Creating an applicant

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

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

Flows allow you to choose what you'd like to screen an applicant for, and which documents you'd like verified. For example, a basic flow you've created may require the applicant to provide one identity document and go through a selfie check.

If you haven't created a Flow yet, create one by going to https://enterprise.personr.co/dashboard/flows before proceeding.

Note that the Names the applicant is created with, is not the details that will be sent for verification later, as this will be extracted from the submitted documents.

The Applicant will be created in the workspace last accessed by the user the token was generated by. Due to this it is recommended if using a service account to not sign in as this user and move between workspaces unless intentional.

---

Create an applicant

POST /api-applicant-create

Create an applicant, ready to be verified.

Headers

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

Body

Name	Type	Description
email	string	The applicant's email address (required)
phone	string	The applicant's phone number (required)
nameFirst	string	The applicant's first name (optional)
nameLast	string	The applicant's last name (optional)
flowName	string	The name of the flow you'd like the applicant to go through (required)
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)

Request

cURL

curl --location 'https://enterprise.personr.co/api/1.1/wf/api-applicant-create' \
--form 'email="[email protected]"' \
--form 'phone="[phone]"' \
--form 'nameFirst="John"' \
--form 'nameLast="Doe"' \
--form 'flowName="KYC basic"' \
--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('email', '[email protected]');
data.append('phone', '[phone]');
data.append('nameFirst', 'John');
data.append('nameLast', 'Doe');
data.append('flowName', 'KYC basic');

var config = {
  method: 'post',
maxBodyLength: Infinity,
  url: 'https://enterprise.personr.co/api/1.1/wf/api-applicant-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("email", "[email protected]");
form.append("phone", "[phone]");
form.append("nameFirst", "John");
form.append("nameLast", "Doe");
form.append("flowName", "KYC basic");

var settings = {
  "url": "https://enterprise.personr.co/api/1.1/wf/api-applicant-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-applicant-create")

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

request = Net::HTTP::Post.new(url)
form_data = [['email', '[email protected]'],['phone', '[phone]'],['nameFirst', 'John'],['nameLast', 'Doe'],['flowName', 'KYC basic']]
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-applicant-create"

payload={'email': '[email protected]',
'phone': '[phone]',
'nameFirst': 'John',
'nameLast': 'Doe',
'flowName': 'KYC basic'}
files=[

]
headers = {}

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

print(response.text)

Response

200

{
  "status": "success",
  "response": {
    "applicantId": "4242424242424x424242424242424242",
    "email": "[email protected]",
    "phone": "[phone]",
    "nameFirst": "John",
    "nameLast": "Doe",
    "flowName": "KYC basic",
    "applicantStatus": "Created"
  }
}

400

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

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