> For the complete documentation index, see [llms.txt](https://manual.personr.co/api-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://manual.personr.co/api-documentation/entities/creating-an-entity.md).

# Creating an entity

Let's create an entity, ready to be verified.

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.

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

<figure><img src="https://2927352434-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyAmEVMxhOOdXgxn7sjnz%2Fuploads%2FRh7yGNaF6xQNyK97SWCo%2FScreenshot%202024-02-27%20at%208.23.14%E2%80%AFpm.png?alt=media&amp;token=53be0794-e396-4c98-8aff-bc95fc3aa102" alt=""><figcaption></figcaption></figure>

The entity is created in the workspace your token belongs to. With a [workspace API key](https://manual.personr.co/api-documentation/getting-started/generating-an-authentication-token.md#workspace-api-keys), that's always the key's workspace. With a personal token, it's whichever workspace the user is currently switched to.

{% hint style="warning" %}
**Creating an entity doesn't start the verification.** After uploading any documents your flow requires, call [Requesting to start the verification process](https://manual.personr.co/api-documentation/entities/requesting-to-start-the-verification-process.md). You need this call even when your flow doesn't ask for documents. The exception is `sendRequest`: when you send the entity an onboarding link, the check starts once they complete it.
{% endhint %}

***

## 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><tr><td><code>email</code></td><td>string</td><td>The email address of the entity's representative <mark style="color:orange;">(optional)</mark></td></tr><tr><td><code>phone</code></td><td>string</td><td>The phone number of the entity's representative <mark style="color:orange;">(optional)</mark></td></tr><tr><td><code>sendRequest</code></td><td>boolean</td><td>Create and send an onboarding link via email and text message <mark style="color:orange;">(optional)</mark></td></tr><tr><td><code>entityType</code></td><td>string</td><td>The entity's type (e.g. Australian Proprietary Company) <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 %}

{% hint style="info" %}
**Trusts.** To verify a trust, super fund or other ABN-only entity, use its 11-digit ABN as `registrationNumber`. These entities can't be found with company search.
{% endhint %}

#### Request

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

```sh
curl --location 'https://enterprise.personr.co/api/1.1/wf/api-entity-create' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--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: { 
    'Authorization': 'Bearer YOUR_TOKEN',
    ...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-entity-create",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  },
  "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)
request["Authorization"] = "Bearer YOUR_TOKEN"
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 = {
  'Authorization': 'Bearer YOUR_TOKEN'
}

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="200 - Flow not found" %}

```json
{
  "status": "error",
  "error": "flow_not_found",
  "message": "No active KYB flow with this flowName exists in the workspace this API user is currently in. API calls always run in the workspace the API user is switched to. Check the flowName, switch the user back to the right workspace, or use that workspace's own API key (Dev Space > Workspace API key).",
  "flowName": "Know Your Busines",
  "workspace": "XYZ Co"
}
```

{% endtab %}
{% endtabs %}

### Flow not found

If no active KYB flow with that `flowName` exists in the workspace the call runs in, no entity is created and you get the `flow_not_found` response above, with HTTP status 200. Check `status` in the body, not just the HTTP status.

The response includes the `flowName` you sent and the `workspace` the call ran in. The usual causes are:

* A typo in `flowName`, or the template name used instead of your flow's name.
* The flow is archived, or isn't a KYB flow.
* The call ran in a different workspace from the one the flow is in. This happens with a personal token when the user has switched workspace. Use a [workspace API key](https://manual.personr.co/api-documentation/getting-started/generating-an-authentication-token.md#workspace-api-keys) to avoid it.

### Next step

The entity is returned with `applicantStatus: Created`. Upload any documents your flow requires, link UBOs if needed, then call [Requesting to start the verification process](https://manual.personr.co/api-documentation/entities/requesting-to-start-the-verification-process.md) to start the verification.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
