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.
Content-Type
multipart/form-data
Authorization
Bearer YOUR_TOKEN
Body
companyName
string
The entity's legal name (required)
registrationNumber
string
The entity's registration, or company number. e.g ACN/ABN for AUS (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)
Request
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?