> For the complete documentation index, see [llms.txt](https://manual.personr.co/api-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://manual.personr.co/api-documentation/entities/requesting-to-start-the-verification-process.md).

# Requesting to start the verification process

After creating an entity (and uploading any documents your flow requires), call this endpoint to start the verification.

Use this endpoint to start verifying an entity you created with `/api-entity-create`. Call it once any required documents have been uploaded and UBOs linked (if necessary).

{% hint style="warning" %}
**This call is required for entities created through the API.** Creating an entity doesn't start the check on its own, even when your flow doesn't ask for documents. Until you call this endpoint, the entity stays at `Created`.
{% endhint %}

{% hint style="warning" %}
Note: You don't need to use this endpoint if you're verifying an entity using a verification link (for example, `sendRequest=true` on [Creating an entity](https://manual.personr.co/api-documentation/entities/creating-an-entity.md)). Verification links submit entities for processing automatically.
{% endhint %}

If your flow requires documents, upload them all before calling this endpoint. Calling it before the required documents are uploaded can lead to improper processing of the entity.

***

## Submit the applicant for processing

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

Start the verification process.

| 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>applicantId</code></td><td>string</td><td>Unique applicantId generated on entity creation <mark style="color:red;">(required)</mark></td></tr></tbody></table>

#### Request

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

```sh
curl --location 'https://enterprise.personr.co/api/1.1/wf/api-request-applicant-check' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--form 'applicantId="4242424242424x424242424242424242"'
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
var axios = require('axios');
var FormData = require('form-data');
var data = new FormData();
data.append('applicantId', '4242424242424x424242424242424242');

var config = {
  method: 'post',
maxBodyLength: Infinity,
  url: 'https://enterprise.personr.co/api/1.1/wf/api-request-applicant-check',
  headers: { 
    'Authorization': 'Bearer YOUR_TOKEN',
    ...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("applicantId", "4242424242424x424242424242424242");

var settings = {
  "url": "https://enterprise.personr.co/api/1.1/wf/api-request-applicant-check",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  },
  "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-request-applicant-check")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer YOUR_TOKEN"
form_data = [['applicantId', '4242424242424x424242424242424242']]
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-request-applicant-check"

payload={'applicantId': '4242424242424x424242424242424242'}
files=[

]
headers = {
  'Authorization': 'Bearer YOUR_TOKEN'
}

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": {
    "response": "success"
  }
}
```

{% endtab %}

{% tab title="200 - Not started" %}

```json
{
  "status": "success",
  "response": {
    "response": "error"
  }
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "statusCode": 400,
    "message": "Error: incorrect applicantId provided"
}
```

{% endtab %}
{% endtabs %}

### Reading the response

Check `response.response`, not just the HTTP status or the top-level `status`.

* `success`: the verification has started. You'll receive the entity result webhook when it's reviewed (usually within a few minutes), and the [ownership ready webhook](https://manual.personr.co/api-documentation/entity-results/retrieving-entity-verification-results/setting-up-a-webhook/ownership-ready-webhook.md) if you've switched it on.
* `error`: the verification didn't start. The usual cause is a flow that requires documents which haven't been uploaded yet. Upload them, then call this endpoint again.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://manual.personr.co/api-documentation/entities/requesting-to-start-the-verification-process.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
