# Creating an applicant

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.

<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&#x26;token=53be0794-e396-4c98-8aff-bc95fc3aa102" alt=""><figcaption></figcaption></figure>

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.&#x20;

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

<mark style="color:green;">`POST`</mark> `/api-applicant-create`

Create an applicant, ready to be verified.

**Headers**

| 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>email</code></td><td>string</td><td>The applicant's email address <mark style="color:red;">(required)</mark></td></tr><tr><td><code>phone</code></td><td>string</td><td>The applicant's phone number <mark style="color:red;">(required)</mark></td></tr><tr><td><code>nameFirst</code></td><td>string</td><td>The applicant's first name <mark style="color:orange;">(optional)</mark></td></tr><tr><td><code>nameLast</code></td><td>string</td><td>The applicant's last name <mark style="color:orange;">(optional)</mark></td></tr><tr><td><code>flowName</code></td><td>string</td><td><p>The name of the flow you'd like the applicant to go through </p><p><mark style="color:red;">(required)</mark></p></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></tbody></table>

#### Request

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

```sh
curl --location 'https://enterprise.personr.co/api/1.1/wf/api-applicant-create' \
--form 'email="johndoe@mail.com"' \
--form 'phone="+61 424 424 424"' \
--form 'nameFirst="John"' \
--form 'nameLast="Doe"' \
--form 'flowName="KYC basic"' \
--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('email', 'johndoe@mail.com');
data.append('phone', '+61 424 424 424');
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);
});
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
var form = new FormData();
form.append("email", "johndoe@mail.com");
form.append("phone", "+61 424 424 424");
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);
});
```

{% endtab %}

{% tab title="Ruby" %}

```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', 'johndoe@mail.com'],['phone', '+61 424 424 424'],['nameFirst', 'John'],['nameLast', 'Doe'],['flowName', 'KYC basic']]
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-applicant-create"

payload={'email': 'johndoe@mail.com',
'phone': '+61 424 424 424',
'nameFirst': 'John',
'nameLast': 'Doe',
'flowName': 'KYC basic'}
files=[

]
headers = {}

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

print(response.text)
```

{% endtab %}
{% endtabs %}

**Response**

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

```json
{
  "status": "success",
  "response": {
    "applicantId": "4242424242424x424242424242424242",
    "email": "johndoe@mail.com",
    "phone": "+61 424 424 424",
    "nameFirst": "John",
    "nameLast": "Doe",
    "flowName": "KYC basic",
    "applicantStatus": "Created"
  }
}
```

{% endtab %}

{% tab title="400" %}

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Remember to input the flow name exactly as you created it. Don't use the template name.
{% endhint %}