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.

---

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 (required)
country	string	The entity's country of incorporation (required).
flowName	string	The name of the flow you'd like the entity to go through (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 (optional)
applicantFlow	string	The name of the KYC flow you'd like automatically-created applicants to be created with (optional)

Use ISO 3166-1 A3 format for 'country' see here for country codes.

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

Request

cURL

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"]'

Node.js

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);
});

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);
});

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

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)

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

Response

200

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

400

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