# Creating an entity

This endpoint allows you to create an entity using a chosen flow that you've created within the platform. 

Flows allow you to choose what you'd like to screen an entity for, which documents you'd like to request, and whether to verify Ultimate Beneficial Owners (UBOs). For example, a Know Your Business flow you've created may require the entity to provide a certificate of incorporation document and send UBOs a verification link.

If you haven't created a Flow yet, create one by going to <https://enterprise.personr.co/dashboard/flows>  and selecting from one of our templates before proceeding.&#x20;

To enable entity verification on your account and custom entity flows, please contact your Account Manager.&#x20;

<figure><img src="/files/pfkP9y0v7hp3WOtKPBAB" alt=""><figcaption></figcaption></figure>

***

## Create an Entity

<mark style="color:green;">`POST`</mark> `/api-entity-create`

Create an entity, ready to be verified.

| Name          | Value                 |
| ------------- | --------------------- |
| Content-Type  | `multipart/form-data` |
| Authorization | `Bearer YOUR_TOKEN`   |

**Body**

<table><thead><tr><th>Name</th><th width="165">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>companyName</code></td><td>string</td><td>The entity's legal name <mark style="color:red;">(required)</mark></td></tr><tr><td><code>registrationNumber</code></td><td>string</td><td>The entity's registration, or company number. e.g ACN/ABN for AUS <mark style="color:red;">(required)</mark></td></tr><tr><td><code>country</code> </td><td>string</td><td>The entity's country of incorporation. (<a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3">ISO-3166 3 char</a>)  <mark style="color:red;">(required).</mark> </td></tr><tr><td><code>flowName</code></td><td>string</td><td><p>The name of the flow you'd like the entity to go through. This is what dictates a registry lookup or UBO details will be searched for.</p><p><mark style="color:red;">(required)</mark></p></td></tr><tr><td><code>uboFlow</code></td><td>string</td><td>The name of the flow you'd like KYC UBOs to be verified on <mark style="color:orange;">(optional)</mark></td></tr><tr><td><code>sourceKey</code></td><td>string</td><td>An internal unique identifier, or source, that you can use to identify where the entity came from, which is returned in all responses <mark style="color:orange;">(optional)</mark> </td></tr><tr><td><code>externalUserId</code></td><td>list</td><td>External identifiers that are returned in all responses <mark style="color:orange;">(optional)</mark> </td></tr><tr><td><code>createApplicant</code></td><td>boolean</td><td>Where applicable, automatically create applicants of identified ownership. Default <code>false</code> <mark style="color:orange;">(optional)</mark></td></tr><tr><td><code>applicantFlow</code></td><td>string</td><td>The name of the KYC flow you'd like automatically-created applicants to be created with <mark style="color:orange;">(optional)</mark></td></tr></tbody></table>

{% hint style="info" %}
`uboFlow` is the name of a KYC (Applicant) flow on your account. If you don't want to verify UBOs, leave this blank.
{% endhint %}

#### Request

{% tabs %}
{% tab title="cURL" %}

```sh
curl --location 'https://enterprise.personr.co/api/1.1/wf/api-entity-create' \
--form 'companyName="Acme Pty Ltd"' \
--form 'registrationNumber="123456789"' \
--form 'country="AUS"' \
--form 'flowName="Know Your Business"' \
--form 'uboFlow="Basic KYC"' \
--form 'sourceKey="Example Source Key"' \
--form 'externalUserId=["UUID1","UUID2"]'
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
var axios = require('axios');
var FormData = require('form-data');
var data = new FormData();
data.append('companyName', 'Acme Pty Ltd');
data.append('registrationNumber', '123456789');
data.append('country', 'AUS');
data.append('flowName', 'Know Your Business');
data.append('uboFlow', 'Basic KYC');

var config = {
  method: 'post',
maxBodyLength: Infinity,
  url: 'https://enterprise.personr.co/api/1.1/wf/api-entity-create',
  headers: { 
    ...data.getHeaders()
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
var form = new FormData();
form.append("companyName", "Acme Pty Ltd");
form.append("registrationNumber", "123456789");
form.append("country", "AUS");
form.append("flowName", "Know Your Business");
form.append("uboFlow", "Basic KYC");

var settings = {
  "url": "https://enterprise.personr.co/api/1.1/wf/api-enity-create",
  "method": "POST",
  "timeout": 0,
  "processData": false,
  "mimeType": "multipart/form-data",
  "contentType": false,
  "data": form
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require "uri"
require "net/http"

url = URI("https://enterprise.personr.co/api/1.1/wf/api-entity-create")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
form_data = [['companyName', 'Acme Pty Ltd'],['registrationNumber', '123456789'],['country', 'AUS'],['flowName', 'Know Your Business'], ['uboFlow', 'Basic KYC']]
request.set_form form_data, 'multipart/form-data'
response = https.request(request)
puts response.read_body
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://enterprise.personr.co/api/1.1/wf/api-entity-create"

payload={'companyName': 'Acme Pty Ltd',
'registrationNumber': '123456789',
'country': 'AUS',
'flowName': 'Know Your Business',
'uboFlow': 'Basic KYC'}

files=[

]
headers = {}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Remember to input the flow name exactly as you created it. Don't use the template name.
{% endhint %}

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "status": "success",
  "response": {
    "applicantId": "4242424242424x424242424242424242",
    "companyName": "Acme Pty Ltd",
    "registrationNumber": "123456789",
    "country": "AUS",
    "flowName": "Know Your Business",
    "applicantStatus": "Created"
  }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "statusCode": 400,
    "message": "Error: Cannot read docSets - incorrect flow name"
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://manual.personr.co/api-documentation/entities/creating-an-entity.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.