Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

The entity is created in the workspace your token belongs to. With a workspace API key, that's always the key's workspace. With a personal token, it's whichever workspace the user is currently switched to.


Create an Entity

POST /api-entity-create

Create an entity, ready to be verified.

Name
Value

Content-Type

multipart/form-data

Authorization

Bearer YOUR_TOKEN

Body

Name
Type
Description

companyName

string

The entity's legal name (required)

registrationNumber

string

The entity's registration, or company number. e.g ACN/ABN for AUS (required)

country

string

The entity's country of incorporation. (ISO-3166 3 char) (required)

flowName

string

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.

(required)

uboFlow

string

The name of the flow you'd like KYC UBOs to be verified on (optional)

sourceKey

string

An internal unique identifier, or source, that you can use to identify where the entity came from, which is returned in all responses (optional)

externalUserId

list

External identifiers that are returned in all responses (optional)

createApplicant

boolean

Where applicable, automatically create applicants of identified ownership. Default false (optional)

applicantFlow

string

The name of the KYC flow you'd like automatically-created applicants to be created with (optional)

email

string

The email address of the entity's representative (optional)

phone

string

The phone number of the entity's representative (optional)

sendRequest

boolean

Create and send an onboarding link via email and text message (optional)

entityType

string

The entity's type (e.g. Australian Proprietary Company) (optional)

uboFlow is the name of a KYC (Applicant) flow on your account. If you don't want to verify UBOs, leave this blank.

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.

Request

Remember to input the flow name exactly as you created it. Don't use the template name.

Response

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 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 to start the verification.

Last updated

Was this helpful?