> For the complete documentation index, see [llms.txt](/llms.txt)
# Getting Started
## Introduction
### What is the Entrust Identity Verification API?
The Entrust Identity Verification (IDV) API lets you integrate and manage identity verification and authentication flows in your application.
Through the endpoints documented here, you can:
* trigger the execution of identity and authentication journeys orchestrated in Workflow Studio
* monitor their progress
* retrieve verification results
* obtain SDK tokens to initialize the Entrust IDV SDKs
### Key API concepts
The essential API building blocks required to create and manage identity verification and authentication workflows include:
* **Creating applicants** – [applicants](#applicants) represent the individuals who are subjects of identity verification workflows
* **Obtaining SDK tokens** – [SDK tokens](#sdk-tokens) are essential for authenticating and initializing the Entrust IDV SDKs
* **Managing workflow runs** – create and initiate [workflow runs](#workflow-runs) for previously orchestrated verification journeys
* **Obtaining verification results** – [retrieve](#retrieve-workflow-run) the results of verification workflows
* **Configuring webhooks** – asynchronously monitor the status of identity verification workflows by configuring [webhook events](#webhooks) to notify you of changes in workflow status
### SDK integration
Entrust highly recommends integration using our SDKs for the capture and upload of document photos and live selfies of applicants. The SDK communicates directly and dynamically with active Studio workflows to create a seamless end-user experience, while our advanced image detection technology ensures the quality of the captured images meets the requirement of Entrust's identity verification process.
While Entrust does allow for direct media upload to Workflow Studio via API, this approach is **not** recommended as it greatly limits the verification products available to you and lacks the image quality control and fraud protection mechanisms offered by our SDKs.
### Where to next?
From here, you're ready to:
* Read our [API quick start guide](#api-quick-start-guide) to set up a simple identity verification flow
* Explore [Workflow Studio](/getting-started/workflow-studio-product/)
* Discover our [core API endpoints](#core-resources)
## API Quick Start Guide
This quick start guide introduces the essential API steps required to create and initialize a simple identity verification flow. The processes described below are foundational to any identity verification, and can be applied to all levels of workflow complexity.
**Important prerequisites**
Before you can begin using the Entrust Identity Verification API, you'll need:
* a registered Entrust account to access the [Entrust Dashboard](https://dashboard.onfido.com/)
* an existing Studio workflow orchestrated in the Workflow Builder. For documentation about Workflow Studio, please refer to our [Studio product guide](/getting-started/workflow-studio-product/)
### Generate an OAuth access token or API token
The Entrust Identity Verification API uses OAuth access and token-based authentication for both its sandbox and live environments.
#### OAuth access tokens
Entrust recommends generating short-lived OAuth access tokens for API authentication using client credentials grant. This authentication method gives you more granular control over the scope of access.
To generate OAuth access token:
* Go to your [Dashboard](https://dashboard.onfido.com/)
* Select **Developers**
* Select **API authentication** and then the **OAuth applications** tab
* Click **Create application**
* Name the application and choose your environment (sandbox or live)
* Select the required scopes and click **Save**
* Copy the `client_secret` that appears in the popup
* Copy the `client_id` that appears for the application you just created
* Generate an OAuth access token using the `client_secret` and `client_id` by making a call to the Generate OAuth access token [API endpoint](#generate-oauth-access-token)
**Please note**: [OAuth access token](#oauth-access-tokens-1) authentication is only available for API v3.6 onwards.
#### API tokens
To alternatively generate API tokens:
* Go to your [Dashboard](https://dashboard.onfido.com/)
* Select **Developers**
* Select **API authentication** and then the **Tokens** tab
* Select **Generate API token**
* Choose **Sandbox** or **Live** from the popup
* Click **Generate**
Make sure you are using the correct API token. Sandbox tokens start with the prefix **api_sandbox**, while live tokens have the prefix **api_live**.
**Please note**: You should never upload confidential information, including personal data, to the sandbox environment. You must never use API tokens in the frontend of your application, or malicious users could discover them in your source code. You should only use them on your server.
### Create an applicant
An identity verification always revolves around an [applicant](#applicants), an individual who is the subject of a verification or authentication check.
At a minimum, the [Create applicant](#create-applicant) API request requires an applicant's first name and last name. However, sample values can be provided if these are not known at the time of applicant creation and can be updated later on.
An example applicant creation request is provided below:
```bash
curl -X POST https://api.eu.onfido.com/v3.6/applicants/ \
-H 'Authorization: Token token=' \
-H 'Content-Type: application/json' \
-d '{
"first_name": "Jane",
"last_name": "Doe"
}'
```
**Please note**: Additional properties can be included in the API request (such as an applicant's address), depending on your specific needs. Including as much accurate applicant information as possible helps you to keep track of your clients, and the data can be used as input for certain workflow tasks in Studio.
The server's response will contain an `id` attribute (the applicant ID), which you'll need for the following steps. Store this `id` against your user for future use.
An example of the server's response is provided below:
```http
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "",
"created_at": "2019-10-09T16:52:42Z",
"sandbox": true,
"first_name": "Jane",
"last_name": "Doe",
"email": null,
"dob": "1990-01-01",
"delete_at": null,
"href": "/v3.6/applicants/",
"id_numbers": [],
"phone_number": "+44 7911 123456",
"address": {
"flat_number": null,
"building_number": null,
"building_name": null,
"street": "Second Street",
"sub_street": null,
"town": "London",
"state": null,
"postcode": "S2 2DF",
"country": "GBR",
"line1": null,
"line2": null,
"line3": null
},
"location": {
"ip_address": "127.0.0.1",
"country_of_residence": "GBR"
}
}
```
### Create a workflow run and obtain an SDK token
For this step, an existing Studio workflow must already be defined in Workflow Builder. For documentation about Workflow Studio, please refer to our [Studio product guide](/getting-started/workflow-studio-product/).
With a valid and active Studio workflow in place, you will then need to create a workflow run by making a call to the [API](#create-workflow-run). At a minimum, you will need to provide a workflow ID (which you can copy and store from your [Studio Dashboard](https://dashboard.onfido.com/studio)), as well as the applicant ID created in the previous step.
The server will return a [workflow run object](#workflow-run-object), which contains a workflow run ID and SDK token in the response:
```http
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": "",
"applicant_id": "",
"workflow_id": "",
"workflow_version_id": 11,
"status": "approved",
"dashboard_url":"https://dashboard.onfido.com/results/"
"output": {"prop1": "val_1", "prop2": 10},
"reasons": ["reason_1", "reason_2"],
"error": null,
"sdk_token": "",
"created_at": "2022-06-28T15:39:42Z",
"updated_at": "2022-07-28T15:40:42Z",
"link": {
"completed_redirect_url": "https://example.onfido.com",
"expired_redirect_url": "https://example.onfido.com",
"expires_at": "2022-10-17T14:40:50Z",
"language": "en_US",
"url": "https://eu.onfido.app/l/"
},
}
```
You will need to store the workflow run ID and SDK token as you will need them to initialize the SDK.
### Initialize the SDK
Entrust's new generation of Identity Verification SDKs provide a common API for initializing SDK sessions across all of our platforms (Android, iOS, Web, React Native and Flutter).
While the overall bootstrapping code is platform-specific, its contents are consistent in their structure and typing. The minimum integration code for the SDK to function requires an SDK token for authentication and the implementation of the three key callbacks that notify the embedding app when the SDK has completed its flow or has encountered errors.
Detailed documentation for SDK initialization can be found [here](/sdk/sdk-integration-guide-2025/#sdk-initialization-and-orchestration).
### Configure webhooks
Entrust provides webhooks to alert you of changes in the status of your verification journeys. These are POST requests to your server that are sent as soon as a specified event occurs. The body of the request (the payload object) contains details of the event.
First, to register new webhooks through your [Dashboard](https://dashboard.onfido.com/):
* Click on **Developers**
* Select the **Webhooks** tab
* Press the **Create webhook** button
In the popup, you can choose which webhook events you want to configure (including `workflow_run.started`, `workflow_run.completed` and `workflow_task.completed`), specifying the URL the webhook events should be sent to, which environment you intend to use (sandbox, live or both) and a name to identify the webhook.
Then, to apply configured webhooks to a specific workflow, open the workflow version in the Workflow Builder. From either the right-hand configuration panel or the Settings menu, click on the Select webhooks tab to choose which ones to apply:
You can also register webhooks programmatically using the [API](#register-webhook).
### Retrieve verification results
The status and results of the identity verifications can be found in the **Results** tab of your [Studio Dashboard](https://dashboard.onfido.com/results).
Alternatively, the results can be obtained programmatically by [retrieving the workflow run](#retrieve-workflow-run), making a call to the Entrust Identity Verification API. The server returns a [workflow run object](#workflow-run-object), with results found in the **status** attribute.
# Overview
> ℹ️ **Note:** **Please note**: If you're migrating and are currently using `api.onfido.com`, please make sure you use `api.eu.onfido.com` with API v3.6.
> You'll find migration guides in the [API section](/api/).
## Request, response format
You should use a `Content-Type: application/json` header with all PUT and POST
requests except when uploading documents or live photos. For these requests,
use a `Content-Type: multipart/form-data` header.
Responses return JSON with a consistent structure, except downloads.
You must make all your requests to the API over HTTPS and TLS 1.2+, with
Server Name Indication enabled. Any requests made over HTTP will fail.
Text fields support UTF-8, but [do not allow certain special
characters](#forbidden-characters).
## Token authentication
The Entrust Identity Verification API uses token-based authentication. Tokens must be included in
the header of all requests made to the API.
You can generate new tokens and find your existing ones in your [Dashboard](https://dashboard.onfido.com/).
You can make requests using sandbox tokens to test our API before you go live.
### OAuth access tokens
You can use OAuth with [client credentials grant](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/) to get short-lived access tokens to access the API.
The access token has a duration of 60 minutes and can be retrieved with a client\_id/client\_secret pair through the [oauth token endpoint](#generate-oauth-access-token).
You can create, edit and delete OAuth applications in your [Dashboard](https://dashboard.onfido.com) and also enforce granular access with [OAuth Scopes](#oauth-scopes).
*Note:* This authentication method is only available in API v3.6 onwards.
> ⚠️ **Warning:** The client\_id/client\_secret pair and access tokens are meant to be used on a machine-to-machine communication scenario.
> You must never use access tokens in the frontend of your application or malicious users could discover them in your source code.
### OAuth access token rotation
We highly recommend that you rotate live OAuth applications when staff members with
access to the client\_id/client\_secret leave your organisation. Consider creating a leaver's
process which covers this.
1. In your [Dashboard](https://dashboard.onfido.com), create a new OAuth application
2. Wherever you use your old client\_id/client\_secret pair, replace it with the new one
3. Confirm your old OAuth application isn't in use
4. Delete your old OAuth application
### API tokens
You can use API tokens to authenticate any API action described in this
documentation.
You can create and revoke API tokens, and see when they were last used, in
your [Dashboard](https://dashboard.onfido.com).
> ⚠️ **Warning:** You must never use API tokens in the frontend of your
> application or malicious users could discover them in your source code. You
> should only use them on your server.
If you do need to collect applicant data in the frontend of your application,
we recommend that you use one of the Entrust Identity Verification SDKs.
You should limit live API token access to only the minimum number
of people necessary, but you can use [sandbox tokens](#sandbox-testing) to
freely experiment with the sandbox API.
Note that there are some [differences between the sandbox and live
APIs](#sandbox-and-live-differences).
You should not embed API tokens in your backend code—even if it’s not
public—because this increases the risk that they will be discovered. Instead,
you should store them in configuration files or environment variables.
Please consider enabling GitHub's [Secret Scanning](https://docs.github.com/en/code-security/secret-scanning/about-secret-scanning) and [Push Protection](https://docs.github.com/en/enterprise-cloud@latest/code-security/secret-scanning/push-protection-for-repositories-and-organizations) feature when hosting your code on GitHub. This will help detect and safeguard API Tokens that could inadvertently be exposed in your repositories.
You should also periodically rotate your live API tokens (see next section).
### API token rotation
We highly recommend that you rotate live API tokens when staff members with
access to those tokens leave your organisation. Consider creating a leaver's
process which covers this.
1. In your [Dashboard](https://dashboard.onfido.com), create a new API token
2. Wherever you use your old API token, replace it with the new one
3. Confirm your old token isn't in use
4. Revoke your old token
Your old API tokens will continue to work until you revoke them, so you can rotate your tokens without users experiencing any downtime.
### SDK tokens
> ⚠️ **Warning:** If you're using the Android SDK at lower than version
> 4.11.0 or the iOS SDK lower than 12.2.0, please update your integration to use a Mobile SDK version which supports SDK tokens.
All of the latest Entrust Identity Verification SDKs authenticate using SDK tokens. You
cannot use an API token to authenticate the SDKs.
An SDK token is restricted to a workflow run, and can be found in the [workflow run API payload](#workflow-run-object).
If you are yet to migrate to Workflow Studio, please contact [Client Support](mailto:identity-client-support@entrust.com) for instructions on how to [manually generate SDK tokens](#generate-sdk-token).
### IP Whitelisting
You can define the list of allowed IPs when using [OAuth authentication](#oauth-access-tokens). The list of IPs can be set per OAuth application in your [Dashboard](https://dashboard.onfido.com).
## Sandbox testing
> ⚠️ **Warning:** You should never upload confidential
> information, including personal data, to the sandbox.
Entrust has a sandbox environment for testing integrations before promoting them to production / live environments.
To use the sandbox, you'll need to generate a sandbox API token in your [Dashboard](https://dashboard.onfido.com/).
All of the API endpoints available in the live environment can be requested and tested in the sandbox. Sandbox results have the same response structures as live requests. You can also be notified of resource status changes via your registered [webhooks](#webhooks).
The sandbox enables you to test:
* your system's network connectivity with the API
* all webhooks are working correctly
* you're posting all required data in the correct format to the API
* you're handling API responses correctly
By default, sandbox API tokens start with `api_sandbox.` and live API tokens
start with `api_live.`. This might vary if you're using a different
[region environment](#regions).
For sandbox requests, the rate limit is 120 requests per minute.
### Sandbox and live differences
The key differences between the sandbox and live environments are:
* sandbox request data is not processed by Entrust services or third parties, meaning that sandbox responses are faster than live responses
* sandbox results are pre-determined
* sandbox applicants are isolated from the live environment\*
* you won't be charged for sandbox test requests
\* applicant notification emails still get sent out to sandbox applicants
### Sample document and photo files
You can use the following sample files with the [upload document](#upload-document) endpoint for running test verification reports:
* [sample\_driving\_licence.png](/images/sample_driving_licence.png)
* [sample\_photo.png](/images/sample_photo.png)
The sandbox API will always return pre-determined responses, regardless of
what files are uploaded.
> **Note:** These files also work for testing the Entrust Identity Verification SDKs.
### Simulating verification reports in the sandbox
To test your integration in the sandbox API, pre-determined responses can be generated for the following report types:
* [Document](#document-report)
* [Driver's License Data Verification](#drivers-license-data-verification-report)
* [Facial Similarity Motion](#facial-similarity-motion)
* [Facial Similarity Photo](#facial-similarity-photo)
* [Facial Similarity Photo Fully Auto](#photo-fully-auto)
* [Facial Similarity Video](#facial-similarity-video)
* [Identity Enhanced](#identity-enhanced-report)
* [Known Faces](#known-faces-report)
* [Proof of Address](#proof-of-address-report)
* [Repeat Attempts](#repeat-attempts-1)
* [Watchlist AML](#watchlist-aml)
* [Watchlist PEPs Only](#watchlist-peps-only)
* [Watchlist Sanctions Only](#watchlist-sanctions-only)
* [Watchlist Standard](#watchlist-standard)
#### Pre-determined 'consider' results
Pre-determined responses can be generated by modifying the `first_name` and `last_name` parameters of the [applicant object](#applicant-object).
Using the [Create Applicant](#create-applicant) API endpoint with a sandbox API token, set the `last_name` parameter to "Consider". Any verification report run against this applicant will return a `consider` response. For any other applicant last name, the response will be `clear`.
Next, [create a workflow run](#create-workflow-run) for an [active workflow](/getting-started/workflow-studio-product/#workflow-versions-and-activation) using your sandbox token and the `applicant_id` for the applicant created using a modified `last_name`.
Lastly, copy the Smart Capture URL from the [link object](#link-object) returned in the Workflow Run API [payload](#workflow-run-object), and paste it into your browser to complete the verification flow. Report results can be found in the `status` attribute returned by the [Retrieve Workflow Run](#retrieve-workflow-run) endpoint.
### [Simulating Document reports in the sandbox](#simulating-document-reports-in-the-sandbox)
The sandbox API supports additional functionality for testing Document reports. Pre-determined responses can be triggered for specific:
* [breakdowns and sub-breakdowns](#pre-determined-breakdowns-document)
* [document types](#pre-determined-document-types)
* [sub-results](#pre-determined-sub-results)
For Document reports, `first_name` and `last_name` must be provided when creating an applicant (even in the Sandbox).
#### [Breakdowns and sub-breakdowns](#pre-determined-breakdowns-document)
You can trigger pre-determined responses for particular breakdowns and sub-breakdowns for sandbox Document reports. These responses show possible breakdown and sub-breakdown combinations that can be flagged for a `consider` report result.
To test Document report breakdown and sub-breakdown combinations, [create an applicant](#create-applicant) and set the `first_name` parameter to the "breakdown - sub-breakdown" combination you intend to trigger.
The following combinations are supported:
* `"Image Integrity - Supported Document"`
* `"Image Integrity - Image Quality"`
* `"Visual Authenticity - Fonts"`
* `"Visual Authenticity - Security Features"`
* `"Visual Authenticity - Face Detection"`
* `"Data Validation - Document Numbers"`
* `"Data Consistency - Document Type"`
Passing a `first_name` option to generate a Document report pre-determined response will override any conflicting option passed to the applicant's `last_name`.
> **Note:** You can also include a document type by specifying `last_name` as a supported
> sandbox document type during applicant creation (refer to the next section).
#### [Pre determined document types](#pre-determined-document-types)
You can trigger responses for particular document types for sandbox Document reports, which include the specific `properties` for the associated document type.
To test different document types, [create an applicant](#create-applicant) and set the `last_name` parameter to the document type you intend to test.
The sandbox supports the following document type options:
| Sandbox option | Sandbox option \* | Document type \*\* |
| ------------------- | ------------------------------------------------------------------ | ------------------------------------------- |
| `"CA DL 2018"` | `"CA DL 2018 front only"` | US drivers license for California state |
| `"NY DL 2017"` | `"NY DL 2017 front only"` | US drivers license for New York state |
| `"Ontario ID 2010"` | - | Canadian national identity card for Ontario |
| `"FRA ID 1994"` | `"FRA ID 1994 front only"` and `"FRA ID 1994 front only rejected"` | French identity card |
\* Specifying "front only" means only data contained on the front side of the document will be returned in the `properties`.
\*\* The document type `properties` returned are specific to the document version supported in Sandbox.
> **Note:** You can also trigger a flagged "breakdown - sub-breakdown" combination by
> specifying `first_name` as a supported combination during applicant creation (refer to the previous section).
#### [Sub-results](#pre-determined-sub-results)
You can trigger responses for [particular sub-results](#sub-results) for
sandbox Document reports, showing possible individual breakdown results which can lead to different sub-results.
To do this, [create an applicant](#create-applicant) and set the `last_name` parameter to one of the following strings:
* `"clear"`
* `"rejected"`
* `"suspected"`
* `"caution"`
> ⚠️ **Warning:** When testing sub-results, you cannot specify a document type.
After creating an applicant to test the specific functionalities of a Document report described above (breakdowns and sub-breakdowns, document types or sub-results), you can use the `applicant_id` to create a workflow run to generate a pre-determined response as described above.
### [Simulating Facial Similarity reports in the sandbox](#simulating-facial-similarity-reports-in-the-sandbox)
The sandbox API supports additional functionality for testing breakdowns and sub-breakdowns for Facial Similarity Photo, Photo Fully Auto, Video and Motion reports.
For Facial Similarity reports, `first_name` and `last_name` must be provided when creating an applicant (even in the Sandbox).
#### [Breakdowns and sub-breakdowns](#pre-determined-breakdowns-facial-sim)
You can trigger pre-determined responses for [particular breakdowns and sub-breakdowns](#facial-similarity-photo-object) for sandbox Facial Similarity reports. These responses show possible breakdown and sub-breakdown combinations that can be flagged for a `consider` report result.
To test Facial Similarity report breakdown and sub-breakdown combinations, [create an applicant](#create-applicant) and set the `first_name` parameter to the "breakdown - sub-breakdown" combination you intend to trigger.
The following combinations are supported:
* `"Visual Authenticity - Spoofing Detection"`
* `"Face Comparison - Face Match"`
* `"Image Integrity - Source Integrity"`
* `"Image Integrity - Face Detected"`
After creating an applicant, you can use the `applicant_id` to create a workflow run to generate a pre-determined response as described above.
> ⚠️ **Warning:** Applicant IDs returned in the response don't map to actual sandbox applicants, they are example uuids to represent the applicant ID field. As a result, there is no associated applicant data.
### [Pre-determined responses for Repeat Attempts](#pre-determined-responses-for-repeat-attemptss)
The sandbox API supports additional functionality for testing breakdowns and sub-breakdowns for [Repeat Attempts](#repeat-attempts-1).
To help you integrate with this service, you can generate pre-defined Repeat Attempts responses. Depending on the scenario you are trying to test, you can use one of seven possible keywords as the `report_uuid` in the request URL:
* `match`
* `mismatch`
* `error`
* `empty`
* `document_known_faces_pii_match_face_match`
* `document_known_faces_pii_mismatch_face_match`
* `document_known_faces_pii_match_face_mismatch`
Below is a pre-determined response example for a Repeat Attempts match:
```json
{
"report_id": "00000000-0000-0000-0000-000000000000",
"repeat_attempts": [
{
"report_id": "00000000-0000-0000-0000-000000000001",
"applicant_id": "00000000-0000-0000-0000-000000000003",
"date_of_birth": "match",
"names": "match",
"result": "clear",
"created_at": "2022-01-06T14:46:43Z",
"completed_at": "2022-01-06T15:46:43Z"
},
{
"report_id": "00000000-0000-0000-0000-000000000002",
"applicant_id": "00000000-0000-0000-0000-000000000003",
"date_of_birth": "match",
"names": "match",
"result": "clear",
"created_at": "2022-02-18T03:09:34Z",
"completed_at": "2022-02-18T03:10:34Z"
}
],
"attempts_count": 3,
"attempts_clear_rate": 1,
"unique_mismatches_count": 0
}
```
Below is a pre-determined response example for a Document Known Faces match:
```json
{
"report_id": "00000000-0000-0000-0000-000000000000",
"repeat_attempts": [
{
"report_id": "00000000-0000-0000-0000-000000000001",
"applicant_id": "00000000-0000-0000-0000-000000000003",
"date_of_birth": "match",
"names": "match",
"document_number": "match",
"face": "match",
"result": "clear",
"created_at": "2022-01-06T14:46:43Z",
"completed_at": "2022-01-06T15:46:43Z"
},
{
"report_id": "00000000-0000-0000-0000-000000000002",
"applicant_id": "00000000-0000-0000-0000-000000000003",
"date_of_birth": "match",
"names": "match",
"document_number": "match",
"face": "match",
"result": "clear",
"created_at": "2022-02-18T03:09:34Z",
"completed_at": "2022-02-18T03:10:34Z"
}
],
"attempts_count": 3,
"attempts_clear_rate": 1,
"unique_mismatches_count": 0
}
```
Below is a pre-determined response example for a Document Known Faces mismatch:
```json
{
"report_id": "00000000-0000-0000-0000-000000000000",
"repeat_attempts": [
{
"report_id": "00000000-0000-0000-0000-000000000001",
"applicant_id": "00000000-0000-0000-0000-000000000003",
"date_of_birth": "mismatch",
"names": "mismatch",
"document_number": "mismatch",
"face": "match",
"result": "consider",
"created_at": "2022-01-06T14:46:43Z",
"completed_at": "2022-01-06T15:46:43Z"
},
{
"report_id": "00000000-0000-0000-0000-000000000002",
"applicant_id": "00000000-0000-0000-0000-000000000003",
"date_of_birth": "mismatch",
"names": "mismatch",
"document_number": "mismatch",
"face": "match",
"result": "consider",
"created_at": "2022-02-18T03:09:34Z",
"completed_at": "2022-02-18T03:10:34Z"
}
],
"attempts_count": 3,
"attempts_clear_rate": 0,
"unique_mismatches_count": 2
}
```
Below is a pre-determined response example for a Document Known Faces mismatch (when PII matches and face mismatches):
```json
{
"report_id": "00000000-0000-0000-0000-000000000000",
"repeat_attempts": [
{
"report_id": "00000000-0000-0000-0000-000000000001",
"applicant_id": "00000000-0000-0000-0000-000000000003",
"date_of_birth": "match",
"names": "match",
"document_number": "match",
"face": "mismatch",
"result": "consider",
"created_at": "2022-01-06T14:46:43Z",
"completed_at": "2022-01-06T15:46:43Z"
},
{
"report_id": "00000000-0000-0000-0000-000000000002",
"applicant_id": "00000000-0000-0000-0000-000000000003",
"date_of_birth": "match",
"names": "match",
"document_number": "match",
"face": "mismatch",
"result": "consider",
"created_at": "2022-02-18T03:09:34Z",
"completed_at": "2022-02-18T03:10:34Z"
}
],
"attempts_count": 3,
"attempts_clear_rate": 1,
"unique_matches_count": 0
}
```
### Sandbox testing with Profile Data Capture tasks
Studio workflows that start with a [Profile Data Capture task](/getting-started/workflow-studio-product/#profile-data-capture-task) must be handled differently when sandbox testing. As all of the fields in a Profile Data Capture task have a limit of 32 characters, the number of report scenarios that can be simulated is restricted.
After building and activating a valid workflow starting with a Profile Data Capture task, click "Share Smart Capture Link" on the workflow versions page in your [Dashboard](https://dashboard.onfido.com/), copy the Sandbox link and paste it into your browser and complete the journey.
The breakdown and sub-breakdown combinations that can be tested for Document reports using workflows starting with a Profile Data Capture task by modifying the `first_name` parameter of the applicant include:
* `"Image Integrity - Image Quality"`
* `"Visual Authenticity - Fonts"`
* `"Data Consistency - Document Type"`
The breakdown and sub-breakdown combinations that can be tested for Facial Similarity reports using workflows starting with a Profile Data Capture task by modifying the `first_name` parameter of the applicant include:
* `"Face Comparison - Face Match"`
* `"Image Integrity - Face Detected"`
### Sandbox testing for API generated reports
For those not integrating using Workflow Studio, and instead generating verification reports using our [checks](#checks) and [reports](#reports) API endpoints, sandbox testing works slightly differently.
After [creating an applicant](#create-applicant) with a sandbox token and modified `first_name` and `last_name` parameters to test the various scenarios outlined above, you can use the `applicant_id` to [create a check](#create-check) for the desired report.
The pre-determined sandbox results can be retrieved by making a [Retrieve report](#retrieve-report) call to the Entrust Identity Verification API.
#### Pre-determined 'consider' and 'clear' results
To test multiple different sandbox report responses simultaneously, you can pass specific report
types to the `consider` parameter (in an array) when making a [Create check](#create-check) API call.
Only the reports specified in the `consider` array will
return a `consider` report result. All other reports in the check will return a `clear` result.
## [Postman collection](#postman)
You can run our API version 3.6 collection in Postman:
In your Postman environment, you will need to define the `apiToken` environment variable and configure the `region` variable for the `baseUrl` should you wish to designate a region other than the default `eu`. Please refer to our [regions documentation](#regions) for `baseUrl` options.
You can read more in Postman's documentation about [managing environments](https://learning.getpostman.com/docs/postman/environments_and_globals/manage_environments/).
## Go live
Before you go live, you may find the introductory guides in our [Getting
Started section](/getting-started) useful.
## [API client libraries](#client-libraries)
You can use our officially supported client libraries to integrate with the Entrust Identity Verification API.
| Language | Library | Notes |
| -------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Ruby | [onfido-ruby](https://github.com/onfido/onfido-ruby) | |
| Java | [onfido-java](https://github.com/onfido/onfido-java) | |
| Node.js | [onfido-node](https://github.com/onfido/onfido-node) | Also supports TypeScript. |
| Python | [onfido-python](https://github.com/onfido/onfido-python) | |
| PHP | [api-php-client](https://github.com/onfido/api-php-client) | Made with [OpenAPI generator](https://github.com/OpenAPITools/openapi-generator). |
Refer to our [API versioning guide](/api/api-versioning-policy#client-libraries) for details on client library versioning.
Please email the [Customer Support team](mailto:identity-support@entrust.com) if you have written your own
library and want us to link to it.
### OpenAPI specification
We use [an OpenAPI
specification](https://github.com/onfido/onfido-openapi-spec) to generate our
PHP library, which we also host publicly.
For any custom libraries you generate yourself with this specification, we
can only provide support on a best-effort basis.
## Rate limits
The Entrust Identity Verification API enforces a maximum volume of requests per second for all clients. Unless contractually agreed otherwise, the maximum rate is 400 requests per minute (up to 7 requests per second with a burst of 14 requests).
For sandbox requests, the rate limit is 120 requests per minute (up to 2 requests per second with a burst of 4 requests).
Entrust uses the token bucket algorithm to handle usage.
Any request over the limit will return a `429 Too Many Requests` error.
## Regions
> ℹ️ **Note:** There is no default region in API v3.6. If you were previously using `api.onfido.com`, you should use `api.eu.onfido.com` with v3.6.
We offer region-specific environments: EU, US, and Canada. You can use these to store the data in your account at rest within a
specific geographic region.
Regions have unique base URLs and API token formats for both live and sandbox environments.
| Region | Notes | API base URL | API token format |
| ------ | -------------------------------------------------------------------------------- | ---------------------------- | -------------------------------------------------------------- |
| EU | Replaces `api.onfido.com` for EU region in v3.1, v3.2, v3.3, v3.4, v3.5 and v3.6 | `https://api.eu.onfido.com/` | Tokens are prepended with `api_live.` and `api_sandbox.` |
| US | | `https://api.us.onfido.com/` | Tokens are prepended with `api_live_us.` and `api_sandbox_us.` |
| CA | | `https://api.ca.onfido.com/` | Tokens are prepended with `api_live_ca.` and `api_sandbox_ca.` |
Unless specified, all examples in the documentation refer to the `https://api.eu.onfido.com/` base URL and token format.
For the EU region, data is physically stored in the Republic of Ireland, with backup storage in Germany.
If you're using one of the officially supported [API client libraries](#client-libraries),
follow that library's GitHub documentation to change the region.
## Versioning policy
Refer to our [API versioning guide](/api/api-versioning-policy/) for details on Entrust's versioning policy.
## Changelog
| Date | Description |
| ---------- | ---------------------------------------------------------------------------------------- |
| 2023-01-24 | General release of API version 3.6. Please see our [release notes](/api/release-notes/). |
## Upcoming maintenance
> ℹ️ **Note:** There's currently no scheduled maintenance.
## Errors
All errors are returned with the same structure:
```json
{
"error": {
"type": ,
"message": ,
"fields":
}
}
```
### Example error object
| Attribute | Description |
| --------- | --------------------------------------------------------------------------------------------------- |
| type | **string**
The type of error returned. |
| message | **string**
A human-readable message giving more details about the error. |
| fields | **object**
The invalid fields and their associated errors. Only applies to validation errors. |
### Error codes and what to do
| Status | Action |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **400 bad\_request** | Make sure your request is formatted correctly. |
| **400 incorrect\_base\_url** | Please use api.eu.onfido.com for API v3.1 onwards if you were previously using api.onfido.com. |
| **401 authorization\_error** | Make sure you've entered your API token correctly.> **Note:** The Entrust Identity Verification SDKs use [SDK tokens](#sdk-tokens) for authentication, not API tokens. If you're receiving a 401 error on one of our SDKs, check you've entered a valid application ID when [generating the SDK token](#generate-sdk-token). |
| **401 user\_authorization\_error** | Contact an administrator about user permissions. |
| **401 bad\_referrer** | Check the referrer used to generate the [SDK token](#generate-sdk-token). |
| **401 expired\_token** | Request a new [SDK token](#generate-sdk-token). |
| **403 account\_disabled** | Please contact [identity-client-support@entrust.com](mailto:identity-client-support@entrust.com). |
| **403 trial\_limits\_reached** | Please contact [identity-client-support@entrust.com](mailto:identity-client-support@entrust.com). |
| **403 disabled\_endpoint** | The API endpoint is disabled for your account. Please contact [identity-client-support@entrust.com](mailto:identity-client-support@entrust.com). |
| **404 resource\_not\_found** | Make sure you've formatted the URI correctly. |
| **410 gone** | The resource has been deleted or is scheduled for deletion. |
| **422 validation\_error** | Check the `fields` property for a specific error message. |
| **422 missing\_billing\_info** | Make sure you've provided your billing information before starting a check. |
| **422 missing\_documents** | Make sure you've [uploaded the required documents](#upload-document) before starting a check. |
| **422 missing\_applicant\_location** | Make sure you've provided the applicant's [location](#location-create-applicant) before starting a check |
| **422 missing\_applicant\_provided\_consents** | Make sure you've provided the required [consents](#consents) |
| **422 invalid\_reports\_names** | Make sure you've entered the report name(s) in the correct format (string). |
| **422 missing\_id\_numbers** | Make sure you've supplied all required ID numbers. |
| **422 report\_names\_blank** | Make sure you've specified `report_names` in your request. |
| **422 report\_names\_format** | `report_names` must be an array of strings, not an array of objects. |
| **422 deprecated\_reports** | The requested reports have been deprecated. |
| **422 check\_type\_deprecated** | `type` is not used in this version of the API. Please read about the [`applicant_provides_data`](#applicant-provides-data) feature. |
| **422 document\_ids\_with\_unsupported\_report** | You should only specify the optional `document_ids` argument when creating a check containing a [Document report](#document-report) or a [Facial Similarity report](#facial-similarity-reports), or both. |
| **422 facial\_similarity\_photo\_without\_document** | For `applicant_provides_data` checks, [Facial Similarity reports](#facial-similarity-reports) must be paired with a [Document report](#document-report). |
| **422 facial\_similarity\_video\_not\_supported** | The [Facial Similarity Video](#facial-similarity-video) report is not supported for checks where [`applicant_provides_data`](#applicant-provides-data) is `true`. |
| **422 failed\_check\_requirements** | Check that all required information has been provided and correctly specified. |
| **422 incomplete\_checks** | Check cannot be completed as there are other ongoing checks associated with this applicant. |
| **422 deletion\_incomplete\_checks** | Applicants with checks in progress cannot be deleted. |
| **422 disabled\_reports** | There are reports disabled in your account. Please contact [identity-client-support@entrust.com](mailto:identity-client-support@entrust.com). |
| **422 too\_many\_checks** | You have exceeded the limit of 1000 checks for the given applicant. |
| **422 deletion\_applicant\_on\_hold** | The applicant cannot be deleted because a deletion hold is present. |
| **429 rate\_limit** | The [rate limit](#rate-limits) has been reached. Please try again later. |
| **500 internal\_server\_error** | The server encountered an error. If this persists, please contact [identity-client-support@entrust.com](mailto:identity-client-support@entrust.com). |
# Identity Lifecycle Endpoints
The endpoints documented in this section enable you to manage the end-to-end identity verification process, from Workflow Run [creation](#create-workflow-run) to the retrieval of Workflow Run [results](#retrieve-workflow-run). These also include defining and managing records of the individuals undergoing verification (your applicants), as well as all aspects involved in executing and managing instances of identity verification workflows orchestrated in the Studio Workflow Builder.
## Applicants
An applicant represents an individual who will be the subject of an identity verification check. Creating an applicant is the first step towards initiating a verification check, and without an applicant a check cannot be completed.
There are different minimum requirements for applicant data and recommended applicant data, depending on the type of identity verification flow. This information is documented for each of our verification reports.
If you are orchestrating multiple verification journeys for the same individual, you should reuse the `id` returned in the initial [applicant response object](#applicant-object) in the `applicant_id` field when creating a check.
### Applicants with Sanctioned Documents
If an applicant uploads a [document](#documents) which is issued by a country subject to comprehensive US sanctions (list of countries [here](https://support.identity.entrust.com/s/article/Documents-Issued-by-US-Sanctioned-Countries-FAQs)), any reports run with that applicant will return a `withdrawn` [status](#report-status) unless otherwise specified in the report documentation. Current exceptions to this are the [Document](#document-report) and [Facial Similarity](#facial-similarity-reports) reports, which will still run but return a result indicating the presence of a sanctioned document.
### Applicant object
| Attribute | Description |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| id | **string**
The unique identifier for the applicant. |
| created\_at | **datetime**
The date and time when this applicant was created. |
| delete\_at | **datetime**
The date and time when this applicant is scheduled to be deleted, or `null` if the applicant is not scheduled to be deleted. |
| href | **string**
The URI of this resource. |
| first\_name | **string**
The applicant's first name. |
| last\_name | **string**
The applicant's surname. |
| email | **string**
The applicant's email address. |
| dob | **date**
The applicant's date of birth in YYYY-MM-DD format. |
| id\_numbers | **array of [id number](#id-number-object) objects**
A collection of identification numbers belonging to this applicant. |
| address | **[address](#address-object) object**
The address of the applicant. |
| sandbox | **Boolean**
Indicates whether the object was created in the sandbox or not. |
| location | **[location](#location-object) object**
The location/country of residence of the applicant. |
| phone\_number | **string**
The applicant's phone number with country code. |
#### ID number object
The ID number array of objects is nested inside the applicant object.
| Attribute | Description |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type | **string**
Type of ID number. Valid values are `ssn`, `social_insurance` (e.g. UK National Insurance), `tax_id`, `identity_card`, `driving_license`, `driving_licence`, `share_code`, `voter_id`, `passport` and `other` (e.g. AUS Foreign Passport). |
| value | **string**
Value of ID number. `ssn` supports both the full SSN or the last 4 digits. If the full SSN is provided then it must be in the format `xxx-xx-xxxx`. |
| state\_code | **string**
Two letter code of issuing state (state-issued driving licences only). |
**Note:** `driving_license` is the preferred spelling (rather than using `driving_licence`) for Studio workflow runs in order to keep consistency with [custom input data](/api/latest/#custom-input-data), but both have the same effect.
#### Address object
The applicant address object is nested inside the applicant object.
| Attribute | Description |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| flat\_number | **string**
The flat number. |
| building\_number | **string**
The building number. |
| building\_name | **string**
The building name. |
| street | **string**
The street of the applicant's address. There is a 32-character limit on this field for UK addresses. |
| sub\_street | **string**
The sub-street. |
| town | **string**
The town. |
| state | **string**
The address state. US states must use the USPS abbreviation (see also [ISO 3166-2:US](https://www.iso.org/obp/ui/#iso:code:3166:US)), for example `AK`, `CA`, or `TX`. |
| postcode | **string**
The postcode (ZIP code) of the applicant's address. For UK postcodes, specify the value in the following format: `SW4 6EH`. |
| country | **string**
The 3 character ISO country code of this address. For example, `GBR` is the country code for the United Kingdom. |
| line1 | **string**
Line 1 of the address. |
| line2 | **string**
Line 2 of the address. |
| line3 | **string**
Line 3 of the address. |
`postcode` and `country` are required fields if an address is provided for an
applicant. For US addresses, `state` is also a required field.
Most addresses will contain information such as `flat_number`. Make sure they
are supplied as separate fields, and do not try and fit them all into the
`street` field. Doing so is likely to affect check performance.
Alternatively, you can provide addresses in the form `line1`, `line2` and
`line3` if you're creating a check with an [Identity
Enhanced](#identity-enhanced-report) report. If you provide address data in
this form, Entrust uses a third-party subprocessor for address cleansing.
#### Location object
The location object is nested inside the applicant object.
| Attribute | Description |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| ip\_address | **string**
The IP address of the applicant. |
| country\_of\_residence | **string**
The 3 character ISO country code of the country where the applicant resides. |
If `country_of_residence` is not provided in the request, it will be inferred from the IP address which may result in an incorrect value.
If you submitted `location` during [document upload](#document-upload), it will not be returned here.
**Note:** `location` refers to the applicant's country of residence, not their nationality or place of birth.
#### Forbidden characters
For addresses the following characters are forbidden:
`!$%^*=<>`
For names the following characters are forbidden:
`^!#$%*=<>;{}"`
### Create applicant
`POST /v3.6/applicants/`
> ⚠️ **Warning:** Using this endpoint in a live context will cause you to
> send personal data to Entrust. Always make sure you inform your users about this
> and obtain any necessary permissions. For more information on how Entrust uses
> personal data, view our [Privacy Policy](https://onfido.com/privacy/).
Creates a single applicant. Returns an [applicant
object](#applicant-object).
When you create an applicant, [some characters are
forbidden](#forbidden-characters). You should remove any duplicate whitespaces before creating an applicant, otherwise this may result in a [data comparison](#data_comparison) failure.
The minimum requirements for applicant data and recommended applicant data will vary, depending on the type of identity verification.
#### [Request body parameters](#create-applicant-request-body)
| Parameter | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| first\_name | **required**
The applicant's forename. |
| last\_name | **required**
The applicant's surname. |
| email | **required only if creating a check where [`applicant_provides_data`](#applicant-provides-data) is `true`**
The applicant's email address. |
| dob | **optional**
The applicant's date of birth in YYYY-MM-DD format. |
| id\_numbers | **optional**
A collection of identification numbers belonging to this applicant. |
| address | **optional**
The address of the applicant. |
| phone\_number | **optional**
The applicant's phone number with country code. |
| location | **optional**
An object that contains the location/country of residence of the applicant. |
| consents | **optional**
An array of objects indicating whether consent has been given by the applicant. |
#### [location](#location-create-applicant)
> ⚠️ **Warning:** You must provide `location` for every applicant. If you do not, all checks with either a Document, Facial Similarity or Known Faces report will fail with a validation error.
You must provide location information for each end user as this determines the necessary consent required in order to process a verification.
You can specify either or both the IP address and the country of residence (3 character ISO country code) of the applicant in the `location` object.
```bash
...
"location": {
"ip_address": "127.0.0.1",
"country_of_residence": "GBR"
}
...
```
You can also provide location information during [document upload](#upload-document).
If you submit location information in multiple requests, the document upload location will take precedence.
> ℹ️ **Note:** If you use the Entrust Identity Verification SDK, location is provided directly by the SDK. You do not need to manually submit the `location` parameter in this case.
#### consents
Where required, you must collect end user consent before creating a check. If you do not, Entrust is unable to process an applicant's data and complete a verification.
Exact consent requirements are linked to the location of the end user and the report type. You must specify an applicant's location in the [`location`](#location-create-applicant) parameter when [creating an applicant](#create-applicant) or [uploading a document](#document-upload).
* **`privacy_notices_read`**
End users located in the United States, must read the Privacy Notices and Terms of Service before giving consent.
`granted` should be set to `true` after gaining the necessary consent from the applicant. If it's set to `false`, or the parameter is not provided, all [check creation](#create-check) requests will fail with a validation error.
> **Note:** For more information on the requirements and implementation options for collecting US end user consent, please see our [Privacy notices and consent guide](/guide/onfido-privacy-notices-and-consent/).
* **`ssn_verification`**
End users must give consent to process their Social Security Number (SSN) before you can submit an [Identity Enhanced report](#identity-enhanced-report).
`granted` should be set to `true` after gaining the necessary consent from the applicant. If it's set to `false`, or the parameter is not provided, SSN reports will fail with a validation error.
```bash
...
"consents": [
{
"name": "privacy_notices_read",
"granted": true
},
{
"name": "ssn_verification",
"granted": true
}
]
...
```
You can also provide `consents` when [updating an applicant](#update-applicant).
> ℹ️ **Note:** If you use the Entrust Identity Verification SDK, consent is collected directly by the SDK. The SDK contains a mandatory consent screen which the end user must accept in order to proceed. You do not need to manually provide the `consents` parameter in this case.
### Retrieve applicant
`GET /v3.6/applicants/{applicant_id}`
Retrieves a single [applicant](#applicants). Returns an [applicant
object](#applicant-object).
### Update applicant
`PUT /v3.6/applicants/{applicant_id}`
> ⚠️ **Warning:** Using this endpoint in a live context will cause you to
> send personal data to Entrust. Always make sure you inform your users about this
> and obtain any necessary permissions. For more information on how Entrust uses
> personal data, view our [Privacy Policy](https://onfido.com/privacy/).
Updates an applicant's information. Returns the updated [applicant
object](#applicant-object).
- Partial updates are valid
- Addresses and ID numbers present will replace existing ones
- Takes the same request body parameters as creating an applicant
- Applicant details can be updated between check creations
### Delete applicant
`DELETE /v3.6/applicants/{applicant_id}`
Deletes a single applicant. If successful, returns a `204 No Content` response.
Sending a deletion request adds the applicant object and all associated
documents, photos, videos, checks, reports and analytics data to our deletion
queue. The objects will be permanently deleted from Entrust's production object
storage and relational database system after a deletion delay which can be
configured by emailing our [client support team](mailto:identity-client-support@entrust.com).
After deletion, applicant details cannot be recovered or queried, and Entrust
will not be able to troubleshoot. Within the delay period, the applicant can
be restored. For more information about Entrust's deletion service, see our
[Data Deletion
FAQ](https://support.onfido.com/hc/en-us/sections/360003412494-Data-Deletion).
Once deleted, Entrust will not be able to carry out any troubleshooting or
investigate any queries raised by the client. It is for this reason we
recommend a longer deletion period, for example, a minimum of thirty days.
### Restore applicant
`POST /v3.6/applicants/{applicant_id}/restore`
Restores a single applicant scheduled for deletion. If successful, returns a `204 No Content` response.
A restore request will also restore all associated documents, photos, videos, checks, reports and analytics data.
Applicants that have been permanently deleted cannot be restored.
### List applicants
`GET /v3.6/applicants/`
Lists all applicants you've created, sorted by creation date in descending
order. Returns data in the form: `{"applicants": []}`.
Requests to this endpoint will be paginated to 20 items by default.
#### [Query string parameters](#list-applicants-query-string-parameters)
`include_deleted=true` (optional): include applicants scheduled for deletion.
`per_page` (optional): set the number of results per page (500 at maximum). Defaults to 20.
`page` (optional): return specific pages. Defaults to 1.
#### Link header
The `Link` header contains pagination information. For example:
`Link: [https://api.eu.onfido.com/v3.5/applicants?page=3059](https://api.eu.onfido.com/v3.5/applicants?page=3059); rel="last", [https://api.eu.onfido.com/v3.5/applicants?page=2](https://api.eu.onfido.com/v3.5/applicants?page=2); rel="next"`
Possible `rel` values are:
| Name | Link relation (description) |
| ------- | --------------------------- |
| `next` | Next page of results. |
| `last` | Last page of results. |
| `first` | First page of results. |
| `prev` | Previous page of results. |
The custom `X-Total-Count` header gives the total resource count.
### List applicant consents
`GET /v3.6/applicants/{applicant_id}/consents`
Lists all available consents for a specific applicant. Returns data in an array of consent objects, in the form:
`[{consent_1},{consent_2},{consent_3}]`.
Each consent object has the following attributes:
| Name | Description |
| ----------- | --------------------------------------------------------------------------------------------------------------------- |
| name | **string**
The name of the consent granted. |
| granted | **Boolean**
Indicates whether consent was granted. |
| granted\_at | **datetime**
The date and time at which the consent was granted. Has a value of `null` if `granted` is `false`. |
#### [Path parameters](#list-applicant-consents-path-parameters)
`applicant_id` (required): the unique identifier (UUID) of the applicant.
## Workflow Runs
Workflows are the container for how the end user will be verified using interactive and non-interactive tasks as configured
using Workflow Studio via the [Dashboard](https://dashboard.onfido.com/studio). Workflow Runs are individual instances of the Workflow,
and each Workflow Run requires data in order for it to execute.
The required Workflow Run data will be based on how the Workflow is configured in Workflow Studio. Data can either be provided through the
[Applicant Object](#applicant-data) and/or through the [Custom Input Data Object](#custom-input-data).
#### Workflow Run Versions
Workflows are version controlled, meaning everytime a Workflow is edited and saved a new version is created.
The active version of the Workflow will be used during the creation of a Workflow Run. Workflow Runs can only
be created against the active version of the Workflow. The active version of a workflow can be designated in Studio
via the Dashboard.
#### Workflow Run Status
Workflow Runs are transitioned through statuses as the Applicant progresses through the tasks. These statuses are visible
on the Dashboard and available via the [Retrieve Workflow Run endpoint](#retrieve-workflow-run).
| Workflow Status | Description |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| awaiting\_input | When the Workflow is waiting for an Applicant to complete a Smart Capture SDK interactive task.
Note: If your Workflow has parallel tasks, `awaiting_input` will take precedence over `processing`. |
| awaiting\_client\_input | Certain tasks are completed by the workflow (such as Send/Receive Data tasks), but are waiting for a customer response. |
| processing | When the Workflow is processing non-interactive tasks. |
| abandoned | When an interactive task is not completed by the applicant and the workflow run expires. |
| error | The Workflow ended due to a technical issue during run time. |
| approved | The Workflow Run reached an end task of ‘Approve Applicant’ based on the Workflow configuration. |
| review | The Workflow Run reached an end task of ‘Review Applicant’ based on the Workflow configuration. |
| declined | The Workflow Run reached an end task of ‘Decline Applicant’ based on the Workflow configuration. |
### Workflow Run object
| Attribute | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | **string (UUID)**
The unique identifier for the Workflow Run. |
| applicant\_id | **string (UUID)**
The unique identifier for the Applicant. |
| workflow\_id | **string (UUID)**
The unique identifier for the Workflow. |
| workflow\_version\_id | **int**
The identifier for the Workflow Version. |
| dashboard\_url | **string**
The URL for viewing the workflow run results on your Dashboard. |
| status | **string (enum)**
The [status](#workflow-run-status) of the Workflow Run. Possible values are: `processing`, `awaiting_input`, `awaiting_client_input`, `approved`, `declined`, `review`, `abandoned` and `error`. |
| tags | **array of strings**
A list of tags associated with the Workflow Run. |
| customer\_user\_id | **string**
A customer-provided user identifier. |
| output | **[output object](#output-object)**
Output object contains all of the properties configured on the workflow version. |
| reasons | **array (string)**
The [reasons](#reasons) the Workflow Run outcome was reached. Configurable when creating the Workflow Version. |
| error | **[error object](#error-object)**
Error object. Only set when the Workflow Run status is `error`. |
| sdk\_token | **string**
Client token to use when initiating this workflow run in the Entrust Identity Verification SDK. |
| link | **[link object](#link-object)**
Link object. |
| created\_at | **datetime (ISO-8601)**
The date and time when the Workflow Run was created. |
| updated\_at | **datetime (ISO-8601)**
The date and time when the Workflow Run was last updated. |
#### Output object
Workflow output data is a configurable set of properties which allows you to add any specific data attribute contained within a Workflow.
Workflow Output information must be first created as a property in Studio using the Workflow input and output configuration tab. Once the properties are created
then these need to be mapped on the end tasks. This gives full flexibility to add as little or as much detailed information to the Retrieve Workflow Run endpoint.
This is the recommended method to integrate with our API to get information into your systems.
#### Reasons
Workflow reasons are set during Workflow creation in Studio. Each end task can have one or more reasons configured by the user.
This provides the flexibility to capture more information about why an end user reached a specific end state.
For example, if a workflow contains multiple approval end tasks, the reasons field can be used to clearly identify which path the end user completed.
#### Error object
Error object that details why a Workflow Run is in Error status.
| Attribute | Description |
| --------- | ---------------------------------------------------- |
| type | **string**
The type of the error. |
| message | **string**
A textual description of the error. |
#### Link object
Object for the configuration of the Workflow Run link.
| Attribute | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| url | **string**
Link to access the Workflow Run without the need to integrate with the Entrust Identity Verification SDKs. |
| completed\_redirect\_url | **string**
When the interactive section of the Workflow Run has completed successfully, the user will be redirected to this URL instead of seeing the default "thank you" page. |
| expired\_redirect\_url | **string**
When the Link has expired, the user will be immediately redirected to this URL instead of seeing the default error message. |
| expires\_at | **string (ISO-8601)**
Date and time when the link will expire. [Additional details](#link-expiration). |
| language | **string (enum)**
The code for the language when the Workflow Run is acessed using the link. |
### Create Workflow Run
`POST /v3.6/workflow_runs/`
Creates and starts a Workflow Run. Returns a [Workflow Run object](#workflow-run-object).
A Workflow must exist and be activated before you can create a Workflow Run. You can create and activate your Workflow
in Workflow Studio via the [Dashboard](https://dashboard.onfido.com/studio). An Applicant ID is mandatory for creating a Workflow Run.
For active Workflows with [gradual rollout](/getting-started/workflow-studio-product/#gradual-workflow-rollout) applied, user traffic through Workflow Runs
will be distributed according to the percentages configured in your Dashboard.
Any data that you want to provide to be used in the Workflow Run can be passed in two ways at its creation:
* [Applicant object](#applicant-data)
* [Custom input data](#custom-input-data)
> ℹ️ **Note:** You must request a Workflow Run before you initialize the SDK.
#### Request body parameters
| Parameter | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| workflow\_id | **required** string (UUID)
The unique identifier for the Workflow. |
| applicant\_id | **required** string (UUID)
The unique identifier for the Applicant. |
| tags | **optional** array of strings
Array of tags being assigned to the Workflow Run.
**Please note**: you must never pass Personally Identifiable Information (PII) into workflow run tags. |
| custom\_data | **optional** [custom data](#custom-input-data) object
Object with Custom Input Data to be used in the Workflow Run. |
| link | **optional** [link](#link-object) object
Link object to configure the Workflow Run link. |
| customer\_user\_id | **optional** string
A customer-provided user identifier. |
#### Applicant Data
The Workflow Run requires an Applicant ID, meaning that the Workflow is able to access information stored in the Applicant.
Before being able to use that data within the Workflow Run, you must specify which Applicant fields you intend to use by configuring
the Input Data via Studio. The additional Applicant fields you decide to use become mandatory and the Workflow Run create endpoint will
validate if they are present before creating the Workflow Run. You can manage the Applicant using the [create](#create-applicant) and
[update](#update-applicant) endpoints.
#### Custom Input Data
If you have business-specific data that you want to use during your workflow, you can configure Custom Input Data
using the Studio via the Dashboard.
If Custom Input Data is configured, then it becomes mandatory when creating a Workflow Run.
#### [Link object](#create-workflow-run-link-object)
Object for the configuration of the Workflow Run link.
| Attribute | Description |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| completed\_redirect\_url | **optional** string
When the interactive section of the Workflow Run has completed successfully, the user will be redirected to this URL instead of seeing the default "thank you" page. |
| expired\_redirect\_url | **optional** string
When the Link has expired, the user will be immediately redirected to this URL instead of seeing the default error message. |
| expires\_at | **optional** string (ISO-8601)
Date and time when the link will expire. [Additional details](#link-expiration). |
| language | **optional** string (enum)
The code for the language when the Workflow Run is accessed using the link. Defaults to `en_US` if not specified. |
**Supported languages**
You can customize the language attribute of the link object for when the Workflow Run is accessed using the link by including the corresponding country code (`fr` for French, for example).
You can find a complete list of the 44 supported languages and their relevant codes in our [SDK customization guide](/sdk/sdk-customization#supported-languages).
#### [Link expiration](#link-expiration)
When the link expires, the Applicant won't be able to use it anymore to access the Workflow Run journey. If no expiration date and time is set, the link will be acessible
until the Workflow Run reaches an end state (`abandoned`, `error`, `approved`, `review` and `declined`).
### List Workflow Runs
`GET /v3.6/workflow_runs`
Retrieves the [Workflow Runs](#workflow-runs) of the client. Returns a list of [Workflow Run
objects](#workflow-run-object). The page size is 20 objects.
#### [Query String parameters](#list-workflow-runs-query-parameters)
`page` (optional): The number of the page to be retrieved. If not specified, defaults to 1.
`status` (optional): a list of comma separated [status](#workflow-run-status) values to filter the results.
`tags` (optional): a list of comma separated tags to filter the results.
`created_at_gt` (optional): a ISO-8601 date to filter results with a created date greater than (after) the one provided.
`created_at_lt` (optional): a ISO-8601 date to filter results with a created date less than (before) the one provided.
`sort` (optional): a string with the value `desc` or `asc` that allows to sort the returned list by the completed datetime either descending or ascending, respectively.
If not specified, defaults to `desc`.
`applicant_id` (optional): the unique identifier (UUID) of applicant.
### Retrieve Workflow Run
`GET /v3.6/workflow_runs/{workflow_run_id}`
Retrieves a [Workflow Run](#workflow-runs). Returns a [Workflow Run
object](#workflow-run-object).
#### [Path parameters](#retrieve-workflow-run-path-parameters)
`workflow_run_id` (required): the unique identifier of the Workflow Run you want to retrieve.
### Retrieve Workflow Run Evidence Folder
`GET /v3.6/workflow_runs/{workflow_run_id}/evidence_folder`
Retrieves the evidence folder for the designated Workflow Run.
After a successful call, a 302 Found HTTP status is returned with a pre-signed URL to download the folder (in the ZIP file format) in the Location header.
The evidence folder is available a few seconds after the Workflow Run has been completed. Please also ensure that evidence folder generation is enabled for your account. See the [ETSI Certified IDV product guide](/guide/etsi-certified-idv/) for more information.
**Note**: If you invoke this endpoint for Sandbox workflow runs, a mock evidence folder will be returned.
#### [Path parameters](#retrieve-workflow-run-evidence-folder-path-parameters)
`workflow_run_id` (required): the unique identifier of the Workflow Run for which you want to retrieve the evidence folder.
> ⚠️ **Warning:** **Note**: The Evidence Folder may contain sensitive personal identifiable information (PII). The pre-signed URLs allow downloading the Evidence Folder and should be handled carefully.
### Retrieve Workflow Run Evidence Summary File
> ⚠️ **Warning:** The evidence summary file is deprecated. We recommend that you use the [Evidence Folder](#retrieve-workflow-run-evidence-folder) instead.
`GET /v3.6/workflow_runs/{workflow_run_id}/evidence_summary_file`
Retrieves the evidence summary file for the designated Workflow Run.
After a successful call, a 302 Found HTTP status is returned with a pre-signed URL to download the file in the Location header.
The evidence summary file is available a few seconds after the Workflow Run has been completed. Please also ensure that file generation is enabled for your account. See the [ETSI Certified IDV product guide](/guide/etsi-certified-idv/) for more information.
**Note**: If you invoke this endpoint for Sandbox workflow runs, a mock evidence summary file will be returned.
#### [Path parameters](#retrieve-workflow-run-evidence-summary-file-path-parameters)
`workflow_run_id` (required): the unique identifier of the Workflow Run for which you want to retrieve the evidence summary file.
> ⚠️ **Warning:** **Note**: The Evidence Summary File may contain sensitive personal identifiable information (PII). The pre-signed URLs allow downloading the Evidence Summary File and should be handled carefully.
## Tasks
Tasks are the individual steps that make up a Workflow Run. Tasks may require Task input data in order to execute,
and will return Task output data on completion. Task input data can be managed by selecting a Task and configuring it
in the input tab in Studio. The Task endpoints are designed to enable auditability and transparency of Workflow Runs
by providing Task input and output.
Tasks are versioned using unique Task Definitions so that each time enhancements, new features or bugs are released,
the functioning of these Tasks remains unchanged, preserving the integrity of the previous version of the Workflow.
Task inputs and outputs may change between Task versions.
The Task input and output information is accessible directly in Studio and should be used to configure an applicant's
verification journey using the condition tasks. For example, Tasks output data can be used to decide the next Tasks to
perform, or the end state of the Applicant verification journey directly within Studio.
Despite this data being available and accessible through these endpoints, it also comes with some drawbacks. If changes
are made to the Workflow, or individual Tasks are updated (new features, bug fixing, for example), the schemas may change,
which could break previous integrations.
As such, Task endpoints are not recommended to be used as an integration method to retrieve data, please use
the [Output object](#output-object-workflow-runs) in [Workflow Run](#workflow-runs).
### Task object
| Attribute | Description |
| ------------------ | -------------------------------------------------------------------------------------- |
| id | **string**
The identifier for the Task. |
| task\_def\_id | **string**
The identifier for the Task Definition. |
| task\_def\_version | **string**
The version for the Task Definition. |
| workflow\_run\_id | **string (UUID)**
The identifier for the Workflow Run to which the task belongs. |
| input | **object**
Input object with the fields used by the Task to execute. |
| output | **object**
Output object with the fields produced by the Task execution. |
| created\_at | **datetime (ISO-8601)**
The date and time when the Task was created. |
| updated\_at | **datetime (ISO-8601)**
The date and time when the Task was last updated. |
### List Tasks
`GET /v3.6/workflow_runs/{workflow_run_id}/tasks`
Retrieves the [Tasks](#tasks) of a Workflow Run. Returns a subset of the [Task
object](#task-object).
The response contains only Tasks that were already started or completed, ordered by the `created_at`
field, in ascending order.
#### [Path parameters](#list-tasks-path-parameters)
`workflow_run_id` (required): the unique identifier of the Workflow Run to which the Tasks belong.
#### Example response
```json
[
{
"id": "",
"task_def_id": "",
"workflow_run_id": "",
"created_at": "2022-06-28T15:39:42Z",
"updated_at": "2022-07-28T15:39:52Z",
},
{
"id": "",
"task_def_id": "",
"workflow_run_id": "",
"created_at": "2022-06-28T15:40:42Z",
"updated_at": "2022-07-28T15:40:52Z",
}
...
]
```
### Retrieve Task
`GET /v3.6/workflow_runs/{workflow_run_id}/tasks/{task_id}`
Retrieves a [Task](#tasks). Returns a [Task
object](#task-object).
#### [Path parameters](#retrieve-task-path-parameters)
`workflow_run_id` (required): the unique identifier of the Workflow Run to which the Task belongs.
`task_id` (required): the identifier of the Task you want to retrieve.
**Note**: The `output` property of the returned task object can be `null`, under the following circumstances:
* the task is still ongoing
* the task completes but does not require any output
* the task failed, or the workflow run was canceled before it completed
### Complete Task
`POST /v3.6/workflow_runs/{workflow_run_id}/tasks/{task_id}/complete`
Completes a [Send / Receive Data Task](#send--receive-data-tasks).
#### [Path parameters](#complete-task-path-parameters)
`workflow_run_id` (required): the unique identifier of the Workflow Run to which the Task belongs.
`task_id` (required): the identifier of the Task you want to complete.
#### Request body parameters
| Parameter | Description |
| --------- | ------------------------------------------------------------------------------------------------------- |
| data | **required** object
The Task completion payload. More details [below](#send--receive-data-tasks). |
#### [Send / Receive Data Tasks](#send--receive-data-tasks)
Send / Receive Data Tasks are a special type of Task that allow you to create custom actions that can be executed anywhere in a workflow.
You can send data out of the system mid workflow and pass data back in to be used in more logic tasks.
You can configure a Send / Receive Data Task in the Workflow Builder, while defining your Workflow. When configuring a Send / Receive Data Task, you should
define the input and output data it expects. The logic necessary to process the inputs and produce the outputs is up to the service being called.
The recommended way of integrating a Send / Receive Data Task is configuring a `workflow_task.started` Webhook, so you can be notified when the task is ready
to execute. The payload of this Webhook contains all the inputs you have defined for your Task.
Once notified by our Webhook, your system can asynchronously run any custom action you want to produce the desired outputs. Once ready, you should
invoke the Complete Task endpoint, providing as `data` parameter an object with the outputs you have defined. Our system will validate the provided data against
the output schema you have defined when configuring the Send / Receive Data Task and return an HTTP 422 error if they don't match.
If the submission of the data is successful, the Send / Receive Data Task will be completed and the Workflow will proceed. All data received back into the Workflow Run will be able to be used in our condition logic tasks.
You can configure as many Send / Receive Data Tasks as you want in your Workflow.
# Authentication Endpoints
The endpoints documented in this section enable you to manage mechanisms around secure, passwordless authentication. These include the retrieval and management of biometric tokens used for the enrollment and authentication of applicants, as well as the retrieval and management of encrypted passkeys.
## Biometric tokens
Biometric tokens are securely encrypted data that contain media embeddings (such as motion captures) along with relevant identifiers.
These tokens are symmetrically encrypted by Entrust to ensure the security and privacy of the biometric information.
Please refer to the [Studio guide](/getting-started/workflow-studio-product/#decentralized-authentication) for generating **biometric tokens**.
### Biometric token object
| Attribute | Description |
| ------------ | ----------------------------------------------------------------------------------------- |
| uuid | **string**
The unique identifier of the biometric token. |
| inserted\_at | **datetime (ISO-8601)**
The date and time at which the biometric token was created. |
| media\_type | **string**
The biometric media type. |
| status | **string**
The status of the biometric token (e.g. approved, declined ...). |
### List biometric tokens
`GET /v3.6/biometric_tokens/{customer_user_id}`
Lists all the biometric tokens that belong to a `customer_user_id`. A `customer_user_id` is an identifier that uniquely identifies the customer's end-user, regardless of Entrust's applicant.
Note: The customer user ID will default to the applicant ID if not specified at workflow creation.
Returns data in the form: `{"biometric_tokens": []}`.
#### Path parameters
`customer_user_id` (required): A free-form unique string that identifies a user, passed at [workflow run creation](https://documentation.identity.entrust.com/api/latest/#create-workflow-run).
### Retrieve biometric token details
`GET /v3.6/biometric_tokens/{customer_user_id}/{biometric_token_uuid}`
Retrieves a single biometric token. Returns the corresponding [biometric token object](#biometric-token-object).
### Invalidate all biometric tokens
`DELETE /v3.6/biometric_tokens/{customer_user_id}`
Invalidates all biometric tokens for a given `customer_user_id`.
If successful, returns a `200 OK` response.
### Invalidate a single biometric token
`DELETE /v3.6/biometric_tokens/{customer_user_id}/{biometric_token_uuid}`
Invalidates a single biometric token for a given `customer_user_id`.
If successful, returns a `200 OK` response.
### Update a single biometric token status
`PUT /v3.6/biometric_tokens/{customer_user_id}/{biometric_token_uuid}`
Updates a biometric token's `status`. Returns the updated [biometric token object](#biometric-token-object).
> ℹ️ **Note:** This endpoint can be used to manually approve a biometric token
## Passkeys
Passkeys are phishing-resistant FIDO2 credentials that can be used to approve secure actions across Entrust workflows.
They are generated and stored by the applicant's trusted hardware or platform authenticator so subsequent assertions stay tamper-proof.
For more information on Passkey, please refer to the dedicated [product documentation](/guide/passkey-authentication/).
### Passkey object
| Attribute | Description |
| ------------------- | -------------------------------------------------------------------------------------------- |
| id | **string**
Unique identifier of the passkey resource. |
| application_domain | **string**
The domain that passkeys will be registered to for authentication. This is also known as the relying party identifier (RP ID). |
| state | **string**
The state of the passkey. Allowed values: `ACTIVE`, `INACTIVE`. |
| created_at | **datetime (ISO-8601)**
Timestamp indicating when the passkey was created. |
| last_used_at | **datetime (ISO-8601)**
Timestamp of the most recent successful authentication, if any. |
### List passkeys
`GET /v3.6/passkeys/{username}`
Lists all the passkeys that belong to a `username`. A `username` is an identifier that is passed to the Enroll Passkey task's input.
Note: The username will default to the applicant ID if no input is passed to the Enroll Passkey task in the workflow.
Returns data in the form: `passkeys: []`
### Retrieve passkey
`GET /v3.6/passkeys/{username}/{passkey_id}`
Retrieves a single passkey.
Returns the corresponding [passkey object](#passkey-object).
### Delete all passkeys
`DELETE /v3.6/passkeys/{username}`
Deletes all passkeys stored for the specified `username`.
If successful, returns `204 No Content` response.
### Delete a single passkey
`DELETE /v3.6/passkeys/{username}/{passkey_id}`
Deletes the specified passkey for the given `username`.
If successful, returns `204 No Content`.
### Update a single passkey state
`PUT /v3.6/passkeys/{username}/{passkey_id}`
Updates the `state` field of a passkey to either `ACTIVE` or `INACTIVE`.
Returns the updated [passkey object](#passkey-object).
# Media Upload and Retrieval Endpoints
The endpoints documented in this section enable you to manage the upload and retrieval of document and facial biometric media assets used during identity verifications.
**Please note**: Live photos and motion captures cannot be uploaded via API; these must be captured by one of the Entrust IDV SDKs. Entrust highly recommends integration using our SDKs for the capture of identity documents and facial biometrics in order to benefit from our advanced image quality controls and fraud protection mechanisms.
## Documents
A document represents an applicant's identity document (such as a passport, national ID card or driver's license), to be used as a means of verifying their identity.
Documents belong to a single applicant, so they must be captured during a verification workflow after an [applicant](#applicants) has been created.
Several of Entrust's verification reports require the capture of identity documents in order to be processed successfully. The full list of the documents we support can be found [here](https://www.entrust.com/products/identity-verification/document-verification/supported-documents/).
> ⚠️ **Warning:** Depending on the type of the document, we may require both sides of the document to be captured.
The Entrust Identity Verification API uses the British English spelling `driving_licence` when required for reports.
### Document object
| Attribute | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------- |
| id | **string**
The unique identifier of the document. |
| created\_at | **datetime**
The date and time at which the document was uploaded. |
| href | **string**
The URI of this resource. |
| download\_href | **string**
The URI that can be used to download the document. |
| file\_name | **string**
The name of the uploaded file. |
| file\_type | **string**
The file type of the uploaded file. |
| file\_size | **integer**
The size of the file in bytes. |
| type | **string**
The [type of document](#document-types). |
| side | **string**
The side of the document, if applicable. The possible values are `front` and `back`. |
| issuing\_country | **string**
The issuing country of the document, in 3-letter ISO code, specified when uploading it. |
| applicant\_id | **string**
The id of the applicant to whom the document belongs. |
### Document types
#### Identity documents
The following is a partial list of document types (i.e. `type` when [uploading
a document](#upload-document)):
| Type |
| ------------------------ |
| `national_identity_card` |
| `driving_licence` |
| `passport` |
| `voter_id` |
| `work_permit` |
This list is not exhaustive.
If you're unsure of the type of document you want to verify, you can
submit documents with type `unknown`. In this case, we will attempt to
classify and recognize the document type when processing a Document report.
### Upload document
`POST /v3.6/documents/`
> ⚠️ **Warning:** Using this endpoint in a live context will cause you to
> send personal data to Entrust. Always make sure you inform your users about this
> and obtain any necessary permissions. For more information on how Entrust uses
> personal data, view our [Privacy Policy](https://onfido.com/privacy/).
Uploads a single [identity document](#documents) as part of a verification journey. Returns a [document object](#document-object).
A sample document is provided [here](/images/sample_driving_licence.png) for testing this endpoint.
Valid file formats for documents are `jpg`, `png` and `pdf`. The file size
must be between 32KB and 10MB. Maximum supported resolution is 64MPx.
> ⚠️ **Warning:** Entrust **highly recommends** integration using our SDKs for the capture and upload of identity documents. Our advanced image detection technology ensures the quality of the captured images meets the requirement of Entrust's identity verification process.
#### [Request body parameters](#upload-document-request-body)
| Parameter | Description |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| applicant\_id | **required**
The ID of the applicant who owns the document. |
| file | **required**
The file to be uploaded. |
| type | **required**
The [type of document](#document-types). For example, `passport`. |
| side | **optional** (**required** for [documents which have multiple sides](https://www.entrust.com/products/identity-verification/document-verification/supported-documents/))
Either the `front` or `back` of the document. |
| issuing\_country | **optional** (**required** for [Proof of Address](#proof-of-address-report) reports)
The issuing country of the document in 3-letter ISO code. |
| location | **optional**
An object that contains the location/country of residence of the applicant. |
| validate\_image\_quality | **optional**
A Boolean. Defaults to `false`. When `true` the submitted image will undergo an [image quality validation](#image-quality) which may take up to 5 seconds. |
> **Note:** Provide the `side` parameter when uploading documents for optimal results.
#### [location](#location-upload-document)
> ⚠️ **Warning:** You must provide `location` for every applicant. If you do not, all checks will fail with a validation error.
You must provide location information for each end user as this determines the necessary consent required in order to process a verification.
You can specify either or both the IP address and the country of residence (3 character ISO country code) of the applicant in the `location` object.
```bash
...
-F 'location[ip_address]=127.0.0.1' \
-F 'location[country_of_residence]=GBR'
...
```
You can also provide location information during [applicant creation](#create-applicant).
If you submit location information in multiple requests, the document upload location will take precedence.
If you submit location information during document upload, this will not be returned in the [applicant object](#applicant-object).
> ℹ️ **Note:** If you use the Entrust Identity Verification SDK, location is provided directly by the SDK. You do not need to manually submit the `location` parameter in this case.
#### Image quality
You can request image quality validation when uploading a document. It is conducted synchronously and you'll receive the result as a response to your request.
When the image passes validation, returns a [document object](#document-object).
When the image fails validation, returns a [422 validation\_error](#error-codes-and-what-to-do). There can be one or more failed image quality validations for a request. The list of reasons is provided in the `fields` property.
> ℹ️ **Note:** If the image fails validation, you should ask the end user to retake the photo of their document.
| Field | Message |
| -------------------- | --------------------------------- |
| `detect_blur` | blur detected in image |
| `detect_cutoff` | cutoff document detected in image |
| `document_detection` | no document in image |
Sample images to trigger various error responses can be provided.
### Retrieve document
`GET /v3.6/documents/{document_id}`
Retrieves a single document. Returns a [document object](#document-object).
### List documents
`GET /v3.6/documents?applicant_id={applicant_id}`
Lists all documents belonging to an applicant, and includes any associated media (document photos and videos when these are retrieved by UUID).
Returns data in the form:
`{"documents": []}`.
#### [Query string parameters](#list-documents-query-string-parameters)
`applicant_id` (required): the ID of the applicant ID whose documents you want to list.
### Download document
`GET /v3.6/documents/{document_id}/download`
Downloads specific documents belonging to an applicant. If successful, the
response will be the binary data representing the image.
#### [Path parameters](#download-document-path-parameters)
`document_id` (required): the unique identifier (UUID) of the document.
### Download NFC face
`GET /v3.6/documents/{document_id}/nfc_face`
Downloads digital photos extracted from specific documents belonging to an
applicant. If successful, the response will be the binary data representing
the image.
#### [Path parameters](#download-nfc-face-path-parameters)
`document_id` (required): the unique identifier (UUID) of the document.
### Download document video
`GET /v3.6/documents/{document_id}/video/download`
Downloads a document video. If successful, the response will be the binary data representing the video.
#### [Path parameters](#download-document-video-path-parameters)
`document_id` (required): the unique identifier (UUID) of the document.
## Motion captures
Motion captures are representations of an applicant's face, recorded and uploaded by the
Entrust Identity Verification SDKs ([iOS](/sdk/ios/),
[Android](/sdk/android/) or
[Web](/sdk/web/)), at the same time as the
document image is captured—also by the SDKs. These captures are used for [Facial
Similarity Motion](#facial-similarity-motion) reports.
### Motion capture object
| Attribute | Description |
| -------------- | ----------------------------------------------------------------------------------------- |
| id | **string**
The unique identifier of the motion capture. |
| created\_at | **datetime (ISO-8601)**
The date and time at which the motion capture was uploaded. |
| href | **string**
The URI of this resource. |
| download\_href | **string**
The URI that can be used to download a motion capture. |
| file\_name | **string**
The name of the uploaded file. |
| file\_type | **string**
The file type of the uploaded file. |
| file\_size | **integer**
The size of the file in bytes. |
### Upload motion capture
> ⚠️ **Warning:** Motion captures can only be uploaded via one of our SDKs, not via the API directly. As a result, **Entrust does not provide an upload motion capture endpoint**.
To upload motion captures for [Facial Similarity Motion reports](#facial-similarity-motion), integrate with one of our Smart Capture SDKs ([iOS](/sdk/ios/), [Android](/sdk/android/) or [Web](/sdk/web/)).
The maximum motion capture file size is 3MB.
### Retrieve motion capture
`GET https://api.onfido.com/v3.6/motion_captures/{motion_capture_id}`
Retrieves a single motion capture. Returns the corresponding [motion capture object](#motion-capture-object).
### List motion captures
`GET https://api.onfido.com/v3.6/motion_captures?applicant_id={applicant_id}`
Lists all the motion captures that belong to an applicant.
Returns data in the form: `{"motion_captures": []}`.
#### [Query string parameters](#list-motion-captures-query-string-parameters)
`applicant_id` (required): the ID of the applicant whose motion captures you want to list.
### Download motion capture
`GET https://api.onfido.com/v3.6/motion_captures/{motion_capture_id}/download`
Downloads a motion capture. Returns the binary data representing the motion capture.
### Download motion capture frame
`GET https://api.onfido.com/v3.6/motion_captures/{motion_capture_id}/frame`
Instead of the whole motion capture data, a single frame can be downloaded using this
endpoint. Returns the binary data representing the frame.
### Unsuccessful frame extraction
#### Frame extraction failed
If a frame cannot be extracted from the motion capture, a `frame_extraction_failed` response will be returned.
#### Frame extraction unavailable
If the extraction feature is temporarily unavailable, a `frame_extraction_unavailable` response will be returned instead.
## Live photos
Live photos are images of the applicant's face, typically captured or uploaded during the same verification flow as [identity documents](#documents) are provided. Several of Entrust's verification reports require the capture or upload of live photos in order to be processed successfully.
### Live photo object
| Attribute | Description |
| -------------- | -------------------------------------------------------------------------- |
| id | **string**
The unique identifier of the live photo. |
| created\_at | **datetime**
The date and time at which the live photo was uploaded. |
| href | **string**
The URI of this resource. |
| download\_href | **string**
The URI that can be used to download the live photo. |
| file\_name | **string**
The name of the uploaded file. |
| file\_type | **string**
The file type of the uploaded file. |
| file\_size | **integer**
The size of the file in bytes. |
### Upload live photo
`POST /v3.6/live_photos/`
> ⚠️ **Warning:** Using this endpoint in a live context will cause you to
> send personal data to Entrust. Always make sure you inform your users about this
> and obtain any necessary permissions. For more information on how Entrust uses
> personal data, view our [Privacy Policy](https://onfido.com/privacy/).
Uploads a [live photo](#live-photos) as part of a verification journey. Returns a [live photo object](#live-photo-object).
A sample photo is provided [here](/images/sample_photo.png) for testing this endpoint.
Valid file formats for live photos are `jpg`, `jpeg` and `png`. The file size must be
between 32KB and 10MB. Live photos are validated at the point of upload to
check that they contain exactly one face. This validation can be disabled by
setting the `advanced_validation` argument to `false`.
> ⚠️ **Warning:** Entrust **highly recommends** integration using the Entrust Identity Verification SDKs for the capture of live photos. Our advanced image detection technology ensures the quality of the captured images meets the requirement of Entrust's identity verification process.
#### [Request body parameters](#upload-live-photo-request-body)
| Parameter | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------- |
| file | **required**
The file to be uploaded. |
| applicant\_id | **required**
The applicant\_id to associate the live photo with. |
| advanced\_validation | **optional**
A Boolean which defaults to true
Validates that the live photo contains exactly one face. |
### Retrieve live photo
`GET /v3.6/live_photos/{live_photo_id}`
Retrieves a single live photo. Returns a [live photo
object](#live-photo-object).
### List live photos
`GET /v3.6/live_photos/?applicant_id={applicant_id}`
Lists the live photos that belong to an applicant. Returns data in the form:
`{"live_photos": []}`.
#### [Query string parameters](#list-live-photos-query-string-parameters)
`applicant_id` (required): the ID of the applicant whose live photos you want to list.
### Download live photo
`GET /v3.6/live_photos/{live_photo_id}/download`
Downloads a live photo. If successful, the response will be the binary data
representing the image.
## Live videos
Live videos are footage of the applicant's face, recorded and uploaded by the
Entrust Identity Verification SDKs ([iOS](/sdk/ios/),
[Android](/sdk/android/) or
[Web](/sdk/web/)), at the same time as the
document image is captured—also by the SDKs. These videos are used for [Facial
Similarity Video](#facial-similarity-video) reports.
### Live video object
During the video recording end users are asked to perform randomly generated actions, represented in `challenge`. Challenges always have 2 parts `recite` and `movement`, but the order in which these happen can vary. The order of the challenges is maintained in the live video object. `recite` asks the user to say 3 randomly generated digits, whereas `movement` asks the user to look over their right or left shoulder.
| Attribute | Description |
| -------------- | -------------------------------------------------------------------------------------------------- |
| id | **string**
The unique identifier of the live video. |
| created\_at | **datetime**
The date and time at which the live video was uploaded. |
| href | **string**
The URI of this resource. |
| download\_href | **string**
The URI that can be used to download the live video. |
| file\_name | **string**
The name of the uploaded file. |
| file\_type | **string**
The file type of the uploaded file. |
| file\_size | **integer**
The size of the file in bytes. |
| challenge | **array of objects**
Challenge the end user was asked to perform during the video recording. |
### Upload live video
> ⚠️ **Warning:** Live videos can only be uploaded via one of our SDKs, not via the API directly. As a result, **Entrust does not provide an upload live video endpoint**.
To upload live videos for [Facial Similarity Video reports](#facial-similarity-video), integrate with one of our Smart Capture SDKs ([iOS](/sdk/ios/), [Android](/sdk/android/) or [Web](/sdk/web/)).
The maximum video file size is 10MB.
### Retrieve live video
`GET /v3.6/live_videos/{live_video_id}`
Retrieves a single live video. Returns the corresponding [live video object](#live-video-object).
### List live videos
`GET /v3.6/live_videos?applicant_id={applicant_id}`
Lists all the live videos that belong to an applicant.
Returns data in the form: `{"live_videos": []}`.
#### [Query string parameters](#list-live-videos-query-string-parameters)
`applicant_id` (required): the ID of the applicant whose live videos you want to list.
### Download live video
`GET /v3.6/live_videos/{live_video_id}/download`
Downloads a live video. Returns the binary data representing the video.
### Download live video frame
`GET /v3.6/live_videos/{live_video_id}/frame`
Instead of the whole video, a single frame can be downloaded using this
endpoint. Returns the binary data representing the frame.
This will be the frame extracted from the video where the end user is facing the camera.
If no face can be detected, it will fallback to the first frame of the video.
### Unsuccessful frame extraction
#### Frame extraction failed
If a frame cannot be extracted from the live video, a `frame_extraction_failed` response will be returned.
#### Frame extraction unavailable
If the extraction feature is temporarily unavailable, a `frame_extraction_unavailable` response will be returned instead.
## ID photos
ID photos are government ID images of the applicant's face, typically provided by a
trustworthy party (e.g., Government digital agency). ID photos can be used for all [Facial Similarity report](#facial-similarity-reports) variants.
### ID photo object
| Attribute | Description |
| -------------- | ------------------------------------------------------------------------ |
| id | **string**
The unique identifier of the ID photo. |
| created\_at | **datetime**
The date and time at which the ID photo was uploaded. |
| href | **string**
The URI of this resource. |
| download\_href | **string**
The URI that can be used to download the ID photo. |
| file\_name | **string**
The name of the uploaded file. |
| file\_type | **string**
The file type of the uploaded file. |
| file\_size | **integer**
The size of the file in bytes. |
> ℹ️ **Note:** By default, if both an ID photo and a document are provided for an identity verification journey, this ID photo will be used for the facial similarity check, even if the identity document is more recent. The rationale is that ID photos are meant to be more trustworthy than document live captures.
> To use ID photos in Workflow Studio, please refer to the [Integrating ID Photos with Workflow Studio](#integrating-id-photos-with-onfido-studio) section below.
> For customers who have yet to migrate to Workflow Studio and are implementing our Checks and Reports API, the document photo can override an ID photo for Facial Similarity reports by setting the `"document_ids": [""]` property.
### Upload ID photo
`POST /v3.6/id_photos/`
> ⚠️ **Warning:** Using this endpoint in a live context will cause you to
> send personal data to Entrust. Always make sure you inform your users about this
> and obtain any necessary permissions. For more information on how Entrust uses
> personal data, view our [Privacy Policy](https://onfido.com/privacy/).
Uploads a single [ID photo](#id-photos) as part of a verification journey. Returns an [ID photo object](#id-photo-object).
A sample photo is provided [here](/images/sample_photo.png) for testing this endpoint.
Valid file formats for ID photos are `jpg`, `jpeg` and `png`. The file size must be
between 32KB and 10MB.
#### [Request body parameters](#upload-id-photo-request-body)
| Parameter | Description |
| ------------- | ------------------------------------------------------------------- |
| file | **required**
The file to be uploaded. |
| applicant\_id | **required**
The applicant\_id to associate the ID photo with. |
### Retrieve ID photo
`GET /v3.6/id_photos/{id_photo_id}`
Retrieves a single ID photo. Returns a [ID photo
object](#id-photo-object).
### List ID photos
`GET /v3.6/id_photos/?applicant_id={applicant_id}`
Lists the ID photos that belong to an applicant. Returns data in the form:
`{"id_photos": []}`.
#### [Query string parameters](#list-id-photos-query-string-parameters)
`applicant_id` (required): the ID of the applicant whose ID photos you want to list.
### Download ID photo
`GET /v3.6/id_photos/{id_photo_id}/download`
Downloads an ID photo. If successful, the response will be the binary data
representing the image.
### Integrating ID Photos with workflow Studio
To integrate ID photos with Studio workflows, you must add the ID Photos object in the [custom data](#custom-input-data)
field of the [create workflow run](#create-workflow-run) call.
The structure of the custom data field object must be:
```
"custom_data": { "id_photo_ids": [{"id": "", "type": "id_photo"}] }
```
> ℹ️ **Note:** Custom input data for workflows must first be configured in the Dashboard ([refer to our Studio documentation](/getting-started/workflow-studio-product/#workflow-input-data)). If not, the data will not be considered during the workflow run creation.
> You will also need to update the workflow task (e.g. Facial Similarity report) to read the input from the custom input data.
# Electronic Signature Endpoints
The endpoints documented in this section enable you to manage the upload and retrieval of a range Entrust’s electronic signature solutions. Regardless of your specific requirements, Entrust’s Qualified, Advanced and Simple electronic signature solutions offer a secure, compliant and auditable mechanism for digitally signing documents.
## Qualified Electronic Signature
### Retrieve Workflow Run Signed Document
`GET /v3.6/qualified_electronic_signature/documents?workflow_run_id={workflow_run_id}&file_id={file_id}`
Retrieves the signed document or application form depending on the `file_id` provided.
After a successful call, a `302 Found` HTTP status is returned with a pre-signed URL to download the file in the `Location` header.
The signed QES document can also be downloaded from the Dashboard as part of the ETSI Evidence Folder for the associated workflow run.
**Note**: If you invoke this endpoint for Sandbox workflow runs, a mock signed document will be returned.
#### [Query string parameters](#retrieve-qes-document-query-string-parameters)
`workflow_run_id` (required): the unique identifier of the Workflow Run for which you want to retrieve the signed document.
`file_id` (required): the unique identifier of the file which you want to retrieve.
**Note**: To retrieve `file_id`, you can obtain Qualified Electronic Signatures task details using the [Retrieve Task](#retrieve-task) endpoint:
`/v3.6/workflow_runs/{workflow_run_id}/tasks/{task_id}`
## Advanced Electronic Signature
[Advanced Electronic Signature (AES)](/guide/advanced-electronic-signature/) is a secure method of digital signing that ensures the integrity, authenticity and legal admissibility of electronic documents.
Upon completion, all signed documents and signature transaction receipts can be [retrieved and downloaded](#retrieve-electronic-signature-document).
## Simple Electronic Signature
Simple Electronic Signature (SES) is a basic form of electronic signing suitable for lower assurance, low-risk documents (for example acknowledgements or standard agreements) where advanced identity verification is not required.
Upon completion, all signed documents and signature transaction receipts can be [retrieved and downloaded](#retrieve-electronic-signature-document).
## Signing documents
Signing documents are files that must be reviewed and electronically signed by the applicant during e-signature tasks (e.g. employment agreements, consent forms, etc.).
They are associated with a single applicant and must be uploaded after the applicant is created. Once uploaded, a signing document
can be referenced by an [e-signature task](/guide/advanced-electronic-signature/#advanced-electronic-signature-request-and-verification-tasks)
by adding the signing document `id` as custom workflow input.
### Signing document object
| Attribute | Description |
| -------------- | -------------------------------------------------------------------------------- |
| id | **string**
The unique identifier of the signing document. |
| file\_name | **string**
The name of the uploaded file. |
| file\_type | **string**
The file type of the uploaded file. |
| file\_size | **integer**
The size of the file in bytes. |
| href | **string**
The URI of this resource. |
| download\_href | **string**
The URI that can be used to download the signing document. |
| created\_at | **datetime**
The date and time at which the signing document was uploaded. |
### Upload signing document
`POST /v3.6/signing_documents/`
> ⚠️ **Warning:** Using this endpoint in a live context will cause you to
> send personal data to Entrust. Always make sure you inform your users about this
> and obtain any necessary permissions. For more information on how Entrust uses
> personal data, view our [Privacy Policy](https://onfido.com/privacy/).
Uploads a single [signing document](#signing-documents) as part of a verification journey. Returns an [signing document object](#signing-document-object).
Only valid file format for signing documents is `pdf`. The file size must be between 32KB and 10MB, with a maximum of 20 pages.
#### [Request body parameters](#upload-signing-document-request-body)
| Parameter | Description |
| ------------- | --------------------------------------------------------------------------- |
| file | **required**
The file to be uploaded. |
| applicant\_id | **required**
The applicant\_id to associate the signing document with. |
### Retrieve signing document
`GET /v3.6/signing_documents/{signing_document_id}`
Retrieves a single signing document. Returns a [signing document object](#signing-document-object).
#### [Path parameters](#retrieve-signing-document-path-parameters)
`signing_document_id` (required): the unique identifier (UUID) of the signing document.
### List signing documents
`GET /v3.6/signing_documents/?applicant_id={applicant_id}`
Lists the signing documents that belong to an applicant. Returns data in the form:
`{"signing_documents": []}`.
#### [Query string parameters](#list-signing-documents-query-string-parameters)
`applicant_id` (required): the ID of the applicant whose signing documents you want to list.
### Download signing document
`GET /v3.6/signing_documents/{signing_document_id}/download`
Downloads a signing document. If successful, the response will be the binary data
representing the pdf.
#### [Path parameters](#download-signing-document-path-parameters)
`signing_document_id` (required): the unique identifier (UUID) of the signing document.
### Integrating signing documents with Workflow Studio
To integrate signing documents with Studio workflows, you must add the signing documents object in the [custom data](#custom-input-data)
field of the [create workflow run](#create-workflow-run) call.
The structure of the custom data field object must be:
```
"custom_data": { "signing_document_ids": [{"id": ""}] }
```
> ℹ️ **Note:** Custom input data for workflows must first be configured in the Dashboard ([refer to our Studio documentation](/getting-started/workflow-studio-product/#workflow-input-data)). If not, the data will not be considered during the workflow run creation.
> You will also need to update the workflow task (e.g. Request e-signature) to read the input from the custom input data.
## Electronic Signature Documents
The Electronic Signature Documents endpoint retrieves the signed documents, signature transaction receipts and, for Qualified Electronic Signature (QES), certificate documents produced by Simple (SES), Advanced (AES) and Qualified (QES) electronic signature workflows built with the [Request eSignature task](/guide/electronic-signature-configuration/#request-esignature-task-configuration).
Upon completion, all signed documents, signature transaction receipts and certificate documents can be retrieved and downloaded using a single endpoint, regardless of assurance level. Evidence files are a separate artifact and are retrieved using the [Retrieve Workflow Run Evidence Folder](/api/latest/#retrieve-workflow-run-evidence-folder) endpoint instead.
### Retrieve Electronic Signature Document
`GET /v3.6/electronic_signature/documents?workflow_run_id={workflow_run_id}&id={file_id}`
Retrieves the signed document, signature transaction receipt or certificate document for a Simple, Advanced or Qualified electronic signature workflow. If successful, the response will be the binary data representing the signed PDF document.
#### [Query string parameters](#retrieve-esignature-query-string-parameters)
`workflow_run_id` (required): the unique identifier of the Workflow Run for which you want to retrieve the signed document.
`id` (required): the unique identifier of the file which you want to retrieve.
# Event Monitoring Endpoints
The endpoints documented in this section enable you to monitor the status of verification workflows. These include creating and managing watchlist monitors, programmatically registering and tracking a wide variety of webhook events, as well as creating and retrieving timeline files that provide a compliant end-to-end audit trail of the identity verification process.
## Monitors
Monitors are used for Ongoing Monitoring of an applicant and must be used in conjunction with Watchlist Reports. Monitors listen for changes to Watchlist reports and when an update is detected, a new verification check and corresponding Watchlist Report are initiated. Learn more about this feature [here](/guide/watchlist-reports/).
If you are interested in using this feature, it must first be enabled for your account. Please reach out to your CSM or [email our Client Support team](mailto:identity-client-support@entrust.com).
### Monitor object
| Attribute | Description |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| id | **string**
The unique identifier for the monitor. |
| created\_at | **datetime**
The date and time at which the monitor was created. |
| deleted\_at | **datetime**
The date and time at which the monitor was deleted. If the monitor is still active, this field will be null. |
| applicant\_id | **string**
The ID for the applicant associated with the monitor. |
| report\_name | **string**
The name of the report type the monitor creates. Can be either `"watchlist_standard"` or `"watchlist_aml"`. |
| tags | **array of strings**
A list of tags associated with this monitor. These tags will be applied to each check this monitor creates. |
| sandbox | **boolean**
Indicates whether the object was created in the sandbox or not. |
### Create monitor
`POST /v3.6/watchlist_monitors/`
> ⚠️ **Warning:** **Please note**: This endpoint is only applicable for customers who have yet to migrate to Workflow Studio and are manually requesting checks and reports using our API. When integrating with Studio, an [Ongoing Monitor task](/guide/watchlist-reports/#watchlist-ongoing-monitoring-task) should be added to a Studio workflow.
Creates a new ongoing monitor for the applicant.
Once created, the monitor will create an initial Watchlist report under the given applicant.
Only one active monitor can be created per applicant.
### [Request body parameters](#create-monitor-request-body)
| Parameter | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| applicant\_id | **required**
The ID for the applicant associated with the monitor. |
| report\_name | **required**
The name of the report type the monitor creates. Can be either `"watchlist_standard"` or `"watchlist_aml"`. |
| tags | **optional**
A list of tags associated with this monitor. These tags will be applied to each check this monitor creates. |
### Retrieve monitor
`GET /v3.6/watchlist_monitors/{monitor_id}`
Retrieves a single monitor. Returns a [monitor object](#monitor-object).
### List monitors
`GET /v3.6/watchlist_monitors?applicant_id={applicant_id}`
Returns all available monitors for an applicant. Returns data in the form: `{"monitors": []}`.
#### [Query string parameters](#list-monitors-query-string-parameters)
| Parameter | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| applicant\_id | **optional**
The ID of the applicant whose monitors you want to list. If omitted, all monitors for the account will be listed. |
| include\_deleted | **optional**
If this option is included, deleted (inactive) monitors will also be included in the list. |
### Delete monitor
`DELETE /v3.6/watchlist_monitors/{monitor_id}`
Deactivates the given monitor. No further updates will be given on this monitor, and all search information for this monitor will be deleted. Reports that have already been generated by the monitor will still exist.
> ⚠️ **Warning:** Once a monitor is deleted, it cannot be re-activated.
> If a monitor on an applicant was deleted in error, a new monitor will need to be created.
### List matches (BETA)
`GET /v3.6/watchlist_monitors//matches`
Gets a list of match IDs on this monitor, as well as their enabled/disabled status.
Match IDs are also visible in the report properties of monitored watchlist reports.
> ⚠️ **Warning:** This will NOT return details about each match. (Such as name, media links, match type, etc.)
> This will only return the IDs and enabled/disabled status.
> Match details are only viewable on reports generated by the monitor.
```
HTTP/1.1 200 Success
Content-Type: application/json
{
"matches": [
{
"id": ,
"enabled": true
},
{
"id": ,
"enabled": false
},
...
]
}
```
### Set match status (BETA)
`PATCH /v3.6/watchlist_monitors//matches`
Update the enabled status of the given matches.
Matches that are disabled will no longer contribute to overall results in future reports generated by this monitor.
Additionally, any updates to disabled matches will no longer trigger a new report to be generated.
#### [Request body parameters](#disable-matches-request-body)
| Parameter | Description |
| --------- | ---------------------------------------------------------------- |
| enable | **optional**
Array of match IDs to set to `enable: true`. |
| disable | **optional**
Array of match IDs to set to `enable: false`. |
If no match IDs are provided, a `204 No Content` response is returned.
If the same ID is provided to both the “enable” and “disable” lists, a `422 validation_error` is returned. The “fields” messages in this case will be the list of IDs that are duplicated.
If any of the IDs in either the “enable” or “disable” lists are invalid (or pertain to matches that are not on the given monitor), a `422 validation_error` is returned. The “fields” messages in this case will be the list of IDs that are invalid.
### Force new report creation (BETA)
`POST /v3.6/watchlist_monitors//new_report`
Triggers a new check with an updated report to be generated by the monitor, as if the monitor had received an update.
The report generated will not have any new information (as it is pulling from the same information as the previous report), but if matches have been newly enabled or disabled, the overall results may be different. For example, if all matches have been disabled, this will generate a “clear” report.
This endpoint has no request body.
If a new report is successfully generated, it will return a `201 Created` response with no response body.
A link to the newly generated report will be listed in the “Location” header of the response.
```
HTTP/1.1 201 Created
Content-Type: application/json
Location: "/api/v3.5/checks/"
```
## Timeline Files
A Timeline File is an audit trail of the end-to-end IDV process performed on an Applicant through a Workflow Run, provided in PDF format.
It includes all the Workflow Tasks performed in chronological order, alongside some additional information. You can find more details about the Timeline File in the [Studio product guide](/getting-started/workflow-studio-product#workflow-run-timeline-files-beta).
The Timeline File for a Workflow Run is generated on demand by invoking the [Create Timeline File](#create-timeline-file-for-workflow-run-beta) endpoint.
Since the generation of the Timeline File can take between a few seconds and a few minutes (depending on the number of Tasks the Workflow Run has), the process is executed asynchronously.
As such, as soon as file generation begins, the Create Timeline File endpoint will immediately return a `202 Accepted` HTTP response.
The recommended way to be notified when the generation finishes and the Timeline File is available is to subscribe to the [`workflow_timeline_file.created`](#timeline-file-created-event-object) webhook event. The payload of this webhook contains a pre-signed URL to download the file directly from Entrust's storage.
Alternatively, you may poll the [Retrieve Timeline File](#retrieve-timeline-file-for-workflow-run-beta) endpoint until the file is made available. To do so, you use the Timeline File unique identifier returned by the Create Timeline File endpoint.
While the file is under generation, the Retrieve Timeline File endpoint will return a `404 Not Found` HTTP response because the resource is not yet created. When the file becomes available, the endpoint returns a `302 Found` HTTP status with a pre-signed URL to download the file in the `Location` header.
> ⚠️ **Warning:** **Note**: For security reasons, the pre-signed URLs provided in both the Webhook and the Retrieve Timeline File endpoint have an expiration interval of 7 days. If you fail to download the file within this timeframe, you may call the Retrieve Timeline File again and a refreshed pre-signed URL will be returned in the `Location` header.
As an alternative to using our API, the Timeline File can also be downloaded from your Dashboard, on the [Workflow Run results page](https://dashboard.onfido.com/results).
The Timeline File is not signed, and must not be mistaken for the Evidence File contained in the [Evidence Folder](#retrieve-workflow-run-evidence-folder). If you are looking to implement an ETSI certified Workflow solution, please read the documentation about the Evidence Folder in our [product guide](/guide/etsi-certified-idv/).
> ⚠️ **Warning:** **Note**: The Timeline File may contain sensitive personal identifiable information (PII). The pre-signed URLs allow downloading the Timeline File and should be handled carefully.
### Create Timeline File for Workflow Run
`POST /v3.6/workflow_runs/{workflow_run_id}/timeline_file`
Triggers the generation of the Timeline File for the designated Workflow Run.
The Timeline File can only be generated if the Workflow Run is in a terminal status:
* `Abandoned`
* `Error`
* `Approved`
* `Review`
* `Declined`
Given that the generation of the Timeline File takes some time, the process is executed asynchronously in the background. As such, this endpoint will return a `202 Accepted` HTTP response as soon as the file generation begins. The response includes the unique identifier of the file that will be generated.
The recommended way to be notified of the completion of the file generation is by subscribing to the [`workflow_timeline_file.created`](#timeline-file-created-event-object) webhook event.
Alternatively, you may poll the [Retrieve Timeline File](#retrieve-timeline-file-for-workflow-run-beta) endpoint.
#### [Path parameters](#create-workflow-run-timeline-file-path-parameters)
`workflow_run_id` (required): the unique identifier of the Workflow Run for which you want to start the generation of the Timeline File.
### Retrieve Timeline File for Workflow Run
`GET /v3.6/workflow_runs/{workflow_run_id}/timeline_file/{timeline_file_id}`
Retrieves the Timeline File for the designated Workflow Run.
After a successful call, a `302 Found` HTTP status is returned with a pre-signed URL to download the Timeline File in the `Location` header.
The Timeline File should be available some time after its generation was triggered by calling the [Create Timeline File](#create-timeline-file-for-workflow-run-beta) endpoint. However, the generation time varies depending on the size of the Workflow Run, with Workflows Runs having more tasks and media captured taking more time to generate the file.
#### [Path parameters](#create-workflow-run-timeline-file-path-parameters)
`workflow_run_id` (required): the unique identifier of the Workflow Run for which you want to retrieve a Timeline File.
`timeline_file_id` (required): the unique identifier of the Timeline File.
> ⚠️ **Warning:** **Note**: The Timeline File may contain sensitive personal identifiable information (PII). The pre-signed URLs allow downloading the Timeline File and should be handled carefully.
## Webhooks
### About webhooks
Entrust provides webhooks to alert you of changes in the status of your verification journeys. These are POST requests to your server that are sent as soon as a specified
event occurs. The body of the request (the **payload object**) contains details of the [event](#events).
You can create and configure up to 20 webhooks to receive status changes
from live, [sandbox](#sandbox-testing) or both environments. These can be fully managed and configured through the dashboard.
#### Retry logic
Upon receiving a webhook notification, you should acknowledge success by
responding with an HTTP `20x` response within 10 seconds. Otherwise, we will
attempt to resend the notification 5 times according to the following
schedule:
* 30 seconds after the first attempt
* 2 minutes after the first attempt
* 15 minutes after the first attempt
* 2 hours after the first attempt
* 10 hours after the first attempt
We also use circuit breaking for webhooks: if any 5 requests to the same
webhook fail in a row, then that webhook will be disabled for one minute.
The webhook response body shown in the dashboard is truncated to a maximum of 500 characters. If your endpoint returns a longer response, only the first 500 characters will be displayed.
#### Testing
You can quickly inspect webhook requests with temporary
endpoint URLs. You can create these using free hosted services such as
[https://webhook.site](https://webhook.site).
#### Security
The webhook URL must use HTTPS and both `TLSv1.2` and `TLSv1.3` versions are supported.
#### Duplicate events
We guarantee at-least-once delivery of webhooks, which means that in rare occasions you may receive duplicate events. You should treat events as **idempotent** to avoid unwanted effects in your application.
#### Ordering
Entrust doesn't guarantee order when delivering events. As a result, you may receive an event before another event that was created earlier. You should expect to receive them out of order and handle them accordingly.
### Webhook object
| Attribute | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | **string**
The unique identifier for the webhook. |
| url | **string**
The url to listen to notifications (must be HTTPS). |
| enabled | **Boolean**
Determines if the webhook should be active. If omitted, will be set to true by default. |
| events | **array**
The events that should be published to the webhook. If omitted, all events will be subscribed by default. You can read about [the supported events](#events). |
| token | **string**
The webhook token (read more about [verifying webhook signatures](#verifying-webhook-signatures)). |
| href | **string**
The URI of this resource. |
| environments | **array**
Lists the environments that the webhook will receive events from. |
| payload\_version | **integer**
[Webhook version](/api/api-versioning-policy#webhook-events) used to control the payload object when sending webhooks. |
| oauth\_enabled | **Boolean**
Determines if the webhook will fetch OAuth access tokens to send in the Authorization header. |
| oauth\_server\_url | **string**
The url to fetch the OAuth access token using client credentials grant. |
| oauth\_server\_client\_id | **string**
The client id to authenticate the client credentials grant. |
| oauth\_server\_client\_secret | **string**
The client secret to authenticate the client credentials grant. |
| oauth\_server\_scope | **string**
The scopes to be sent when requesting the access token. |
### Webhook IP addresses
All webhook requests will come from the following IPs:
Europe:
* `52.51.171.25`
* `52.51.228.228`
* `52.51.234.203`
United States:
* `34.232.2.222`
* `52.55.124.58`
* `34.224.182.19`
Canada:
* `15.223.105.11`
* `15.222.176.53`
* `15.222.71.172`
Please make sure that you allow these IPs in order to receive webhook
notifications.
### [Events](#events)
By default, webhooks are subscribed to all events, but can be subscribed to a
subset using the `events` array.
Beware that some webhooks payload may contain personal data, such as `audit_log.created`, `watchlist_monitor.matches_updated`, or Studio related resources (workflow\_\* events).
You can configure any of the following events to trigger a message to registered webhooks:
#### General webhook events
| Resource | Events | Description |
| ------------------ | ----------------------------------- | ---------------------------------------------------------------------------------------------- |
| audit\_log | audit\_log.created | An audit log has been created. It requires to have audit logs enabled in your Entrust account. |
| watchlist\_monitor | watchlist\_monitor.matches\_updated | An ongoing monitor has new matches. |
#### Studio webhook events
| Resource | Events | Description |
| ------------------------------- | --------------------------------------- | ------------------------------------------------------------- |
| workflow\_run | workflow\_run.completed | A workflow run has been completed. |
| workflow\_run | workflow\_timeline\_file.created | A Workflow Run Timeline File has been generated. |
| workflow\_task | workflow\_task.started | A new task of a workflow run has started. |
| workflow\_task | workflow\_task.completed | A workflow task has been completed. |
| workflow\_timeline\_file | workflow\_timeline\_file.created | A timeline file has been created for a given workflow run. |
| workflow\_run\_evidence\_folder | workflow\_run\_evidence\_folder.created | An evidence folder has been created for a given workflow run. |
#### Checks and reports webhook events
> ℹ️ **Note:** **Please note**: This set of webhook events is relevant only to customers who have yet to migrate to Workflow Studio and are integrated using our Checks and Reports API.
| Resource | Events | Description |
| -------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| check | check.started | A check has been started. When [`applicant_provides_data`](#applicant-provides-data) is `true`, this indicates the applicant has submitted all required information. |
| check | check.reopened | A check has been reopened. This indicates the applicant needs to re-submit required information. |
| check | check.withdrawn | A check has been withdrawn. |
| check | check.completed | A check has been completed. |
| check | check.form\_completed | An applicant has submitted their information using the check form. |
| report | report.withdrawn | A report has been withdrawn. |
| report | report.resumed | A paused report has been resumed. |
| report | report.cancelled | A paused report has been canceled. |
| report | report.awaiting\_approval | A report has transitioned to the "Awaiting Approval" status. |
| report | report.completed | A report has been completed and results are available. |
### [Event object](#webhook-event-object)
#### Attributes
| Attribute | Description |
| -------------- | ---------------------------------------------------------------------------------------------------------------------- |
| payload | **object**
The top level element. |
| resource\_type | **string**
Indicates the resource affected by this event. |
| action | **string**
The event that triggered this webhook, e.g. `report.completed`. |
| object | **object**
The object affected by this event. This will contain an `id` and an `href` to retrieve that resource. |
### [Workflow run completed event object](#workflow-run-completed-webhook-event-object)
The webhook event `workflow_run.completed` is fired upon completion of a Workflow Run.
#### Attributes
| Attribute | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| resource\_type | **string**
Indicates the resource affected by this event. |
| action | **string**
The event that triggered this webhook, e.g. `workflow_run.completed`. |
| object | **object**
The object affected by this event. This will contain an `id` and an `href` to retrieve that resource. |
| resource | **object**
An attribute unique to Workflow webhooks, containing the [Workflow Run object](#workflow-run-object) affect by this event. |
### [Workflow task started event object](#workflow-task-started-webhook-event-object)
The webhook event `workflow_task.started` is fired when a new Task of the Workflow Run starts.
#### Attributes
| Attribute | Description |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| resource\_type | **string**
Indicates the resource affected by this event. |
| action | **string**
The event that triggered this webhook, `workflow_task.started`. |
| object | **object**
The object affected by this event. This will contain an `id` and an `href` to retrieve that resource. |
| resource | **object**
An attribute unique to Workflow webhooks, containing the [Task object](#task-object) affected by this event. |
### [Workflow task completed event object](#workflow-task-completed-webhook-event-object)
The webhook event `workflow_task.completed` is fired upon completion of a Workflow task.
#### Attributes
| Attribute | Description |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| resource\_type | **string**
Indicates the resource affected by this event. |
| action | **string**
The event that triggered this webhook, `workflow_task.completed`. |
| object | **object**
The object affected by this event. This will contain an `id` and an `href` to retrieve that resource. |
| resource | **object**
An attribute unique to Workflow webhooks, containing the [Task object](#task-object) affected by this event. |
### [Timeline File created event object](#timeline-file-created-event-object)
The webhook event `workflow_timeline_file.created` is fired upon the generation of a Timeline File for a Workflow Run.
#### Attributes
| Attribute | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| resource\_type | **string**
Indicates the resource affected by this event. |
| action | **string**
The event that triggered this webhook, `workflow_timeline_file.created`. |
| object | **object**
The object affected by this event. This will contain an `id` and an `href` to retrieve that resource. |
| resource | **object**
An attribute unique to Workflow webhooks, containing the `timeline_file_download_url` needed to download the Timeline File affected by this event. |
**Note**: The Timeline File may contain sensitive personal information (PII). The pre-signed URLs allow downloading the Timeline File and should be handled carefully.
### [Watchlist monitor matches updated event object](#watchlist-monitor-matches-updated-webhook-event-object)
The webhook event `watchlist_monitor.matches_updated` is fired when there are new matches on an ongoing monitor.
#### Attributes
| Attribute | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------- |
| resource\_type | **string**
Indicates the resource affected by this event. |
| action | **string**
The event that triggered this webhook, `watchlist_monitor.matches_updated`. |
| object | **object**
The object affected by this event. This will contain details about who and what was performed. |
| resource | **object**
An attribute containing the resource affected by this event. |
### [Workflow Run Evidence Folder created event object](#workflow-run-evidence-folder-created-event-object)
The webhook event `workflow_run_evidence_folder.created` is fired upon the generation of the Evidence Folder for a Workflow Run.
#### Attributes
| Attribute | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| resource\_type | **string**
Indicates the resource affected by this event. |
| action | **string**
The event that triggered this webhook, `workflow_run_evidence_folder.created`. |
| object | **object**
The object affected by this event. This will contain the `href` to retrieve that resource. |
| resource | **object**
An attribute containing the resource affected by this event. This will contain a `workflow_run_id` and the `created_at` relative to the resource. |
**Note**: The Evidence Folder may contain sensitive personal information (PII).
### [Audit log created event object](#audit-log-created-webhook-event-object)
The webhook event `audit_log.created` is fired when a new Dashboard Audit log is created. You can view all the available types [here](https://support.identity.entrust.com/s/article/How-Long-Are-Audit-Logs-Retained-in-the-Onfido-Dashboard).
#### Attributes
| Attribute | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------- |
| resource\_type | **string**
Indicates the resource affected by this event. |
| action | **string**
The event that triggered this webhook, `audit_log.created`. |
| object | **object**
The object affected by this event. This will contain details about who and what was performed. |
### Webhook event versioning
Refer to our [API versioning guide](/api/api-versioning-policy#webhook-events) for details on webhook event versioning.
### OAuth authentication
You are able to enhance the security of your webhooks with the use of an [OAuth Client Credentials Grant](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/).
Each webhook can be configured independently to fetch an access token when sending the webhook request to your server. The expected response should follow the [OAuth specification](https://www.oauth.com/oauth2-servers/access-tokens/access-token-response/) and the token type must be "Bearer".
The necessary fields can be configured through the [Register webhook](#register-webhook) and [Edit webhook](#edit-webhook) endpoints, or your Dashboard "Webhook Management" page:
* `oauth_enabled`
* `oauth_server_url`
* `oauth_server_client_id`
* `oauth_server_client_secret`
* `oauth_server_scope`
For each webhook, the access token is cached for 5 minutes to avoid the congestion of your authorization server.
### Verifying webhook signatures
You should verify request signatures on your server to prevent attackers from
imitating valid webhook events.
Each [webhook you register](#register-webhook) will return a single secret
token in the `token` field of the API response body, which is used to generate
an HMAC using SHA-256. You only need to register a webhook once. The token for
each webhook is also displayed on your Dashboard ‘Webhook Management’
page.
If possible, we recommend that you verify request signatures with our
supported client libraries in your integration.
The following [client libraries](#client-libraries) have support built
in:
* Java
* Node
* PHP
* Python
* Ruby
#### Using client libraries
You must initialize the verifier instance with your webhook’s secret token. For each webhook event, the verifier instance needs:
* the signature of the webhook (from the `X-SHA2-Signature` header)
* the body of the event request (must be in raw format, not decoded from JSON)
#### Manually
We provide a [detailed guide](/api/manual-webhook-signature-verification/)
for manually verifying webhook signatures.
### Register webhook
`POST /v3.6/webhooks/`
Registers a webhook. Returns a [webhook object](#webhook-object).
You can read more about [how to verify request signatures on your
server](#verifying-webhook-signatures).
> ⚠️ **Warning:** You cannot use sandbox tokens to create or manage
> webhooks for live environments.
#### [Request body parameters](#webhook-request-body)
| Parameter | Description |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| url | **required**
The url that will listen to notifications (must be HTTPS). |
| name | **optional**
The name to identify the webhook. |
| enabled | **optional**
Determine if the webhook should be active.
If omitted, will be set to true by default. |
| environments | **optional**
The environments from which the webhook will receive events.
Allowed values are "sandbox" or "live" but sandbox tokens cannot be used for the "live" environment.
If omitted (with a live token), the webhook will receive events from both environments. |
| events | **optional**
The events that should be published to the webhook. If omitted, all events will be subscribed by default. You can read about [the supported events](#events). |
| payload\_version | **optional**
The version used for the payload. |
#### Register a webhook using the Dashboard
You can also register webhooks through the [Dashboard](https://dashboard.onfido.com/api/webhook_management).
#### Webhook logs
To help you diagnose webhook issues, you can review logs on the [Dashboard](https://dashboard.onfido.com/api/webhook_log).
### List webhooks
`GET /v3.6/webhooks/`
Lists all webhooks you've created.
Returns data in the form: `{"webhooks": []}`.
### Retrieve webhook
`GET /v3.6/webhooks/{webhook_id}`
Retrieves a single webhook. Returns a [webhook object](#webhook-object).
### Edit webhook
`PUT /v3.6/webhooks/{webhook_id}`
Edits a webhook. Returns the updated [webhook object](#webhook-object).
### Delete webhook
`DELETE /v3.6/webhooks/{webhook_id}`
Deletes a webhook. If successful, returns a `204 No Content` response.
### Resend webhooks
`POST /v3.6/webhooks/resend`
Resends events to all webhooks registered with a matching environment
in your account. Returns a `204 No Content` response.
There is a limit of 20 resources for the maximum number of objects that can be
defined in the request body.
A resend can only be issued if the webhook event for the given `resource_id` was triggered in the past 30 days.
#### [Request body parameters](#webhook-request-body)
| | |
| ------------ | -------------------------------------------------------------------------------------- |
| resource\_id | **required**
ID of the resource whose webhooks are to be retriggered. |
| event | **required**
The event that should retrigger webhooks. All events are accepted. |
#### Event to resource id mapping
Below you can find the correct `resource_id` that matches the webhook event when resending a webhook:
##### Workflow Studio
| Event | Resource id |
| --------------------------------------- | ----------------------------- |
| workflow\_run.completed | `` |
| workflow\_timeline\_file.created | `` |
| workflow\_task.started | `:` |
| workflow\_task.completed | `:` |
| workflow\_timeline\_file.created | `` |
| workflow\_run\_evidence\_folder.created | `` |
##### Checks and Reports API
> ℹ️ **Note:** **Please note**: This set of webhook events is relevant only to customers who have yet to migrate to Workflow Studio and are integrated using our Checks and Reports API.
| Event | Resource id |
| ----------------------------------- | -------------- |
| check.started | `` |
| check.reopened | `` |
| check.withdrawn | `` |
| check.completed | `` |
| check.form\_completed | `` |
| report.withdrawn | `` |
| report.resumed | `` |
| report.cancelled | `` |
| report.awaiting\_approval | `` |
| report.completed | `` |
| watchlist\_monitor.matches\_updated | `` |
## Watchlist alert risks
The Watchlist alert risks endpoint retrieves the detailed risk records associated with a watchlist alert generated by a watchlist screening.
For one-off screenings, use the `alert_identifier` returned by the **Query watchlists** task (`task_def_id` `query_watchlists_complyadvantage_mesh`). The same endpoint can also be used for alerts generated through ongoing monitoring. The response is paginated and returns an array of watchlist alert risk objects. The total number of risks is returned in the `X-Total-Count` response header.
### Watchlist alert risk object
| Attribute | Description |
| --- | --- |
| created_at | **datetime**
The date and time at which the risk record was created. |
| decision | **string**
The review decision currently applied to the risk. Possible values include `NOT_REVIEWED`, `IN_REVIEW`, `FALSE_POSITIVE`, and `TRUE_POSITIVE`. |
| previous_decision | **string** or **null**
The previous review decision, if one exists. |
| detail | **object**
Additional detail about the risk, including the matched profile, screening configuration, and any newly added mentions. |
| identifier | **string**
The unique identifier of the risk record. |
| type | **string**
The type of risk returned for the alert. |
| updated_by | **string** or **null**
The identifier of the user or system that last updated the risk decision. |
| updated_at | **datetime** or **null**
The date and time at which the risk record was last updated. |
### Retrieve watchlist alert risks
`GET /v3.6/complyadvantage_watchlists/alerts/{alert_id}/risks?page={page}&per_page={per_page}`
Retrieves the detailed risks associated with a watchlist alert. Returns an array of [watchlist alert risk objects](#watchlist-alert-risk-object). For one-off screenings, the `alert_id` comes from the **Query watchlists** task (`task_def_id` `query_watchlists_complyadvantage_mesh`). The total number of risks is returned in the `X-Total-Count` response header.
Returns `404 Not Found` if the alert does not exist.
#### [Path parameters](#retrieve-watchlist-alert-risks-path-parameters)
`alert_id` (required): the unique identifier of the alert whose risks you want to retrieve.
#### [Query string parameters](#retrieve-watchlist-alert-risks-query-string-parameters)
| Parameter | Description |
| --- | --- |
| page | **optional**
The page of results to retrieve. Defaults to `1`. |
| per_page | **optional**
The number of risks to return per page. Defaults to `25`. |
# Other Endpoints
The documentation in the sections below is aimed at customers who are integrating Entrust identity verification journeys using our Checks and Reports API (also known as a Classic integration), and are yet to migrate to [Workflow Studio](/getting-started/workflow-studio-product/).
The Checks and Reports endpoints detailed here rely on you manually creating identity verification checks, rather than taking advantage of the dynamic, conditional workflows defined in Workflow Studio.
Workflow Studio is Entrust's orchestration platform enabling you to design and implement identity journeys through an intuitive drag-and-drop interface, minimising the need for custom integration code. It provides a high level of configurability and adaptability and is Entrust's recommended method of integration.
To learn more about migrating to Workflow Studio, contact Entrust's [**Customer Support** team](mailto:identity-support@entrust.com) or explore our [migration guide](/getting-started/classic-to-studio-migration/).
> ⚠️ **Warning:** **Please note**: For customers with accounts configured exclusively for integration with Workflow Studio, all Checks and Reports endpoints are disabled and you will receive a [403 disabled\_endpoint](#error-codes-and-what-to-do) error if you attempt to use them.
> If you believe your account may be affected or you are unsure about your current account configuration, please reach out to your Customer Success Manager or contact our [Support team](mailto:identity-client-support@entrust.com).
## Checks endpoints
Checks are performed on an [applicant](#applicants) and consist of one or more [reports](#reports).
> ⚠️ **Warning:** **Please note**: The Checks endpoints documented here are only applicable to customers who have yet to migrate to Workflow Studio and are manually requesting identity verifications using our API. When integrating with Studio workflows, checks are created automatically based on your specific workflow implementation.
> For customers with accounts configured exclusively for integration with Workflow Studio, these Checks endpoints are disabled and you will receive a [403 disabled\_endpoint](#error-codes-and-what-to-do) error if you attempt to use them.
> If you believe your account may be affected or you are unsure about your current account configuration, please reach out to your Customer Success Manager or contact our [Support team](mailto:identity-client-support@entrust.com).
### Check object
| Attribute | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | **string**
The unique identifier for the check. |
| created\_at | **datetime**
The date and time at which the check was initiated. |
| webhook\_ids | **array of strings**
The list of registered [webhook](#webhook-object) IDs to notify as part of this check. Unless the value is included during check creation, this parameter will be `null`. |
| href | **string**
The API endpoint to retrieve the check. |
| applicant\_provides\_data | **Boolean**
Run an applicant\_provides\_data check or not. Default is `false`. |
| applicant\_id | **string**
The ID for the applicant associated with the check. |
| status | **string**
The current state of the check in the checking process. |
| tags | **array of strings**
A list of tags associated with this check. |
| result | **string**
The overall result of the check, based on the [results of the reports used](#report-results). |
| form\_uri | **string**
A link to the applicant form, if `applicant_provides_data` is `true`. |
| redirect\_uri | **string**
For checks where `applicant_provides_data` is `true`, redirect to this URI when the applicant has submitted their data. |
| results\_uri | **string**
A link to the corresponding results page on the Dashboard |
| report\_ids | **array of strings**
The list of [report object](#report-object) IDs associated with the check. |
| sandbox | **Boolean**
Indicates whether the object was created in the sandbox or not. |
#### Check status
| Status | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| in\_progress | We are currently processing the check. |
| awaiting\_applicant | The applicant has not yet submitted the applicant form, either because they have not started filling the form out or because they have started but have not finished. |
| complete | All reports for the applicant have been completed or withdrawn. |
| withdrawn | The check has been withdrawn. |
| paused | The check is paused until you (the client) switch it on manually. Special case used by clients who wants to collect data and run the checks when they want and not immediately. |
| reopened | Insufficient or inconsistent information was provided by the applicant, and the report has been bounced back for further information. |
### Check results
The value of the check is derived from the [results of the individual reports](#report-results) that it contains:
| Check result | Description |
| ------------ | ----------------------------------------------------------------------------------------------- |
| clear | If all the reports contained in the check have `clear` as their results. |
| consider | If any reports contained in the check have either `consider` or `unidentified` as their result. |
### Create check
`POST /v3.6/checks/`
> ⚠️ **Warning:** **Please note**: This endpoint is only applicable to customers who have yet to migrate to Workflow Studio and are manually requesting identity verifications using our Checks and Reports API.
> For customers with accounts configured exclusively for integration with Workflow Studio, this endpoint is disabled and you will receive a [403 disabled\_endpoint](#error-codes-and-what-to-do) error if you attempt to use it.
> ⚠️ **Warning:** Using this endpoint in a live context will cause you to
> create a check using an applicant's personal data. Always make sure you inform
> your users about this and obtain any necessary permissions. For more
> information on how Entrust uses personal data, view our [Privacy
> Policy](https://onfido.com/privacy/).
Initiates a check for [an applicant](#applicants), which can contain one or
more [reports](#reports). Returns a [check object](#check-object).
Having created the first check, you are allowed to create further checks for
the same applicant, as long as the previous check is not still ongoing (i.e.
check has been completed, withdrawn or canceled). You will receive an error
message if you try to create a check for an applicant with an ongoing check.
If you are creating multiple checks for the same applicant you should reuse the same `applicant_id` in every check request. This ensures all checks are associated with the same individual.
When creating checks, you must use the `report_names` field (which takes an
array of strings). For example, to create a check with 2 reports:
`"report_names": ["report_name_1", "report_name_2"]`
### Required applicant data
The following applicant data is required for all checks. Each report type may also require additional applicant data in order to be processed.
**Location**
You must provide location information for each applicant before creating a check with either Document, Facial Similarity or Known Faces reports. You can include `location`as part of your API request when [creating an applicant](#location-create-applicant) or [uploading a document](#location-upload-document). If you do not provide `location` all check requests will fail with a validation error.
**Consent**
If the location of the applicant is the US, you must also provide consent information confirming that the end user has viewed and accepted Entrust’s privacy notices and terms of service. You can specify `consents` as part of your API request when [creating](#consents) or [updating](#update-applicant) an applicant. If `privacy_notices_read` is not set to `"granted": true`, all check requests will fail with a validation error.
> ℹ️ **Note:** If you use the Entrust Identity Verification SDK, location and consent is collected directly by the SDK. You do not need to manually provide the `location` or `consents` parameter in this case.
> **Note:** For more information on the requirements and implementation options for collecting US end user consent please see our [Privacy notices and consent guide](/guide/onfido-privacy-notices-and-consent/).
### [Request body parameters](#create-check-request-body)
| Parameter | Description |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| applicant\_id | **required**
The ID of the applicant to run the check on. |
| report\_names | **required**
Array of strings describing [reports requested for the check](#report-names-in-api). |
| document\_ids | **optional**
Array of strings describing which document to process in checks containing a [Document](#document-report) report, a [Facial Similarity](#facial-similarity-reports) report or both, which takes a maximum of 2 strings (document IDs) 1. By default, the most recently uploaded document is used. `document_ids` is only usable with Document and Facial Similarity reports.
**Note:** `document_ids` is a **required parameter** for [Document Video Report](guide/document-report/#document-video-report) and [Document report with NFC](/guide/document-report-nfc#start-here). For Document Report with NFC, you must specify the NFC media ID at check creation, in which case the maximum number of strings is 3. |
| applicant\_provides\_data | **optional**
Default is `false`. If `true`, applicant provides required information and documents using the Entrust applicant form. |
| asynchronous | **optional**
Default is `true`.2 It’s strongly recommended that you leave this as the default, and configure [webhooks](#webhooks) to notify you when a check or report is complete. |
| tags | **optional**
Array of tags being assigned to this check. |
| suppress\_form\_emails | **optional**
For checks where [`applicant_provides_data`](#applicant-provides-data) is `true`, applicant form will not be automatically sent if `suppress_form_email` is `true`. You can manually send the form at any time after the check has been created, using the link found in the form\_uri attribute of the check object.
Defaults to `false` (i.e., form will be sent automatically by default). |
| redirect\_uri | **optional**
For checks where [`applicant_provides_data`](#applicant-provides-data) is `true`, redirect to this URI when the applicant has submitted their data. |
| consider | **optional**
Array of names of particular reports to return `consider` as their results. This is a feature available in [sandbox testing](#sandbox-testing) which you can [read more about](/#pre-determined-responses-for-multiple-report-checks). |
| webhook\_ids | **optional**
Array of strings describing which [webhooks to trigger for this check](#webhooks). By default, all webhooks registered in the account will be triggered and this value will be null in the responses. |
| us\_driving\_licence | **optional**
An object that contains all accepted fields for the Driver's License Data Verification report. |
| report\_configuration | **optional**
An object that contains all configuration options for facial similarity checks used to distinguish between onboarding and reverification scenarios **(Deprecated)**. |
1: For a check containing a Document and Facial Similarity report, you only need to specify 1 document ID which will be used for both reports. You should only specify 2 document IDs when the uploaded document has a front and a back side. If 2 document IDs are submitted in any other case, the Document report will be rejected for [Image Quality: `two_documents_uploaded`](#image-quality-reasons).
2: If `asynchronous` is set to `false`:
* the request to create a check will only return a response when all the reports in the check complete the automatic part of the review, or the request times out after 29 seconds
* if all reports are completed automatically, the check response is returned with a status of `complete`
* if one of the reports goes to manual review (the status of the report is `awaiting_approval`) the check response is returned with a status of `in_progress`
* a check created in sandbox will always complete automatically and never time out, so may not give an accurate representation of the behavior
#### [webhook\_ids](#webhook_ids)
> ℹ️ **Note:** The majority of users do not need to set this parameter. By default, events will be sent to all configured webhooks.
If you need a check to only trigger a subset of your webhooks (for example, if you have multiple regional specific webhooks subscribed to `report.completed`), you can list the IDs of the webhooks this check should trigger by passing the following array as part of your check request:
`"webhook_ids": ["", "", ...]`
If an invalid webhook ID is included in the list, that ID will be ignored and the request will be
processed as though it were not included.
Omitting `webhook_ids` from the request, or including any of the following in your request
will cause the default behavior of setting the check to trigger all webhooks you've created:
* `"webhook_ids": undefined`
* `"webhook_ids": null`
* `"webhook_ids": []`
To make a check ignoring all webhooks you've created, pass the following as part of your check
request:
`"webhook_ids": ["no_webhooks"]`
If any webhook IDs are included in addition to `"no_webhooks"`, you will receive an error.
Inclusion of a webhook ID in `webhook_ids` does not affect the type of events that webhook is
subscribed to.
### Report names in API
The following table is of report names as they are described in the API.
| Report name | API report name(s) |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Document | document |
| Document Video Report | document\_video |
| Document with Address Information | document\_with\_address\_information |
| Document with Driving License Information | document\_with\_driving\_licence\_information |
| Facial Similarity | facial\_similarity\_photo
facial\_similarity\_photo\_fully\_auto
facial\_similarity\_video
facial\_similarity\_motion |
| Known Faces | known\_faces |
| Identity | identity\_enhanced |
| Watchlist | watchlist\_aml
watchlist\_enhanced
watchlist\_standard
watchlist\_peps\_only
watchlist\_sanctions\_only |
| Proof of Address | proof\_of\_address |
| Driver's License Data Verification | us\_driving\_licence |
| Device Intelligence | device\_intelligence |
| Document with Driver Verification | document\_with\_driver\_verification |
> **Note:** When creating a check, pass these in an array of strings to `report_names`.
### Retrieve check
`GET /v3.6/checks/{check_id}`
Retrieves a single check. Returns a [check object](#check-object).
> ⚠️ **Warning:** **Please note**: When integrating with Studio workflows, the status of verification checks is managed by workflow run output and can be retrieved by making a call to the [Retrieve Workflow Run endpoint](#retrieve-workflow-run). For customers with accounts configured exclusively for integration with Workflow Studio, this endpoint is disabled and you will receive a [403 disabled\_endpoint](#error-codes-and-what-to-do) error if you attempt to use it.
### List checks
`GET /v3.6/checks?applicant_id={applicant_id}`
Returns all checks for an applicant. Returns data in the form: `{"checks": []}`.
#### [Query string parameters](#list-checks-query-string-parameters)
`applicant_id` (required): the ID of the applicant whose checks you want to list.
### Resume check
`POST /v3.6/checks/{check_id}/resume`
Resumes a paused check. If successful, returns a `204 No Content` response.
A check is paused if all the reports that it contains are in the paused state.
When a check where [`applicant_provides_data`](#applicant-provides-data) is `true` gets resumed, all its reports will start processing immediately if the applicant has already submitted the form. The check status will automatically change to `in_progress`. Otherwise, the check will remain as `awaiting_applicant` and the reports will only start processing after the applicant submits the form.
### Download check
`GET /v3.6/checks/{check_id}/download`
Downloads a PDF of a check with a given check ID. Returns the binary data representing the PDF.
## Reports endpoints
In our API, [checks](#checks) are composed of one or more
reports.
> ⚠️ **Warning:** **Please note**: The Reports endpoints documented here are only applicable to customers who have yet to migrate to Workflow Studio and are manually requesting identity verifications using our API. When integrating with Studio workflows, reports are generated based on your specific workflow implementation.
> For customers with accounts configured exclusively for integration with Workflow Studio, these Reports endpoints are disabled and you will receive a [403 disabled\_endpoint](#error-codes-and-what-to-do) error if you attempt to use them.
> If you believe your account may be affected or you are unsure about your current account configuration, please reach out to your Customer Success Manager or contact our [Support team](mailto:identity-client-support@entrust.com).
### Report object
The report object will differ depending on the report itself.
| Attribute | Description |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | **string**
The unique identifier for the report. |
| created\_at | **datetime**
The date and time at which the report was first initiated. |
| name | **string**
The [type of report](#report-names-in-api). |
| href | **string**
The API endpoint to retrieve the report. |
| status | **string**
The current state of the report in the checking process. |
| result | **string**
The [result](#report-results) of the report (`null` if report is incomplete). |
| sub\_result | **string**
The [sub\_result](#sub-results) of the report. It gives a more detailed result for Document reports only, and will be `null` otherwise. |
| breakdown | **object**
The details of the report. This is specific to each type of report. |
| properties | **object**
The properties associated with the report, if any. |
| documents | **array**
The document IDs that were processed. Populated for [Document](#document-report) and [Facial Similarity](#facial-similarity-reports) reports, otherwise an empty array. |
| check\_id | **string**
The ID of the [check](#checks) to which the report belongs. |
The `breakdown` object differs for each report type. For example, for
[Document reports](#document-report).
### Report status
| Status | Description |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| awaiting\_data | Entrust has made a request to one of its data providers and we are waiting on their reply. |
| awaiting\_approval | Report is undergoing manual review. |
| cancelled | Report has been canceled using the [cancel report](#cancel-report) endpoint. |
| complete | Report is done. |
| withdrawn | Report has been automatically withdrawn by the system. For example, due to missing data. |
| paused | Report is paused until you, i.e. the client, switch it on manually. Special case used by clients who want to collect data and run the reports when they want and not immediately. |
### Report results
The `result` field indicates the overall result of a report. The possible values of this field are:
| Report result | Description |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| clear | If all underlying verifications pass, the overall result will be `clear`. |
| consider | If the report has returned information that needs to be evaluated, the overall result will be `consider`. |
| unidentified | For [Identity Enhanced](#identity-enhanced-report) and [Driver's License Data Verification](#drivers-license-data-verification-report) reports only. |
| null | For [Proof of Address](#proof-of-address-report) reports only. |
### Sub results (Document reports)
The `sub_result` field indicates a more detailed result and is unique to [Document reports](#document-report).
| Report sub\_result | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| clear | If all underlying verifications pass, the overall sub result will be `clear`. |
| rejected | If the report has returned information where the check cannot be processed further (poor quality image or an unsupported document). |
| suspected | If the document that is analysed is suspected to be fraudulent. |
| caution | If any other underlying verifications fail but they don't necessarily point to a fraudulent document (such as the name provided by the applicant doesn't match the one on the document). |
### Retrieve report
`GET /v3.6/reports/{report_id}`
Retrieves a single report. Returns a [report object](#report-object).
> ⚠️ **Warning:** **Please note**: When integrating with Studio workflows, the results of reports are managed by workflow run output and can be retrieved by making a call to the [Retrieve Workflow Run endpoint](#retrieve-workflow-run), with results returned in the output attribute. For customers with accounts configured exclusively for integration with Workflow Studio, this endpoint is disabled and you will receive a [403 disabled\_endpoint](#error-codes-and-what-to-do) error if you attempt to use it.
### List reports
`GET /v3.6/reports?check_id={check_id}`
Lists all reports belonging to a particular check. Returns data in the form:
`{"reports": []}`.
#### [Query string parameters](#list-reports-query-string-parameters)
`check_id` (required): the ID of the check whose reports you want to list.
### Resume report
`POST /v3.6/reports/{report_id}/resume`
Resumes a single paused report. If successful, returns a `204 No Content` response.
When an individual report gets resumed in a check where
[`applicant_provides_data`](#applicant-provides-data) is `true`, it will start
processing immediately if the applicant has already submitted the form. The
report status will automatically change from `paused` to `awaiting_data`.
Otherwise, the status change will happen but the report processing will only
start after the applicant submits the form.
Note that you can resume all reports within a check by [resuming the check](#resume-check) itself.
### Cancel report
`POST /v3.6/reports/{report_id}/cancel`
Cancels single paused reports. If successful, returns a `204 No Content` response.
When a report gets canceled in a check where [`applicant_provides_data`](#applicant-provides-data) is `true`, its status will change from `paused` to `cancelled` and the report will never get processed.
## Report Types
## Document report
This API documentation offers detailed information about the structure of a Document report, including an example of the report's result and its breakdowns.
For a more general introduction to the Document report, you can read our
[product documentation](/guide/document-report/).
After you've familiarised yourself with the information here, you can read our guide on [suggested client
actions](/guide/document-report/#suggested-client-actions)
for different result scenarios.
There are 6 different types of Document reports:
* [Document](#document-report) (almost all use cases require this "primary" type)
* [Document Video](#document-video-report)
* [Document with Address Information](#document-with-address-information)
* [Document Video with Address Information](#document-video-report-with-address-information)
* [Document with Driving License Information](#document-with-driving-license-information) (This report will soon be deprecated. We recommend that you use the `document_with_driver_verification` report instead)
* [Document with Driver Verification](#document-with-driver-verification)
| Request body in API | Notes |
| --------------------------------------------------------------- | ----------------------- |
| `"report_names": ["document"]` | Primary Document report |
| `"report_names": ["document_video"]` | Document Video report |
| `"report_names": ["document_with_address_information"]` | In beta |
| `"report_names": ["document_video_with_address_information"]` | In beta |
| `"report_names": ["document_with_driving_licence_information"]` | Will soon be deprecated |
| `"report_names": ["document_with_driver_verification"]` | In beta |
> **Note:** Document with Address Information, Document Video with Address Information and Document with Driver Verification Document are in beta, while Document with Driving License Information will soon be deprecated. They are supersets of the Document report which add functionality for specific use cases. Contact your account manager for more information about the features in these reports.
By default, the most recently uploaded document will be used.
To specify which [uploaded document](#upload-document) to run the Document
report against in the API, or specify document IDs extracted from the SDK callback, use the `document_ids` field. This takes an array
of up to 3 strings (3 document IDs):
`"document_ids": [""]`
The Document report is composed of data integrity, visual authenticity and police record checks. It checks the internal and external consistency of the document provided by the applicant to identify potential discrepancies.
In addition, any data extracted from the document is returned in the `properties` attribute.
The Document report combines software and an expert team to maximise fraud detection. The majority of documents will be processed instantly. However, when document analysis falls back to expert review, the report status will be delivered asynchronously via [webhook notifications](#webhooks).
Expert review is required when we encounter images that use sophisticated counterfeiting techniques, or the image is of poor quality (blurred, low resolution, obscured, cropped, or held at an unreadable angle).
#### Supported Documents
In your [Dashboard](https://dashboard.onfido.com/), you can configure which documents you want to accept in your verification workflow, filtering according to issuing country and document type.
When an applicant submits a restricted document (i.e. a document not included in your supported documents), the `Supported document` [breakdown](/guide/document-report/#breakdown-descriptions) of the Document Report will flag as `consider`, producing a sub-result of `reject`.
#### Near Field Communication (NFC)
If available, the Document report uses NFC to validate the document's chip in order to verify the document. In this case, the visual authentication, image integrity and data consistency checks will not be performed.
**NFC is only available via the Entrust Identity Verification mobile SDKs**, and Entrust highly recommends integrating NFC for Document reports in Workflow Studio. You can read more about NFC in our [NFC for Document report guide](/guide/document-report-nfc/).
When [creating a check](/api/latest/#create-check) for a Document report with NFC using the API, you will need to use API v3.2 or later in order to receive the `issuing_authority` breakdown and sub-breakdowns that contain the details of the NFC verification in the Document report.
The table below outlines the parameters required:
| Parameter | Description |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `applicant_id` (required) | Specifies the applicant for the check. |
| `report_names` (required) | The report name. NFC is available as part of the [primary Document report option](/api/latest/#document-report). |
| `document_ids` (required) | Array including all the document IDs returned in the SDK success callback. This could include up to 3 IDs for the document front side, back side and NFC media. |
You can view the full list of [supported documents for NFC](/guide/supported-documents-nfc/).
#### [Repeat attempts](#repeat-attempts-document-report)
You can also use our [repeat attempts endpoint](#repeat-attempts-1) to request a list of repeat attempt matches for [Document reports](#document-report). A repeat attempt is any previous Document report that was submitted using a document that matches other previously onboarded documents in your Entrust database. This can indicate instances of repeat fraud where users submit multiple requests using the same document but with different personal data.
### [Required applicant data](#document-report-required-applicant-data)
For Document reports, `first_name` and `last_name` must be provided but can be
sample values if you don't know an applicant's name.
### Document type and issuing country
If you’re creating a check containing a Document report, we do not validate
that the properties `type` and `issuing_country` in the [uploaded
document](#upload-document) match extracted values (which are returned in the
Document report object).
### [Document report: Object](#document-report-object)
> **Note:** Our newly expanded [OpenAPI specification](https://github.com/onfido/onfido-openapi-spec) is also a resource for understanding the Document report response object structure.
We host a separate page which contains a detailed description of the [Document report object values](/api/document-report-object/) from an API user's perspective.
#### Results
The `result` field indicates the overall report result. Possible values for
Document reports are `clear` and `consider`:
| Report result | Description |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| clear | If all underlying verifications pass, the overall result will be `clear`. |
| consider | If the report has returned information that needs to be evaluated, the overall result will be `consider`. |
#### Sub-results
The `sub_result` field indicates a more detailed result, and is unique to
Document reports. Possible values of `sub_result` are as follows:
| Sub-result | Description |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| clear | If all underlying verifications pass, the overall sub result will be `clear`. There are no indications the document is fraudulent. |
| caution | We can't successfully complete all verifications, but this doesn’t necessarily point to a suspected document (for example, expired document). |
| suspected | Document shows signs of suspect fraud. |
| rejected | We can't process the document image, or the document isn't supported by Entrust for processing. Another reason is if the age of the applicant is too low (the standard threshold is 16 years old but you can write to your Entrust contact to have this changed). |
### [Document report: Breakdowns](#breakdowns)
Breakdowns can have the values `clear`, `consider` and null.
A breakdown will have the result `consider` when at least one sub-breakdown
contains a `consider` or `unidentified` result. For example, a `consider` result
for the `mrz` sub-breakdown will produce a `consider` result for the
`data_validation` breakdown. This will then also set the report `sub_result`
value to `suspected`.
A breakdown will have the result null when it has not been completed, or is not available. For example, `issuing_authority` will return null if NFC is not available or inconclusive.
Some breakdowns contain sub-breakdowns. For example, the `image_integrity`
breakdown comprises the sub-breakdowns `supported_document`, `image_quality`,
`colour_picture` and `conclusive_document_quality`.
The possible values for sub-breakdowns are `clear`, `consider`, `failed`, `null` and
`unidentified`.
#### Breakdown order priority
Breakdown sub-results have the following order of priority:
`rejected`->`suspected`->`caution`->`clear`
For example, a `caution` sub-result will only ever be asserted when the following
conditions are met:
* no individual breakdown has caused a `rejected` or `suspected` sub-result
* a breakdown which maps to a `caution` sub-result has been flagged
#### Breakdown mapping
Breakdowns and sub-breakdowns are mapped to particular sub-results. Certain mappings can be changed, where possible, depending on your configuration.
**Note:** Some breakdowns have sub-breakdowns that are mapped to different sub-results. For example, in the Data Validation breakdown, `gender`, `document_numbers`, `expiry_date`, `date_of_birth`, `mrz` and `barcode` map to `suspected` whereas `document_expiration` maps to `caution`.
**Note:** When a sub-breakdown mapped to a `rejected` sub-result is flagged, all other breakdowns and the document properties will be omitted from the response object.
#### Breakdown descriptions and logic
#### `data_comparison`:
Establishes whether the data provided by the applicant matches the data extracted from the document.
This breakdown is only returned if Comparison Checks are enabled for your account. Otherwise, the breakdown and its sub-breakdowns are returned as null and will not affect the final report result.
To enable Comparison Checks, please contact [Client Support](mailto:identity-client-support@entrust.com).
We compare the following fields:
* `first_name`
* `last_name`
* `date_of_birth`
* `gender`
`first_name` and `last_name` can be configured to use a fuzzy or exact mechanism for the comparison. We take into account all available names for comparison, including spouse, widow or alias names.
`date_of_birth` and `gender` will always be compared using an exact mechanism.
**Note:** From API v3 onwards, the `gender` field returns a `null` value.
#### Fuzzy comparison
Fuzzy comparison allows for greater flexibility during comparison, catering for discrepancies which may occur, for example, when an applicant uses their middle or spouse name, or there's been an extraction error.
Note:
* When an **applicant hasn’t provided data** the sub-breakdown result is null for the missing field
* When an **applicant has provided names but names have not been extracted from the document**, the sub-breakdown result is `consider`
* When an **applicant has provided date of birth and/or gender, but these fields have not been extracted from the document**, the sub-breakdown result is null
> ⚠️ **Warning:** Any other sub-breakdowns present under `data_comparison` in the document report object exist only for legacy reasons.
#### `data_validation`:
Asserts whether the format and length of the fields are correct for that document type. Uses the following sub-breakdowns:
* `gender`
* `date_of_birth`
* `document_numbers`
* `document_expiration` 1
* `expiry_date` 2
* `mrz`
* `barcode`
1. If this is flagged, the document has expired. Entrust uses UTC as a fixed reference point for the current date and time when the dates are compared.
2. If this is flagged, the expiration date has the incorrect format or the date is in the past.
#### `age_validation`:
Asserts whether the age calculated from the document’s date of birth data
point is greater than or equal to the minimum accepted age set at account
level. The default minimum accepted age is 16 years. Configurable to set a different minimum age value. Entrust uses UTC as a fixed reference point for the current date and time when the applicant's age is calculated.
Uses the following sub-breakdown:
* `minimum_accepted_age`
#### `image_integrity`:
Asserts whether the document was of sufficient quality to verify.
Uses the following sub-breakdowns:
* `image_quality`:
Asserts whether the quality of the image was sufficient for processing.
* `conclusive_document_quality`:
A result of `clear` for this sub-breakdown will assert if the
document was of enough quality to be able to perform a fraud
inspection. A result of `consider` will mean that even if sub
breakdowns of `visual_authenticity` fail, we cannot positively say
the document is fraudulent or not (in cases such as parts of the
document are not visible).
* `supported_document`:
Asserts whether the submitted document is supported. Takes value
of `clear` or `unidentified`.
* `colour_picture`:
Asserts whether the image was a color one. A black and white picture
will map to a `caution` Document report sub-result. Configurable to
map to `rejected`.
#### `visual_authenticity`:
Asserts whether visual (non-textual) elements are correct given the
document type. Uses the following sub-breakdowns:
* `fonts`:
Fonts in the document don’t match the expected ones.
* `picture_face_integrity`:
The pictures of the person identified on the document show signs of
tampering or alteration. In most cases this will focus on the primary
picture yet it may also apply to the secondary and tertiary pictures
when documents contain them.
* `template`:
The document doesn’t match the expected template for the document type
and country it is from.
* `security_features`:
Security features expected on the document are missing or wrong.
* `original_document_present`:
The document was not present when the photo was taken. For example, a
photo of a photo of a document or a photo of a computer screen.
Configurable to map to `caution` instead of `suspected`.
* `digital_tampering`:
Indication of digital tampering in the image (for example, name altered).
* `other`:
This sub-breakdown is returned for backward compatibility reasons. Its
value will be `consider` when at least one of the other breakdowns is
`consider`, and `clear` when all the other breakdowns are `clear`.
* `face_detection`:
No face was detected on the document.
#### `data_consistency`:
Asserts whether data represented in multiple places on the document is
consistent. For example, between MRZ lines and OCR extracted text on
passports. Uses the following sub-breakdowns:
* `multiple_data_sources_present`1
* `document_type`
* `gender`
* `date_of_expiry`
* `nationality`
* `issuing_country`
* `document_numbers`
* `date_of_birth`
* `last_name`
* `first_name`
1. `multiple_data_sources_present` is for cases where we don’t obtain a US barcode because it wasn’t extracted, wasn’t decoded, or wasn’t there at all (e.g. if the back of the document wasn’t available). It acts as a validation for the `data_consistency` breakdown: if 2 sources are present, then data consistency is possible and the other sub-breakdowns are enabled. `multiple_data_sources_present` can be disabled if needed. In this case, it will be returned as null and have no impact on the sub-result.
#### `police_record`:
Asserts whether the document has been identified as lost, stolen or otherwise compromised. Applies to all documents that have been reported as stolen or fraudulent to the UK Metropolitan Police.
This breakdown is only returned if Police Record Checks are enabled for your account. Otherwise, the breakdown and its sub-breakdowns are returned as null and will not affect the final report result. To enable Police Record Checks, please contact [Client Support](mailto:identity-client-support@entrust.com).
#### `compromised_document`:
Asserts whether the image of the document has been found in our internal database.
* `document_database`:
Asserts whether the document is publicly available as compromised. As part of this, will detect and block the fraudulent reuse of genuine identity documents.
* `repeat_attempts`:
Asserts whether the document has been reused in a suspicious way.
#### `issuing_authority`:
Asserts whether data on the document matches the issuing authority data. Uses the following sub-breakdowns:
* `nfc_active_authentication`:
Asserts whether the document NFC chip is original or cloned.
* `nfc_passive_authentication`:
Asserts whether the document NFC chip data was tampered with.
> ℹ️ **Note:** If NFC is completed, the visual authentication, image integrity and data consistency checks will not be performed and the breakdowns will be null.
### Document report: Breakdown reasoning
We will return a reason whenever a report flags for one of the following breakdowns:
* `visual_authenticity` : `original_document_present`
* `image_integrity` : `conclusive_document_quality`
* `image_integrity` : `image_quality`
* `image_integrity` : `supported_document`
This works by returning the contributing reason and corresponding fail result (a `consider` result) in the breakdown properties.
There can be more than one reason per breakdown, as they aren’t mutually exclusive.
All other signals and potential reasons will be omitted.
The following diagram illustrates this logic:
#### Original Document Present reasons:
`photo_of_screen` - When we can see that the applicant's document is on a physical screen or device, e.g. when the device is visible, software applications are seen, a computer cursor is present, or the pixels on the image appearing to have a different texture than expected
`screenshot` - When the applicant has used their mobile phone, tablet, or computer to take a photo within the device, e.g. when software applications are seen, the time and mobile provider are visible, or any digitally added component that wouldn't be seen on a physical document, such as an upload icon
`document_on_printed_paper` - when the applicant has previously captured an image of the document, printed it out, and has now taken a photo of this print out to upload, e.g. when the edges of the paper are visible, when there are fold creases on the paper, or the document's edges blending into the background and appearing flat
`scan` - When the document has clearly been captured using a scanner and there are visible indicators of this, e.g. unusual shadows on the edges of the document, or written text around the document
#### Conclusive Document Quality reasons:
`obscured_data_points` - This refers to when data points are obscured to the point that we cannot confirm if the fonts match the expected ones
`obscured_security_features` - This refers to whenever a critical security feature is obscured. This can also refer to when the holder's wet signature, necessary for the document to be valid, is not present
`abnormal_document_features` - This refers to when something other than obscuration of data points and security features makes the document insufficient to be assessed (i.e. poor image resolution, poor lighting, distortions due to capturing devices, misalignment due to cracks, visual alterations due to cases/laminates, some stickers etc.)
`watermarks_digital_text_overlay` - Any digital text or electronic watermarks on the document
`corner_removed` - If the corner has been physically cut off. This can be found on some documents that are no longer valid
`punctured_document` - A punched hole is present. This can be found on DLs that are no longer valid, for example
`missing_back` - When the back of a document is needed for processing (e.g. for key data points to extract), but is not available (e.g. if the same front was uploaded twice)
`digital_document` - When a document has been published digitally, there aren’t enough security features to review so we cannot perform a full fraud assessment
#### Image Quality reasons:
`dark_photo` - When an image of the document is too dark to be able to see data points
`glare_on_photo` - When there is light reflecting on the document causing glare to obstruct data points
`blurred_photo` - When data points are blurred and no reference can be made elsewhere in the document or if the data points are too blurry and 'they could be something else' (e.g. "I" could be "1", "B" could be "8")
`covered_photo` - When data points have been covered either by the applicant or by another object such as a sticker
`other_photo_issue` - Any other reason not listed, such as when holograms are obscuring data points
`damaged_document` - When a document is damaged and we are unable to make out data points
`incorrect_side` - When the incorrect side of a document has been uploaded, and we have not received the front
`cut_off_document` - When data points are not included in the image due to the document being cut off (i.e. out of the frame of the image)
`no_document_in_image` - If no document has been uploaded or there is a blank image
`two_documents_uploaded` - When 2 different documents are submitted in the same check
#### Supported Document reasons:
`onfido_supported_document` - When the Entrust product doesn't support the requested document
`custom_supported_document` - When the client's configured custom rules don't support the requested document
`sanctioned_issuing_country` - When a document is issued by a country subject to comprehensive US sanctions (you can find the list of countries [here](https://support.identity.entrust.com/s/article/Documents-Issued-by-US-Sanctioned-Countries-FAQs)). The breakdown will return `consider` and a sub-result of `rejected` for the document report, as well as a property indicating that the document is not a supported document due to sanctions
### [Document video report](#document-video-report)
For a general introduction to the Document Video Report, you can read our [product documentation](/guide/document-report#document-video-report).
To request a Document Video Report as part of a [check](/api/latest/#create-check) in the API, use the `report_names` field (which takes an array of strings):
`"report_names": ["document_video"]`
**Note:** When creating checks with the API, `document_ids` is a **required parameter** for Document Video Report.
#### Document video report: Breakdown reasoning
The `image_integrity` breakdown of the Document Video Report response includes a `video_document_presence` sub-breakdown, which has the results `clear` and `unidentified`.
`video_document_presence` also has a property, called `invalid_signature`. If the media signature of a recorded video is not valid, the property will return `consider`, and the sub-breakdown will return `unidentified`. In this case, the Document Video Report will be `rejected`.
With a `clear` report result, the following snippet is an example showing what is added to the Document report response object:
```json
"image_integrity": {
"breakdown": {
"video_document_presence": {
"properties": {},
"result": "clear"
}
},
"result": "clear"
},
```
### BETA Document report options
#### [Document with Address Information](#document-with-address-information-beta)
> **Note:** This report is in beta. Contact your account manager
> for more information about the features in this report.
To request a Document with Address Information report as part of a check in
the API, use the `report_names` field (which takes an array of strings):
`"report_names": ["document_with_address_information"]`
By default, the most recently uploaded document will be used.
If you use this report, Entrust will use a third-party subprocessor for address cleansing after the address has been extracted.
To specify which [uploaded document](#upload-document) to run the Document
with Address Information report against in the API, use the `document_ids` field. This takes an array
of up to 2 strings (2 document IDs):
`"document_ids": [""]`
For a `clear` result, the following snippet is an example showing what is added to the Document report response object:
```json
...
"address_lines": {
"city": "EDINBURGH",
"country": "United Kingdom (UK)",
"postal_code": "EH1 9GP",
"state": "",
"street_address": "122 BURNS CRESCENT",
"country_code": "GBR"
},
"address": "",
...
```
Contact your account manager for more information about the features in the
Document with Address Information report.
#### [Document Video Report with Address Information](#document-video-with-address-information-beta)
> **Note:** This report is in beta. Contact your account manager
> for more information about the features in this report.
To request a Document Video with Address Information report as part of a check in
the API, use the `report_names` field (which takes an array of strings):
`"report_names": ["document_video_with_address_information"]`
By default, the most recently uploaded document will be used.
If you use this report, Entrust will use a third-party subprocessor for address cleansing after the address has been extracted.
To specify which [uploaded document](#upload-document) to run the Document Video
with Address Information report against in the API, use the `document_ids` field. This takes an array
of up to 2 strings (2 document IDs):
`"document_ids": [""]`
For a `clear` result, the following snippet is an example showing what is added to the Document report response object:
```json
...
"address_lines": {
"city": "EDINBURGH",
"country": "United Kingdom (UK)",
"postal_code": "EH1 9GP",
"state": "",
"street_address": "122 BURNS CRESCENT",
"country_code": "GBR"
},
"address": "",
...
```
Contact your account manager for more information about the features in the
Document Video with Address Information report.
#### Document with Driving License Information
> ⚠️ **Warning:** This report will soon be deprecated. We recommend that you use the Document with Driver Verification report instead.
To request a Document with Driving License Information report as part of a
check in the API, use the `report_names` field (which takes an array of
strings):
`"report_names": ["document_with_driving_licence_information"]`
By default, the most recently uploaded document will be used.
To specify which [uploaded document](#upload-document) to run the Document
with Driving License Information report against in the API, use the `document_ids`
field. This takes an array of up to 2 strings (2 document IDs):
`"document_ids": [""]`
For a `clear` result, the following snippet is an example showing what is added to the Document report response object:
```json
...
"driving_licence_information": [
{
"category": "A",
"codes": "79.03,79.04",
"expiry_date": "",
"obtainment_date": ""
},
{
"category": "A1",
"codes": "79.03,79.04",
"expiry_date": "",
"obtainment_date": ""
},
{
"category": "AM",
"codes": "",
"expiry_date": "",
"obtainment_date": ""
},
{
"category": "B",
"codes": "",
"expiry_date": "",
"obtainment_date": ""
}
],
...
```
> ⚠️ **Warning:** The report must be completed using a manual only review process to guarantee the driving license data is extracted.
Contact your account manager for more information about the features in the
Document with Driving License Information report.
#### Document with Driver Verification
> **Note:** This report is in beta. Contact your account manager
> for more information about the features in this report.
To request a Document with Driver Verification report as part of a
check in the API, use the `report_names` field (which takes an array of
strings):
`"report_names": ["document_with_driver_verification"]`
By default, the most recently uploaded document will be used.
To specify which [uploaded document](#upload-document) to run the Document
with Driver Verification report against in the API, use the `document_ids`
field. This takes an array of up to 2 strings (2 document IDs):
`"document_ids": [""]`
For a `clear` result, the following table is an example showing what properties are added to the Document report response object:
| Property | Description | Value type |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `"drivers_licence"` | True when determined to be a non-restricted driving license (applicant older than 18 years, and no restricted categories detected in the license title) | Boolean |
| `"restricted_licence"` | True for **limited/restricted** driving licences, including learner's permits | Boolean |
| `"raw_licence_category"` | Underlying, non-normalised, license category (e.g. "Junior operators license") | String or Empty |
| `"raw_vehicle_classes"` | Comma-separated vehicle classes that the user is qualified for | String or Empty |
| `"vehicle_class_details"` | Detailed classes/categories information | Array of objects or Empty |
| `"vehicle_class_details[].category` | Vehicle class/category | String |
| `"vehicle_class_details[].codes` | Special conditions driver must meet | String or Empty |
| `"vehicle_class_details[].obtainment_date` | Category obtainment date | String |
| `"vehicle_class_details[].expiry_date` | Category expiry date | String or Empty |
| `"manual_transmission_restriction"` | True if the user is not qualified to drive a manual transmission | Boolean or Empty |
| `"passenger_vehicle"` | Normalised data for passenger cars | Object or Empty |
| `"passenger.vehicle.is_qualified"` | Whether they are qualified for a passenger car, such as a “B” class in the UK | String or Empty |
| `"passenger_vehicle.obtainment_date"` | Date the class qualification was obtained | String or Empty |
| `"passenger_vehicle.expiry_date"` | Date the class qualification expires, which may be different to doc expiry | String or Empty |
Example:
```json
...
"drivers_licence": true,
"restricted_licence": false,
"raw_licence_category": "DRIVER LICENSE",
"raw_vehicle_classes": "AM,B",
"vehicle_class_details": [{
"category": "AM",
"obtainment_date": "2020-05-12",
"expiry_date": "2030-05-12"
},
{
"category": "B",
"obtainment_date": "2020-05-12",
"expiry_date": "2030-05-12"
}
]
...
```
Contact your account manager for more information about the features in the
Document with Driver Verification report.
## Facial Similarity reports
This API documentation offers detailed information about the structure of a Facial Similarity report, including an example of the report's result and its breakdowns.
For a more general introduction to the Facial Similarity report, you can read our
[product documentation](/guide/facial-similarity-reports/).
After you've familiarised yourself with the information here, you can read our guide on [suggested client actions](/guide/facial-similarity-reports/#suggested-client-actions) for different result scenarios.
> ⚠️ **Warning:** Creating a check with a Facial Similarity report will
> cause you to process facial biometric personal data. Always make sure you
> inform your users about this and obtain any necessary permissions. For more
> information on how Entrust uses personal data, view our [Privacy
> Policy](https://onfido.com/privacy/).
There are 4 different types of Facial Similarity report:
| Report name | Request body in API |
| ---------------- | -------------------------------------------------------- |
| Photo | `"report_names": ["facial_similarity_photo"]` |
| Photo Fully Auto | `"report_names": ["facial_similarity_photo_fully_auto"]` |
| Video | `"report_names": ["facial_similarity_video"]` |
| Motion | `"report_names": ["facial_similarity_motion"]` |
All Facial Similarity reports will compare the most recent [live photo](#live-photos), [live video](#live-videos) or [motion capture](#motion-captures) provided by the applicant to the face on the specified document or NFC media provided during check creation in the `document_ids` field.
`"document_ids": [""]`
By default, the most recently uploaded document specified will be used. If unspecified, the most recently uploaded document will be used.
Where the document has two sides, we will search both sides of the document for a face. Where the document has been scanned using NFC, we will use the face extracted from the document's NFC chip.
When document IDs are associated with a Facial Similarity report, the document IDs of the documents used will be returned under the `documents` attribute of the [report object](#report-object).
> **Note:** When `side` is not specified, it will take a default value of `front`. We
> recommend that all documents contain the `side` attribute, as this minimises
> the cases where the back of the document is used for comparison and thus
> failed as no face is detected.
### [Required applicant data](#facial-similarity-required-applicant-data)
For all Facial Similarity report types, `first_name` and `last_name` must
be provided but can be sample values if you don't know an applicant's name.
### [Facial Similarity Photo](#facial-similarity-photo)
> ⚠️ **Warning:** If `applicant_provides_data` is `true`,
> the Facial Similarity Photo report needs to be paired with a [Document
> report](#document-report).
#### Facial Similarity Photo: Object
The following table describes the unique fields returned in this version of the API for a completed Facial Similarity Photo report:
| Attribute | Format | Possible values |
| ------------------------------------------------ | ---------------- | ------------------------------- |
| `result` | String | `"clear"`, `"consider"` |
| `image_integrity` | String or `null` | `"clear"`, `"consider"`, `null` |
| (sub-breakdown) `face_detected` | String or `null` | `"clear"`, `"consider"`, `null` |
| (sub-breakdown) `source_integrity`1 | String or `null` | `"clear"`, `"consider"`, `null` |
| `face_comparison` | String or `null` | `"clear"`, `"consider"`, `null` |
| (sub-breakdown) `face_match`2 | String or `null` | `"clear"`, `"consider"`, `null` |
| `visual_authenticity` | String or `null` | `"clear"`, `"consider"`, `null` |
| (sub-breakdown) `spoofing_detection`3 | String or `null` | `"clear"`, `"consider"`, `null` |
1: `source_integrity` may contain reasons under the `properties` bag (see [Facial Similarity Photo: Source Integrity](#facial-similarity-photo-source-integrity))
2: `face_match` contains a `score` value and `document_id` unique identifier under the `properties` bag (see [Facial Similarity Photo: Face Match properties](#facial-similarity-photo-face-match-properties))
3: `spoofing_detection` contains a `score` value under the `properties` bag (see [Facial Similarity Photo: Spoofing Detection Score](#facial-similarity-photo-spoofing-detection-score))
> ℹ️ **Note:** A breakdown or sub-breakdown will have the result `null` when it has not been completed. This occurs when it is not available, or has failed to process the media due to a timeout or an internal error. In this case, the report will go to manual review.
#### Facial Similarity Photo: Breakdowns
| Breakdown | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| image\_integrity | **object**
Asserts whether the quality and integrity of the uploaded files were sufficient to perform a face comparison. |
| (sub-breakdown) face\_detected | **object**
Asserts a single face of good enough quality has been found in both the document image and the live photo. |
| (sub-breakdown) source\_integrity | **object**
Asserts whether the live photo is trustworthy - i.e. not digitally tampered, from a fake webcam, or from other dubious sources. |
| face\_comparison | **object**
Asserts whether the face in the document matches the face in the live photo. |
| (sub-breakdown) face\_match | **object**
Contains a `score` value and `document_id` unique identifier for the matched document under the `properties` bag (see [Facial Similarity Photo: Match properties](#facial-similarity-photo-face-match-properties)). |
| visual\_authenticity | **object**
Asserts whether the person in the live photo is real (not a spoof). |
| (sub-breakdown) spoofing\_detection | **object**
Contains a `score` value under the `properties` bag (see [Facial Similarity Photo: Spoofing Detection Score](#facial-similarity-photo-spoofing-detection-score)). |
#### Facial Similarity Photo: Source Integrity
We will return a reason whenever a report flags for `source_integrity`. This
works by returning the contributing reason and a `consider` result in the
`source_integrity` breakdown properties. There can be more than one reason,
because they aren’t mutually exclusive. All other signals and potential
reasons will be omitted.
For Facial Similarity Photo, the `source_integrity` sub-breakdown is composed
of the following properties:
* `digital_tampering` - when evidence is found that the image was manipulated by Photoshop, or other software
* `fake_webcam` - when evidence is found that a fake webcam was used
* `time_of_capture` - when evidence is found that the live photo was taken more than 24 hours before live photo upload
* `emulator` - when evidence is found that an Android emulator was used
* `payload_integrity` - when evidence is found that the payload was tampered with
* `sanctioned_document_country` - when a document is issued by a country subject to comprehensive US sanctions (you can find the list of countries [here](https://support.identity.entrust.com/s/article/Documents-Issued-by-US-Sanctioned-Countries-FAQs)). The report (either in conjunction with or separate from a document report) will return a `consider` result, accompanied by a `reasons` property clarifying that it is not supported due to sanctions
* `reasons` - additional comma separated details such as the exact digital tampering software used, or the name of the fake webcam
#### Facial Similarity Photo: Face Match properties
The `face_match` breakdown contains a `properties` object with a `score`
value and `document_id` unique identifier.
* The `score` value is a floating point number between 0 and 1 that expresses
how similar the two faces are, where 1 is a perfect match.
If the face matching algorithm fails to detect a face, the `score` property
will not be present and the face matching task will be done manually. The
score only measures how similar the faces are, and does not make an
assessment of the nature of the photo. If spoofing (such as photos
of printed photos or photos of digital screens) is detected the applicant will
be rejected independently of the face match score.
* `document_id` returns the UUID for the document containing the extracted face that was used for face matching.
If no face is detected, no document is recorded and the property is returned as `null`.
#### Facial Similarity Photo: Spoofing Detection Score
The `spoofing_detection` breakdown contains a `properties` object with a `score`
value. This score is a floating point number between 0 and 1. The closer the
score is to 0, the more likely it is to be a spoof (i.e. photos of printed
photos, or photos of digital screens). Conversely, the closer it is to 1, the
less likely it is to be a spoof.
### Photo Fully Auto
> ⚠️ **Warning:** If `applicant_provides_data` is `true`,
> the Photo Fully Auto report needs to be paired with a [Document
> report](#document-report).
#### Photo Fully Auto: Object
The following table describes the unique fields returned in this version of the API for a completed Photo Fully Auto report:
| Attribute | Format | Possible values |
| ------------------------------------------------ | ---------------- | ------------------------------- |
| `result` | String | `"clear"`, `"consider"` |
| `image_integrity` | String or `null` | `"clear"`, `"consider"`, `null` |
| (sub-breakdown) `face_detected` | String or `null` | `"clear"`, `"consider"`, `null` |
| (sub-breakdown) `source_integrity`1 | String or `null` | `"clear"`, `"consider"`, `null` |
| `face_comparison` | String or `null` | `"clear"`, `"consider"`, `null` |
| (sub-breakdown) `face_match`2 | String or `null` | `"clear"`, `"consider"`, `null` |
| `visual_authenticity` | String or `null` | `"clear"`, `"consider"`, `null` |
| (sub-breakdown) `spoofing_detection`3 | String or `null` | `"clear"`, `"consider"`, `null` |
1: `source_integrity` may contain reasons under the `properties` bag (see [Source Integrity](#photo-fully-auto-source-integrity) for Photo Fully Auto)
2: `face_match` contains a `score` value and `document_id` unique identifier under the `properties` bag (see [Face Match properties](#photo-fully-auto-face-match-properties) for Photo Fully Auto)
3: `spoofing_detection` contains a `score` value under the `properties` bag (see [Spoofing Detection Score](#photo-fully-auto-spoofing-detection-score) for Photo Fully Auto)
#### Photo Fully Auto: Breakdowns
| Breakdown | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| image\_integrity | **object**
Asserts whether the quality and integrity of the uploaded files were sufficient to perform a face comparison. |
| (sub-breakdown) face\_detected | **object**
Asserts a single face of good enough quality has been found in both the document image and the live photo. |
| (sub-breakdown) source\_integrity | **object**
Asserts whether the live photo is trustworthy - i.e. not digitally tampered, from a fake webcam, or from other dubious sources. |
| face\_comparison | **object**
Asserts whether the face in the document matches the face in the live photo. |
| (sub-breakdown) face\_match | **object**
Contains a `score` value and `document_id` unique identifier for the matched document under the `properties` bag (see [Face Match properties](#photo-fully-auto-face-match-properties) for Fully Auto). |
| visual\_authenticity | **object**
Asserts whether the person in the live photo is real (not a spoof). |
| (sub-breakdown) spoofing\_detection | **object**
Contains a `score` value under the `properties` bag (see [Spoofing Detection Score](#photo-fully-auto-spoofing-detection-score) for Fully Auto). |
#### Photo Fully Auto: Source Integrity
We will return a reason whenever a report flags for `source_integrity`. This
works by returning the contributing reason and a `consider` result in the
`source_integrity` breakdown properties. There can be more than one reason,
because they aren’t mutually exclusive. All other signals and potential
reasons will be omitted.
For Photo Fully Auto, the `source_integrity` sub-breakdown is composed
of the following properties:
* `digital_tampering` - when evidence is found that the image was manipulated by Photoshop, or other software
* `fake_webcam` - when evidence is found that a fake webcam was used
* `time_of_capture` - when evidence is found that the live photo was taken more than 24 hours before live photo upload
* `emulator` - when evidence is found that an Android emulator was used
* `payload_integrity` - when evidence is found that the payload was tampered with
* `sanctioned_document_country` - when a document is issued by a country subject to comprehensive US sanctions (you can find the list of countries [here](https://support.identity.entrust.com/s/article/Documents-Issued-by-US-Sanctioned-Countries-FAQs)). The report (either in conjunction with or separate from a document report) will return a `consider` result, accompanied by a `reasons` property clarifying that it is not supported due to sanctions
* `reasons` - additional comma separated details such as the exact digital tampering software used, or the name of the fake webcam
#### Photo Fully Auto: Face Match properties
The `face_match` breakdown contains a `properties` object with a `score`
value and `document_id` unique identifier.
* The `score` value is a floating point number between 0 and 1 that expresses
how similar the two faces are, where 1 is a perfect match.
If the face matching algorithm fails to detect a face, the `score` property
will not be present. The score only measures how similar the faces are, and does not make an assessment of the nature of the photo. If spoofing (such as photos of printed photos or photos of digital screens) is detected the applicant will be rejected independently of the face match score.
* `document_id` returns the UUID for the document containing the extracted face that was used for face matching.
If no face is detected, no document is recorded and the property is returned as `null`.
#### Photo Fully Auto: Spoofing Detection Score
The `spoofing_detection` breakdown contains a `properties` object with a `score`
value. This score is a floating point number between 0 and 1. The closer the
score is to 0, the more likely it is to be a spoof (i.e. photos of printed
photos, or photos of digital screens). Conversely, the closer it is to 1, the
less likely it is to be a spoof.
If the anti-spoofing algorithm fails to detect a face, the `score` property will
not be present.
### [Facial Similarity Video](#facial-similarity-video)
In the Facial Similarity Video report, [live videos](#live-videos) are
collected and uploaded by one of the Entrust Identity Verification SDKs
([iOS](/sdk/ios),
[Android](/sdk/android) or
[Web](/sdk/web)).
> ⚠️ **Warning:** Checks where `applicant_provides_data` is `true` are not
> compatible with Facial Similarity Video reports.
In addition to confirming the two faces match, Facial Similarity Video
assesses active liveness by asking users to repeat randomly generated numbers
and perform a random head movement. This prevents impersonation - for example
masks, and deep fakes displayed on digital screens. This process is reflected
in `visual_authenticity`, which is composed of the sub-breakdowns
`spoofing_detection` and `liveness_detected`. See [Facial
Similarity Video Object](#facial-similarity-video-object) and [Facial
Similarity Video Breakdowns](#facial-similarity-video-breakdowns).
In order for a Facial Similarity Video report to complete automatically, the
user needs to turn their head in the correct direction and correctly say the 3
randomly generated digits in one of our supported languages (see table below).
| Language name | Language code |
| ------------- | ------------- |
| English | "en" |
| Spanish | "es" |
| Italian | "it" |
| Indonesian | "id" |
| German | "de" |
| French | "fr" |
| Portuguese | "pt" |
| Polish | "pl" |
| Japanese | "ja" |
| Dutch | "nl" |
| Romanian | "ro" |
| Basque | "eu" |
| Catalan | "ca" |
| Galician | "gl" |
| Chinese | "cn" |
| Turkish | "tr" |
| Malay | "ms" |
> ⚠️ **Warning:** If the user does not say the correct digits, or speak in
> another language, the live video will be reviewed by an analyst for
> evidence of spoofing.
#### SDK localization
We recommend that you localize the strings if you're using one of the Entrust Identity Verification
SDKs, so the user is more likely to understand the liveness headturn and
speaking instructions.
The Entrust voice processor will attempt to detect the language the user is
speaking. This will be more successful if you pass the code for the expected
language to the `locale` mechanism, in any of the Entrust Identity Verification
SDKs:
* [iOS SDK](/sdk/ios/#language-localization) - pass the `onfido_locale` parameter
* [Android SDK](/sdk/android/#language-localization) - pass the `onfido_locale` parameter
* [Web SDK](/sdk/web/#language-customization) - pass the `locale` parameter
Some string localizations are available out of the box, but this differs
depending on the SDK.
You can also provide your own custom translations to your users.
#### Facial Similarity Video: Object
The following table describes the unique fields returned in this version of the API for a completed Facial Similarity Video report:
| Attribute | Format | Possible values |
| ------------------------------------------------ | ---------------- | ------------------------------- |
| `result` | String | `"clear"`, `"consider"` |
| `image_integrity` | String or `null` | `"clear"`, `"consider"`, `null` |
| (sub-breakdown) `face_detected` | String or `null` | `"clear"`, `"consider"`, `null` |
| (sub-breakdown) `source_integrity`1 | String or `null` | `"clear"`, `"consider"`, `null` |
| `face_comparison` | String or `null` | `"clear"`, `"consider"`, `null` |
| (sub-breakdown) `face_match`2 | String or `null` | `"clear"`, `"consider"`, `null` |
| `visual_authenticity` | String or `null` | `"clear"`, `"consider"`, `null` |
| (sub-breakdown) `spoofing_detection`3 | String or `null` | `"clear"`, `"consider"`, `null` |
| (sub-breakdown) `liveness_detected` | String or `null` | `"clear"`, `"consider"`, `null` |
1: `source_integrity` may contain reasons under the `properties` bag (see [Facial Similarity Video: Source Integrity](#facial-similarity-video-source-integrity))
2: `face_match` contains a `score` value and `document_id` unique identifier under the `properties` bag (see [Facial Similarity Video: Face Match properties](#facial-similarity-video-face-match-properties))
3: `spoofing_detection` contains a `score` value under the `properties` bag (see [Facial Similarity Video: Spoofing Detection Score](#facial-similarity-video-spoofing-detection-score))
#### Facial Similarity Video: Breakdowns
| Breakdown | Description |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| face\_comparison | **object**
Asserts whether the face in the document matches the face in the live video. |
| (sub-breakdown) face\_match | **object**
Contains a `score` value and `document_id` unique identifier for the matched document under the properties bag (see [Facial Similarity Video: Face Match properties](#facial-similarity-video-face-match-properties)). |
| image\_integrity | **object**
Asserts whether the quality of the uploaded files and the content contained within them were sufficient to perform a face comparison. |
| (sub-breakdown) face\_detected | **object**
Asserts a single face of good enough quality has been found in both the document image and in the live video. |
| (sub-breakdown) source\_integrity | **object**
Asserts whether the live video is trustworthy - e.g. not from a fake webcam. |
| visual\_authenticity | **object**
Asserts whether the person in the live video is real (not a spoof) and live. |
| (sub-breakdown) spoofing\_detection | **object**
Asserts whether the live video is not a spoof (such as videos of digital screens). |
| (sub-breakdown) liveness\_detected | **object**
Asserts whether the numbers and head movements were correctly executed. |
#### Facial Similarity Video: Source Integrity
We will return a reason whenever a report flags for `source_integrity`. This
works by returning the contributing reason and a `consider` result in the
`source_integrity` breakdown properties. There can be more than one reason,
because they aren’t mutually exclusive. All other signals and potential
reasons will be omitted.
For Facial Similarity Video, the `source_integrity` sub-breakdown is composed of the following properties:
* `fake_webcam` - when evidence is found that a fake webcam was used
* `emulator` - when evidence is found that an Android emulator was used
* `payload_integrity` - when evidence is found that the payload was tampered with
* `sanctioned_document_country` - when a document is issued by a country subject to comprehensive US sanctions (you can find the list of countries [here](https://support.identity.entrust.com/s/article/Documents-Issued-by-US-Sanctioned-Countries-FAQs)). The report (either in conjunction with or separate from a document report) will return a `consider` result, accompanied by a `reasons` property clarifying that it is not supported due to sanctions
* `challenge_reuse` - when evidence is found that the video was uploaded in an attempt to circumvent the randomness of the speaking and head turn challenges
* `reasons` - additional comma separated details, such as the name of the fake webcam
#### Facial Similarity Video: Face Match properties
The `face_match` breakdown contains a `properties` object with a `score`
value and `document_id` unique identifier.
* The `score` value is a floating point number between 0 and 1 that expresses
how similar the two faces are, where 1 is a perfect match.
If the face matching algorithm fails to detect a face, the `score` property
will not be present and the face matching task will be done manually. The
score only measures how similar the faces are, and does not make an
assessment of the nature of the live video. If spoofing (such as videos of
digital screens, masks or print-outs) is detected the applicant will
be rejected independently of the face match score.
* `document_id` returns the UUID for the document containing the extracted face that was used for face matching.
If no face is detected, no document is recorded and the property is returned as `null`.
#### Facial Similarity Video: Spoofing Detection Score
The `spoofing_detection` breakdown contains a `properties` object with a
`score` value. This score is a floating point number between 0 and 1. The
closer the score is to 0, the more likely it is to be a spoof (i.e. videos of
digital screens, masks or print-outs). Conversely, the closer it is to 1, the
less likely it is to be a spoof.
The `score` value is based on passive facial information only, regardless of
whether or not the user said the expected digits or turned their head in the
correct direction. For example, a user who performs no action but is a real
person should receive a score close to 1.
### [Facial Similarity Motion](#facial-similarity-motion)
In the Facial Similarity Motion report, [motion captures](#motion-captures) are
collected and uploaded by one of the Entrust Identity Verification SDKs
([iOS](/sdk/ios/),
[Android](/sdk/android/) or
[Web](/sdk/web/)).
> ⚠️ **Warning:** Checks where `applicant_provides_data` is `true` are not
> compatible with Facial Similarity Motion reports.
In addition to confirming the two faces match, Facial Similarity Motion
assesses liveness by asking users to complete a head turn in both directions.
This process is reflected in `visual_authenticity`, which is composed of
the sub-breakdowns `spoofing_detection` and `liveness_detected`. See [Facial
Similarity Motion Object](#facial-similarity-motion-object) and [Facial
Similarity Motion Breakdowns](#facial-similarity-motion-breakdowns).
Facial Similarity Motion reports always complete automatically.
#### Facial Similarity Motion: Object
The following table describes the unique fields returned in this version of the API for a completed Facial Similarity Motion report:
| Attribute | Format | Possible values |
| ------------------------------------------------ | ---------------- | ------------------------------- |
| `result` | String | `"clear"`, `"consider"` |
| `image_integrity` | String or `null` | `"clear"`, `"consider"`, `null` |
| (sub-breakdown) `face_detected` | String or `null` | `"clear"`, `"consider"`, `null` |
| (sub-breakdown) `source_integrity`1 | String or `null` | `"clear"`, `"consider"`, `null` |
| `face_comparison` | String or `null` | `"clear"`, `"consider"`, `null` |
| (sub-breakdown) `face_match`2 | String or `null` | `"clear"`, `"consider"`, `null` |
| `visual_authenticity` | String or `null` | `"clear"`, `"consider"`, `null` |
| (sub-breakdown) `spoofing_detection`3 | String or `null` | `"clear"`, `"consider"`, `null` |
| (sub-breakdown) `liveness_detected` | String or `null` | `"clear"`, `"consider"`, `null` |
1: `source_integrity` may contain reasons under the `properties` bag (see [Facial Similarity Motion: Source Integrity](#facial-similarity-motion-source-integrity))
2: `face_match` contains a `score` value and `document_id` unique identifier under the `properties` bag (see [Facial Similarity Motion: Face Match Properties](#facial-similarity-motion-face-match-properties))
3: `spoofing_detection` contains a `score` value under the `properties` bag (see [Facial Similarity Motion: Spoofing Detection Score](#facial-similarity-motion-spoofing-detection-score))
#### Facial Similarity Motion: Breakdowns
| Breakdown | Description |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| face\_comparison | **object**
Asserts whether the face in the document matches the face in the motion capture. |
| (sub-breakdown) face\_match | **object**
Contains a `score` value and `document_id` unique identifier for the matched document under the properties bag (see [Facial Similarity Motion: Face Match properties](#facial-similarity-motion-face-match-properties)). |
| image\_integrity | **object**
Asserts whether the quality of the uploaded files and the content contained within them were sufficient to perform a face comparison. |
| (sub-breakdown) face\_detected | **object**
Asserts a face of good enough quality has been found in both the document image and in the motion capture. |
| (sub-breakdown) source\_integrity | **object**
Asserts whether the motion capture is trustworthy - e.g. not from a fake webcam. |
| visual\_authenticity | **object**
Asserts whether the person in the motion capture is real (not a spoof) and live. |
| (sub-breakdown) spoofing\_detection | **object**
Asserts whether the motion capture is not a spoof (such as videos of digital screens). |
| (sub-breakdown) liveness\_detected | **object**
Asserts whether the head movements were correctly executed. |
#### Facial Similarity Motion: Source Integrity
We will return a reason whenever a report flags for `source_integrity`. This
works by returning the contributing reason and a `consider` result in the
`source_integrity` breakdown properties. There can be more than one reason,
because they aren’t mutually exclusive. All other signals and potential
reasons will be omitted.
For Facial Similarity Motion, the `source_integrity` sub-breakdown is composed of the following properties:
* `fake_webcam` - when evidence is found that a fake webcam was used
* `emulator` - when evidence is found that an Android emulator was used
* `payload_integrity` - when evidence is found that the payload was tampered with
* `sanctioned_document_country` - when a document is issued by a country subject to comprehensive US sanctions (you can find the list of countries [here](https://support.identity.entrust.com/s/article/Documents-Issued-by-US-Sanctioned-Countries-FAQs)). The report (either in conjunction with or separate from a document report) will return a `consider` result, accompanied by a `reasons` property clarifying that it is not supported due to sanctions
* `reasons` - additional comma separated details, such as the name of the fake webcam
#### Facial Similarity Motion: Face Match Properties
The `face_match` breakdown contains a `properties` object with a `score`
value and `document_id` unique identifier.
* The `score` value is a floating point number between 0 and 1 that expresses
how similar the two faces are, where 1 is a perfect match.
The score only measures how similar the faces are, and does not make an
assessment of the nature of the motion capture. If spoofing (such as videos of
digital screens, masks or print-outs) is detected the applicant will
be rejected independently of the face match score.
* `document_id` returns the UUID for the document containing the extracted face that was used for face matching.
If no face is detected, no document is recorded and the property is returned as `null`.
#### Facial Similarity Motion: Spoofing Detection Score
The `spoofing_detection` breakdown contains a `properties` object with a
`score` value. This score is a floating point number between 0 and 1. The
closer the score is to 0, the more likely it is to be a spoof (i.e. videos of
digital screens, masks or print-outs). Conversely, the closer it is to 1, the
less likely it is to be a spoof.
The `score` value is based on passive facial information only, regardless of
whether or not the user performed the head turn. For example, a user who performs
no action but is a real person should receive a score close to 1.
### [Suggested client actions](#facial-similarity-suggested-client-actions)
We host a guide on our Developer Hub for [suggested client actions in specific
scenarios](/guide/facial-similarity-reports/#suggested-client-actions)
for clients using our Facial Similarity reports.
## Known Faces report
This API documentation offers detailed information about the structure of a Known Faces report, including an example of the report's result and its breakdowns.
For a more general introduction to the Known Faces report, you can read our
[product documentation](/guide/known-faces-report/).
> ⚠️ **Warning:** The Known Faces report requires that we keep a
> database of facial biometric identifiers (personal data) so that individuals
> can be identified in future checks. Always make sure you inform your users
> about this and obtain any necessary permissions. For more information on how
> Entrust uses personal data, view our [Privacy
> Policy](https://onfido.com/privacy/).
Each applicant you run a Known Faces report against must have an uploaded
[live photo](#live-photos), [live video](#live-videos) or [motion capture](#motion-captures).
If no live photo, live video or motion capture is found, the Known Faces report
will be automatically withdrawn and return an error in the report properties:
```json
"properties":{
"reason": "Report withdrawn due to missing media (photo, video or motion capture) required for processing."
}
```
> ⚠️ **Warning:** It is highly recommended the Known Faces report always be run in conjunction with a
> [Facial Similarity](#facial-similarity-report) report. Only faces processed through Facial Similarity
> are kept on the database. Thus, although it can be requested on its own, **a Known Faces report can
> only match against applicants who have previously gone through a Facial Similarity report.**
No matches will be returned against any [permanently
deleted](#delete-applicant) applicants.
To request a Known Faces report as part of [a check](#checks) in the API, use
the `report_names` field (which takes an array of strings):
`"report_names": ["known_faces"]`
### [Required applicant data](#known-faces-required-applicant-data)
For Known Face reports, `first_name` and `last_name` must be provided but can be sample values if you don't know an applicant's name.
### Known Faces: Object
The following table describes the unique fields returned in this version of the API for a completed Known Faces report:
| Attribute | Format | Possible values |
| ----------------------- | ---------------------------- | -------------------------------- |
| `result` | String | `"clear"`, `"consider"` |
| `previously_seen_faces` | String or `null`1 | `"clear"`, `"consider"` , `null` |
| `image_integrity` | String | `"clear"`, `"consider"` |
1. `null` is returned when `image_integrity` is `"consider"`. This is because, when no face is detected in the input media, there is nothing to match against previously seen faces.
### Known Faces: Breakdowns
| Breakdown | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| previously\_seen\_faces | **object**
Asserts whether the applicant's most recent facial media (live photo or live video) matches any other live photos or live videos already in your Entrust account database. Only matches where the `suspected` field is `true` will be considered. |
| image\_integrity | **object**
Asserts whether the uploaded live photo or live video and the content contained within it were of sufficient quality to perform a face comparison. |
### Known Faces: Properties
The Known Faces response will return any matching applicant IDs as entries
inside a `matches` array under a `properties` bag. Each applicant ID has a
corresponding `score` and the media type (for example `live_photos`,
`live_videos`), as well as the corresponding UUID for that media type. For example, the live photo or live video ID.
Only matches where the `suspected` field is `true` should be considered as possible fraud. This
is determined by fuzzy matching the report's applicant name and matched applicants' names.
This can have a value of `false` only if the **fuzzy name matching** feature for Known Faces reports is enabled in your account.
The `score` attribute is a floating point number between 0 and 1 that expresses how
similar the two faces are, where 1 is a perfect match.
```json
"matches": [
{
"applicant_id": "NTH_MATCHED_APPLICANT_ID",
"score": 0.9915,
"media_id": "LIVE_PHOTO_ID",
"media_type": "live_photos",
"suspected": true
}
]
```
If matches are found and any of them is suspected, the result will be `consider`.
Conversely, if none of the matches are suspected, the result will be `clear`.
## Identity Enhanced report
This API documentation offers detailed information about the structure of a Identity Enhanced report, including an example of the report's result and its breakdowns.
For a more general introduction to the Identity Enhanced report, you can read our
[product documentation](/guide/identity-enhanced-report/).
> ⚠️ **Warning:** For checks containing Identity Enhanced reports, applicants with 1-character last name are allowed for all countries except for `GBR`.
> Applicants with country `GBR` must have last names of at least two non-whitespace characters.
### [Required applicant data](#identity-required-applicant-data)
For Identity Enhanced reports, the following applicant data must be provided:
* `first_name`
* `last_name`
* `dob`
* `address.building_number`
* `address.street`
* `address.town`
* `address.state` (state is mandatory in the US only. In some other countries, province or region may be required to access certain data sources)
* `address.postcode` (ZIP code in US)
* `address.country` (must be a 3-letter ISO code e.g. "GBR")
* `id_numbers` (selected countries only, please check [full list of supported countries with required and recommended data](/api/identity-supported-countries-and-data/))
* `phone_number` (selected countries only, please check [full list of supported countries with required and recommended data](/api/identity-supported-countries-and-data/))
The applicant [address object](#address-object) is nested inside the [applicant object](#applicant-object). You must provide full address information in the request. **The address field will not return a match if only** `address.postcode` **is provided.**
Alternatively, you can provide addresses in the form `line1`, `line2` and `line3`. If you provide address data in this form, Entrust uses a third-party subprocessor for address cleansing.
For more details, you can review the [full list of supported countries with required and recommended data](/api/identity-supported-countries-and-data/).
> ⚠️ **Warning:** If you don't provide date of birth or address information in the request, a `consider` response with no breakdown information is returned. This is an invalid response and should be interpreted as a failed report. Additionally, ensure that none of the required data contains special or non-ASCII characters, including symbols such as `()`, `@`, `;`, etc., as these may result in processing errors or invalid responses.
### Supported countries for Identity Enhanced
You can review the [full list of supported countries for Identity Enhanced
reports](/api/identity-supported-countries-and-data/).
This is not a list of documents that Entrust supports: you can [review that
list separately](https://www.entrust.com/products/identity-verification/document-verification/supported-documents/).
### Identity Enhanced: Report object
> ⚠️ **Warning:** The report object varies depending on the applicant's address `country` field.
#### United Kingdom
Example report object where the applicant's address is in the United Kingdom.
Sources (`credit_agencies`, `voting_register`, `telephone_database`) are displayed as breakdowns with their own `result` value.
#### United States
Example report object where the applicant's address is in the United States.
Any elements that are positively matched will be returned as `clear` in the report object breakdowns, including the source or sources of the database match in the properties field. When a match cannot be found (i.e. `result` is not `clear`) the corresponding `properties` bucket will be empty as such `"properties":{}`.
The report includes Social Security Number for a US applicant as an additional match under the `ssn` breakdown. This breakdown will not be returned if a SSN is not provided.
> ℹ️ **Note:** If an Identity enhanced report includes a Social Security Number breakdown, this will be returned in the `ssn` object for a report that was run using the using the `https://api.us.onfido.com/` base URL, and `ssn1` for a report that was run using the `https://api.eu.onfido.com/` base URL.
#### Non UK or US
Example report object where the applicant's address is not the United Kingdom or United States.
Sources are shown as comma separated under `properties`.
The report includes `national_id_number_matched` for a non UK or non US applicant as an additional match under the `national_id_number` breakdown. This breakdown will not be returned if a National ID Number is not provided or unsupported for the applicant's country.
### Identity Enhanced report custom logic
We've [moved this content](/guide/identity-enhanced-report#report-logic).
## Watchlist reports
This API documentation offers detailed information about the structure of a Watchlist report, including an example of the report's result and its breakdowns.
For a more general introduction to the Watchlist report, you can read our
[product documentation](/guide/watchlist-reports/).
There are 4 different types of Watchlist report:
| Report name | Request body in API |
| ----------------------------------------------------- | ---------------------------------------------- |
| [Watchlist AML](#watchlist-aml) | `"report_names": ["watchlist_aml"]` |
| [Watchlist Standard](#watchlist-standard) | `"report_names": ["watchlist_standard"]` |
| [Watchlist PEPs Only](#watchlist-peps-only) | `"report_names": ["watchlist_peps_only"]` |
| [Watchlist Sanctions Only](#watchlist-sanctions-only) | `"report_names": ["watchlist_sanctions_only"]` |
### Watchlist AML
The Watchlist AML report provides a granular breakdown of any records found when screening global watchlists and media sources. These include:
* `sanction`: Government and International Organisations Sanctions Lists
* `politically_exposed_person`: Proprietary database of Politically Exposed Persons sourced from government lists, websites and other media sources
* `legal_and_regulatory_warnings`: Law-Enforcement and Regulatory bodies Monitored Lists (including Terrorism, Money Laundering and Most Wanted lists)
* `adverse_media`: Negative events reported by publicly and generally available media sources
> **Note:** The Watchlist AML report is 6AMLD compliant.
#### [Matches](#watchlist-aml-matches)
If no match is found against the subject, the `matches` field will read `[]` and the overall `result` will be `clear`.
If one or more matches are found, each match will be returned under `matches` and the overall `result` will be `consider`.
> ⚠️ **Warning:** As matches are done based on the available information, none of these
> properties are guaranteed to be present in the response.
| Field | Description |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| assets | **array of objects**
An array containing objects with URLs to the images of the individual found in the match. |
| last\_updated\_utc | **string**
The date and time the entry was last updated. |
| media | **array of objects**
An array containing objects with URLs to various media related to the individual, such as images or videos. |
| name | **string**
The name on file. Allows for custom cross-referencing of input details against output details. |
| sources | **array of objects**
An array containing objects with information about where the data was obtained, for example, "PEPs list" and all related information from each source. |
| types | **array of strings**
The type of the source, for example, "pep-class-1". |
Where applicable, if multiple values are found from the raw response, string concatenation with a delimiter of ", " is used.
Entity fields are additional, optional fields so they may not be present in the final result.
#### [Required applicant data](#watchlist-aml-required-applicant-data)
For `watchlist_aml` reports, `first_name` and `last_name` must be provided.
#### [Recommended applicant data](#watchlist-aml-recommended-applicant-data)
`dob`
`address[]postcode` (ZIP code in US)
`address[]country`
`address[]state` (required for US addresses)
#### Date of birth
Submitting a `date_of_birth` with the name is optional but recommended, to narrow the search of the relevant individual.
More than one date of birth might be found per match due to the nature of the data sources, such as newspaper articles, which might include someone's age but not their full date of birth.
#### Address
Submitting an `address` with the country is optional but recommended.
The applicant [address object](#address-object) is nested inside the [applicant object](#applicant-object).
Results are filtered by country of operation or office, under these circumstances:
* There are PEP matches only
* There are PEP matches with Adverse Media
The country filter is not applied, or in other words, results will still appear regardless of the address country, under these circumstances:
* There are adverse media matches only
* Address does not have a country
* Sanctions, Money Laundering or Terrorist related events will always appear even if the country filter is applied
If a match is found but the `date_of_birth` or `address` fields are `null`, this means there is no `date_of_birth` or `address` data on file associated with that match.
### Watchlist Standard
The Watchlist Standard report provides a granular breakdown of any records found when screening global watchlists. These include:
* `sanction`: Government and International Organisations Sanctions Lists.
* `politically_exposed_person`: Proprietary database of Politically Exposed Persons sourced from government lists, websites and other media sources.
* `legal_and_regulatory_warnings`: Law-Enforcement and Regulatory bodies Monitored Lists (including Terrorism, Money Laundering and Most Wanted lists).
You can use a [Watchlist PEPs Only](#watchlist-peps-only) report to search only PEPs
lists, or a [Watchlist Sanctions Only](#watchlist-sanctions-only) report to search only
sanctions and warnings lists. The Watchlist Standard report will search all types.
#### [Records](#watchlist-standard-records)
If no match is found against the subject, the `matches` field will read `[]` and the overall `result` will be `clear`.
If one or more matches are found, each match will be returned under `matches` and the overall `result` will be `consider`.
See [Watchlist AML matches](#watchlist-aml-matches) for details of the possible fields.
#### [Required applicant data](#watchlist-standard-required-applicant-data)
For `watchlist_standard` reports, `first_name` and `last_name` must be provided.
#### [Recommended applicant data](#watchlist-standard-recommended-applicant-data)
`dob`
`address[]postcode` (ZIP code in US)
`address[]country`
`address[]state` (required for US addresses)
The applicant [address object](#address-object) is nested inside the [applicant object](#applicant-object). If you create an applicant object with an address, you must provide postcode and country, and state for US addresses.
If the applicant's address is provided, the `address[]country` field will narrow the search to include only PEPs who hold office in that country. The country filter will also be applied if an individual is both a PEP and has warnings or adverse media.
The country filter has no impact on sanctions results.
### Watchlist PEPs Only
The Watchlist PEPs Only report is a subset of the Watchlist Standard report. It provides a granular breakdown of `politically_exposed_person` breakdown matches.
Each match will be returned under `matches` and includes, but is not limited
to: name of match, associates, date of birth, related keywords, type of list,
name of list, and when the entry was last updated. When available, URLs to
data sources are provided, as well as pictures of the individual found in the
match. This allows you to quickly assess the relevancy of the match and
eliminate false positives. See [Watchlist AML matches](#watchlist-aml-matches) for details of the possible fields.
More than one date of birth might be found per match, due to the nature of the
data sources, such as news papers articles, which might include someone's age
but not their full date of birth.
#### [Required applicant data](#watchlist-peps-only-required-applicant-data)
For `watchlist_peps_only` reports, `first_name` and `last_name` must be provided.
#### [Recommended applicant data](#watchlist-peps-only-recommended-applicant-data)
`dob`
If the applicant's address is provided, the `address[]country` field will narrow the search to include only PEPs who hold office in that country. The country filter will also be applied if an individual is both a PEP and has warnings or adverse media.
The country filter has no impact on sanctions results.
### Watchlist Sanctions Only
The Watchlist Sanctions Only report is a subset of the Watchlist Standard report. It provides a granular breakdown of `sanction` breakdown matches.
Each match will be returned under `matches` and includes, but is not limited
to: name of match, associates, date of birth, related keywords, type of list,
name of list, and when the entry was last updated. When available, URLs to
data sources are provided, as well as pictures of the individual found in the
match. This allows you to quickly assess the relevancy of the match and
eliminate false positives. See [Watchlist AML matches](#watchlist-aml-matches) for details of the possible fields.
More than one date of birth might be found per match, due to the nature of the
data sources, such as news papers articles, which might include someone's age
but not their full date of birth.
#### [Required applicant data](#watchlist-sanctions-only-required-applicant-data)
For Watchlist Sanctions Only reports, `first_name` and `last_name` must be provided.
#### [Recommended applicant data](#watchlist-sanctions-only-recommended-applicant-data)
`dob`
## Proof of Address report
This API documentation offers detailed information about the structure of a Proof of Address report, including an example of the report's result and its breakdowns.
For a more general introduction to the Proof of Address report, you can read our
[product documentation](/guide/proof-of-address-report/).
### Supported issuing countries
Documents issued by the following countries are supported for a PoA report:
1. **Group A:**
* Andorra
* Gibraltar
* Isle of Man
* Jersey
* Monaco
* San Marino
* Switzerland
* United Kingdom
2. **Group B:**
* Canada
* European Economic Area (excluding Greece, Cyprus and Bulgaria)
* New Zealand
3. **Group C:**
* Algeria
* Argentina
* Australia
* Bermuda
* Brazil
* British Virgin Islands
* Bulgaria
* Cayman Islands
* Chile
* Colombia
* Costa Rica
* Dominican Republic
* Ecuador
* Ethiopia
* Ghana
* Guatemala
* Hong Kong
* Indonesia
* Ivory Coast
* Jamaica
* Japan
* Kenya
* Kuwait
* Malaysia
* Mexico
* Nigeria
* Panama
* Peru
* Philippines
* Saudi Arabia
* Senegal
* Serbia
* Singapore
* South Africa
* South Korea
* Taiwan
* Tanzania
* Turkey
* Uganda
* Ukraine
* United Arab Emirates
* United States of America
* Vietnam
You must set the `issuing_country` field to the corresponding country when uploading the document via the [document upload](#upload-document) endpoint.
Applicants are able to upload documents from anywhere in the world, but the document must have been issued by a supported country and be [a supported document for this report](#proof-of-address-supported-documents).
### [Required applicant data](#proof-of-address-required-applicant-data)
For Proof of Address reports, the following applicant data must be provided:
`first_name`
`last_name`
`address[]street`
`address[]town`
`address[]postcode`
`address[]country` (must be a 3-letter ISO code e.g. "GBR")
The applicant [address object](#address-object) is nested inside the
[applicant object](#applicant-object). If you create an applicant object with
an address, you must provide postcode and country, and state for US addresses.
> ⚠️ **Warning:** Checks where `applicant_provides_data` is set to `true` are not compatible
> with Proof of Address reports.
### [Supported document types](#proof-of-address-supported-documents)
The following document types are supported for a PoA report, along with its issue date validity based on document issuing country:
| Document | API Document type | Group A | Group B | Group C |
| ------------------------------------------------------------------------ | ----------------------------------- | ------------------- | ------------------- | ------------- |
| Bank Statement or Building Society Statement | `bank_building_society_statement` | Last 3 months | Last 6 months | Last 6 months |
| Utility Bill (electricity, water, gas, broadband, landline ) | `utility_bill` | Last 3 months | Last 6 months | Last 6 months |
| Local Government Tax Letter | `council_tax` | Last 1 year | Last 6 months | |
| Benefits Letter (e.g. Job seeker allowance, House benefits, Tax credits) | `benefit_letters` | Last 1 year | Last 6 months | |
| Mortgage statement | `mortgage_statement` | Last 1 year | Last 1 year | |
| Mobile phone bill | `mobile_phone_bill` | | Last 6 months | |
| General letter (financial institution/utility company) | `general_letter` | | Last 6 months | |
| Insurance statement or brokerage statement | `insurance_statement` | | Last 6 months | |
| Pension statement/letter or Property tax statement/letter | `pension_property_statement_letter` | | Last 1 year | |
| Identity document with address | `identity_document_with_address` | Must not be expired | Must not be expired | |
| Exchange House Statement | `exchange_house_statement` | | | Last 6 months |
| Accommodation or Tenancy Certificate | `accommodation_tenancy_certificate` | | Last 6 months | Last 6 months |
> ⚠️ **Warning:** Local Government Tax Letters and Benefits Letter are only supported if issued by the UK.
> ⚠️ **Warning:** Address certificates (`address_certificate`) are only supported if issued in Hungary and Turkey. If dates are present, address certificates must not be expired.
> ⚠️ **Warning:** When [uploading documents](#upload-document) with 2 sides (e.g. `identity_document_with_address`), `document_type` should be specified and both sides of the document should be uploaded as separate documents, specifying `side` value for each one.
> ⚠️ **Warning:** Exchange House Statements are only supported if provided from authorized issuers in the United Arab Emirates.
> ⚠️ **Warning:** Kenya is the only Group C country that accepts Local Government Tax Letters.
> ⚠️ **Warning:** Singapore is the only Group C country that accepts Mobile Phone Bills.
### Proof of Address: Breakdowns
A PoA report is composed of the following 3 breakdowns:
| Breakdown | Description |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `image_integrity` | **object**
Asserts whether the quality of the uploaded document was sufficient to verify the address |
| `document_classification` | **object**
Asserts whether the document is a [supported document type](#proof-of-address-supported-documents) and the document has a valid date of issue |
| `data_comparison` | **object**
Asserts whether the first name, last name and address provided by the applicant match those on the PoA document |
| `source_integrity` | **object**
Asserts whether the source integrity of the uploaded document is sufficient to verify the address |
### Proof of Address: Properties
In addition, data points extracted from PoA documents are returned in the `properties` attribute.
| Field | Description |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `document_type` | This property provides the document type according to the set of [supported documents](#proof-of-address-supported-documents) |
| `document_source_type` | This property provides the [document source type](#document-source-types) |
| `issue_date` | This property provides the issue date of the document |
| `expiry_date` | This property provides the expiry date of the document |
| `summary_period_start` | This property provides the summary period start date |
| `summary_period_end` | This property provides the summary period end date |
| `issuer` | This property provides the document issuer (e.g. HSBC, British Gas) |
| `first_names` | This property provides the first names on the document, including any initials and middle names |
| `last_names` | This property provided the last names on the document |
| `address` | This property provides the address on the document |
| `address_parsed` | **object**
This property provides a structured address |
| `unsupported_document_reason` | **array**
The reasons why the document is unsupported (possible values include `unsupported_doc_type`, `unsupported_alphabet`, `unsupported_country` or `possible_fraud`). |
Only the summary period or the issue date will be returned in the report properties attribute as they are mutually exclusive.
Issue date may not be returned if document has only expiry date.
### [Document source types](#proof-of-address-document-source-types)
The following document source types can be returned for a PoA report:
| Source type | Description |
| ----------------- | ---------------------------------------------------------------------------------------- |
| `pdf` | Document is a PDF file |
| `photo_of_screen` | Document is a photo of a monitor, phone, tablet etc. that was taken using another device |
| `screenshot` | Document is an image taken using the native screenshot function on a device |
| `paper_document` | Document is a picture of the paper document |
### Proof of Address: Overall Result Logic
We've [moved this content](/guide/proof-of-address-report#overall-result-logic).
## Driver's License Data Verification report
This API documentation offers detailed information about the structure of a Driver's License Data Verification (DLDV) report, including an example of the report's result and its breakdowns.
For a more general introduction to the DLDV report, you can read our
[product documentation](/guide/drivers-license-data-verification-report/).
> **Note:** The DLDV report is for United States documents only.
To request a DLDV report as part of a check in the API, use the `report_names` field (which takes an array of strings):
`"report_names": ["us_driving_licence"]`
To upload document data, use the `us_driving_licence` field (which is an object containing all accepted fields for the DLDV report).
```json
...
"report_names": ["us_driving_licence"],
"us_driving_licence":{
"id_number": "", // required
"issue_state": "", // required
... // all other optional fields
}
...
```
See [optional document data](#dldv-optional-document-data) for a table of the accepted optional fields in the `us_driving_licence` object for a DLDV report.
See [create a check](#create-check-request-body) for a full list of the possible request body parameters.
If you use this report, Entrust will use a third-party subprocessor to verify driving license data against the American Association of Motor Vehicle Administrators (AAMVA) facilitated Department of Motor Vehicles (DMV) driver's license database.
### [Required applicant data](#dldv-required-applicant-data)
For DLDV reports, `first_name` and `last_name` must be provided.
### [Required document data](#dldv-required-document-data)
For DLDV reports, the following document data must be provided in the report request in the `us_driving_licence` field:
| Field | Format |
| ------------- | -------------------------------------- |
| `id_number` | String |
| `issue_state` | String
(2-character state code) |
#### [Optional document data](#dldv-optional-document-data)
The following optional fields are also accepted in the `us_driving_licence` object:
| Field | Format | Possible values |
| ----------------------- | -------------------------------------- | ------------------------------------------------------------- |
| `address_line_1` | String | |
| `address_line_2` | String | |
| `city` | String | |
| `date_of_birth` | Date
YYYY-MM-DD | |
| `document_category` | Enum | "driver license", "driver permit", "id card" |
| `expiration_date` | Date
YYYY-MM-DD | |
| `eye_color_code` | Enum | "BLK", "BLU", "BRO", "DIC", "GRY", "GRN", "HAZ", "MAR", "PNK" |
| `first_name` | String | |
| `gender` | String | |
| `height_measure_feet` | Integer | |
| `height_measure_inches` | Integer | |
| `issue_date` | Date
YYYY-MM-DD | |
| `last_name` | String | |
| `middle_name` | String | |
| `name_suffix` | String | |
| `postal_code` | String | |
| `state` | String
(2-character state code) | |
| `weight_measure` | Integer
(in pounds) | |
### [Supported document types](#dldv-supported-document-types)
* US driver's license
* US learner's permit or provisional license
* ID card
> **Note:** A DLDV report does not require a document upload. Data is entered manually in
> the report request.
### Supported Issue States
* AL
* AR
* AZ
* CO
* CT
* DC
* DE
* FL
* GA
* HI
* IA
* ID
* IL
* IN
* KS
* KY
* MA
* MD
* ME
* MI
* MO
* MS
* MT
* NC
* ND
* NE
* NH
* NJ
* NM
* NV
* OH
* OK
* OR
* RI
* SC
* SD
* TN
* TX
* VA
* VT
* WA
* WI
* WV
* WY
### DLDV: Results
The `result` field indicates the overall report result. Any optional fields submitted in the report request will be accounted for in the final result.
Possible values for
DLDV reports are `clear`, `consider` and `unidentified`:
| Report result | Description |
| ------------- | ------------------------------------------------------------------------------------------------------- |
| clear | All fields exact match |
| consider | Name fields have been flagged as a mismatch through fuzzy matching\* or any optional fields don't match |
| unidentified | ID number or name field doesn't match |
\* Entrust's third-party subprocessor uses fuzzy matching on the name fields during DLDV checks. This is because information can be provided in many different ways and errors in data submission or collection can be quite high. Fuzzy matching allows capturing data variations.
### DLDV: Breakdowns
Breakdowns can have a `clear` or `consider` result. Breakdowns will only have a `clear` result when all included sub-breakdowns are `clear`.
| Breakdown | description | sub-breakdowns |
| --------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| document | **object**
Asserts whether the document data provided matches a real driving license in the DMV driver's license database. | category
expiration\_date
issue\_date
document\_number |
| address | **object**
Asserts whether the address data provided matches a real driving license in the DMV driver's license database. | city
line\_1
line\_2
state\_code
zip4
zip5 |
| personal | **object**
Asserts whether the personal data provided matches a real driving license in the DMV driver's license database. | name\_suffix
height
weight
sex\_code
eye\_color
date\_of\_birth
first\_name
last\_name
middle\_name
first\_name\_fuzzy
middle\_name\_fuzzy
last\_name\_fuzzy
middle\_initial |
## Device Intelligence report
This API documentation offers detailed information about the structure of a Device Intelligence report, including an example of the report's result and its breakdowns.
For a more general introduction to the Device Intelligence report, you intend read our
[product documentation](/guide/device-intelligence-report/).
> ⚠️ **Warning:** The Device Intelligence report will be more effective and provide better data if you're using the Entrust Identity Verification SDKs and not sending the media via the API directly.
> ℹ️ **Note:** You can run Device Intelligence as a standalone report, but we recommend that you combine it with a Document or Facial Similarity report in the same check.
### [Required applicant data](#device-intelligence-required-applicant-data)
For Device Intelligence reports, the following applicant data must be provided:
* `first_name` and `last_name`
* a document or biometric media upload via the Entrust Identity Verification SDKs
### Raw signals collected
| Signal grouping | Category | Description |
| --------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Entrust check data | User | Entrust operational data required for Entrust Services: Entrust User unique identifier, check status/outcome and related tracking information, inferences and outputs from Device Intelligence (e.g. risk score, risk level.) |
| User data | User | Document number and other data extracted from any associated doc and bio check. |
| IP address information | IP | IP address and IP address type, including associated geo-location city/region/country level location. |
| Device fingerprint | Device | Device identifiers including audio and video fingerprint, canvas and WebGL fingerprinting. |
| Media uploaded by user | Media | Media itself, as well as any related metadata, such as complete EXIF extraction and other embedded metatags in media itself. |
| Camera | Device | Capture of camera feed and information like: camera name, microphone name, aspect ratio, resolution, frame rate, etc. |
| Device metadata & browser headers | Device | Information about Users' device including hardware and software attributes (e.g. device type and model, manufacturer, operating system type and version (e.g. iOS or Android), browser type and version, user-agent, navigator, screen details, plugins, fonts, memory, WebGL, battery information, language, timezone, camera name, microphone name, aspect ratio, resolution, frame rate, etc.) |
| Entrust Device ID | Device | Unique identifier stored by Entrust in the device and used to verify re-use of the device. |
| End user interactions | Usage data | Information about an end user’s interactions with the Services, including how the end user uses the Services such as date and time stamps, forms/fields completed, pointer and touch events, timezone offset, distraction events. |
| Application Authenticity | Device | Operational data related to verification flow, used to check whether the device is using stolen security tokens. |
Available for SDK versions iOS 22.4.0 +; Android 9.2.0 +; Web 5.10.0 +
### Device Intelligence: Results
The `result` field indicates the overall report result.
Possible values for Device Intelligence reports are `clear` and `consider`:
| Report result | Description |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| clear | The applicant used a valid device and is not associated with suspicious behavior, indicating they are a genuine user. |
| consider | The applicant was detected to have used an invalid device or is associated with suspicious behavior, indicating they may be a fraudulent user. |
In addition, any additional data and signals are returned in the [`properties`](#device-intelligence-properties) attribute.
### Device Intelligence: Breakdowns
Breakdowns can have a `clear` or `consider` result.
| Breakdown | description |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `device` | **object**
Asserts whether the device used to upload the media is trustworthy, i.e. it is a real, physical device. |
| (sub-breakdown) `application_authenticity` | **object**
Contains `fake_network_request` under the `properties` bag ([see Device Intelligence: Application Authenticity properties](#device-intelligence-application-authenticity-properties)). |
| (sub-breakdown) `device_integrity` | **object**
Contains `randomized_device`, `emulator`, `single_device_used`, `document_capture` and `biometric_capture` under the `properties` bag ([see Device Intelligence: Device Integrity properties](#device-intelligence-device-integrity-properties)). |
| (sub-breakdown) `device_reputation` | **object**
Contains `ip_reputation` and `device_fingerprint_reuse` under the `properties` bag ([see Device Intelligence: Device Reputation properties](#device-intelligence-device-reputation-properties)) |
#### Device Intelligence: Application Authenticity properties
We will return a reason whenever a report flags for `application_authenticity`. The property will be returned as `true` and the sub-breakdown will have a `consider` result.
* `fake_network_request` - when the device used stolen security tokens to send the network information
#### Device Intelligence: Device Integrity properties
We will return a reason whenever a report flags for `device_integrity`. There can be more than one reason, because they aren't mutually exclusive.
* `randomized_device` - when the device provided false randomized device and network information. The property will be returned as `true` and the sub-breakdown will have a `consider` result.
* `emulator` - when evidence is found that an emulator was used. The property will be returned as `true` and the sub-breakdown will have a `consider` result.
* (For opted in customers only) `single_device_used` - when the associated document and biometric media weren't uploaded from the same device. The property will be returned as `false` and the sub-breakdown will have a `consider` result.
* (For opted in customers only) `document_capture` - when the associated document media weren't confirmed to be live captured from the device camera. The property will not be returned as `live` and the sub-breakdown will have a `consider` result.
* (For opted in customers only) `biometric_capture` - when the associated biometric media weren't confirmed to be live captured from the device camera. The property will not be returned as `live` and the sub-breakdown will have a `consider` result.
#### Device Intelligence: Device Reputation properties
We will return a reason whenever a report flags for `device_reputation`. There can be more than one reason, because they aren't mutually exclusive.
* `ip_reputation` - when there is highly suspicious traffic related to the IP address, the sub-breakdown will have a `consider` result.
* `device_fingerprint_reuse` - when the same fingerprint was reused too many times, the sub-breakdown will have a `consider` result.
### Device Intelligence: Properties
Data and signals collected about the device, IP, and geolocation are returned in the `properties` attribute.
Note: All properties can take the value `null` in addition to their corresponding list of possible values.
#### `device` object
| Field | Description | Possible values |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| authentication\_type | **string**
The token used to authenticate the request. | sdk\_token, mobile\_token, api\_token |
| biometric\_capture | **string**
Whether the biometric media were live captured from the device camera. | live, unknown\_method |
| browser | **string**
The browser name reported by the browser's user agent. | - |
| browser\_developer\_tools | **null** and **boolean**
Whether developer tools are open and/or being used to control the browser instance. | null, true, false |
| browser\_incognito | **null** and **boolean**
Whether the browser is running in incognito or privacy mode. | null, true, false |
| browser\_privacy\_settings | **null** and **boolean**
Whether the browser has enabled settings that fight fingerprinting. | null, true, false |
| data\_available | **boolean**
Whether data was found for the applicant. In rare cases, we're unable to find the signals associated with the applicant. Instead of completely failing the report, we return an incomplete report with this property set to `true`. | true, false |
| device\_fingerprint\_reuse | **integer**
The number of times the device was used to create a report for a new applicant. A value greater than 1 indicates potential device reuse. | - |
| document\_capture | **string**
Whether the document media were live captured from the device camera. | live, unknown\_method |
| emulator | **boolean**
Whether the device is an emulator. | true, false |
| fake\_network\_request | **boolean**
Whether device is using stolen security tokens to send the network information. | true, false |
| ip\_reputation | **string**
Whether there is highly suspicious traffic related to the IP address. The risk depends on the overall ratio of clear checks on a given IP. In case the IP is not highly reused we return `NOT_ENOUGH_DATA`. | NOT\_ENOUGH\_DATA, HIGH\_RISK, LOW\_RISK |
| jailbroken | **boolean**
Whether the iOS device has been jailbroken. | null, true, false |
| number\_of\_ip\_reuse\_reports | **number**
Number of times the IP address used by the applicant to submit media matched an IP address associated with another report. | 0.0 |
| number\_of\_suspected\_ip\_reuse\_reports | **number**
Number of times the IP address used by the applicant to submit media matched an IP address associated with a suspected report. | 0.0 |
| os | **string**
The operating system of the device. The value came from manufacturer implementation (for Android and iOS) or browser's user agent (for Web). | - |
| os\_anomaly | **string** (***deprecated field***)
The likelihood of an operating system anomaly between the true OS and the OS sent by the device. | null |
| randomized\_device | **boolean**
Whether the device is providing false randomized device and network information. | true, false |
| raw\_model | **string**
The model as set by the phone manufacturer (for Android and iOS) or the browser manufacturer (for Web). The model can be presented in name or number form depending on each manufacturer implementation. | - |
| remote\_software | **boolean** (***deprecated field***)
Whether the device is controlled via remote software. | null |
| rooted | **boolean**
Whether the Android device has been rooted. | null, true, false |
| sdk\_source | **string**
The SDK used to upload the media. | onfido-android-sdk, onfido-ios-sdk, onfido-web-sdk |
| sdk\_version | **string**
The SDK version that was used. | - |
| single\_device\_used | **null** and **boolean**
Whether the document or biometric media were uploaded from a single device. | null, true, false |
| true\_os | **string** (***deprecated field***)
The true operating system of the device. | null |
| virtual\_machine | **null** and **boolean**
Whether the device is a virtual machine. | null, true, false |
#### `ip` object
| Field | Description | Possible values |
| ---------------- | ------------------------------------------------------------------------------------------------ | ------------------------- |
| address | **string**
The IP address that uploaded the media. | - |
| asn\_name | **string**
The name of the autonomous system (ASN) associated with the IP address. | - |
| asn\_network | **string**
The network of the autonomous system (ASN) associated with the IP address. | - |
| asn\_type | **string**
The type of the autonomous system (ASN) associated with the IP address. | - |
| proxy | **boolean**
Whether the connection is using a proxy. | null, true, false |
| proxy\_detection | **string** (***deprecated field***)
The likelihood of the network connection being a proxy. | null |
| proxy\_provider | **string**
When it is a datacenter proxy, the provider of the proxy. | - |
| proxy\_type | **string**
The type of proxy being used. | data\_center, residential |
| tor\_node | **string**
Whether the connection is using a Tor exit node. | null, true, false |
| type | **string** (***deprecated field***)
The type of organization that owns this IP address. | null |
| vpn | **boolean**
Whether the connection is using a VPN. | null, true, false |
| vpn\_detection | **string** (***deprecated field***)
The likelihood of the network connection being a VPN. | null |
#### `geolocation` object
| Field | Description | Possible values |
| --------- | ---------------------------------------------------------------------------- | --------------- |
| city | **string**
City location of the IP address. | - |
| country | **string**
Country location of the IP address in a three letter format. | - |
| latitude | **number**
Latitude of the IP address geolocation. | [-90.0, 90.0] |
| longitude | **number**
Longitude of the IP address geolocation. | [-180.0, 180.0] |
| region | **string**
Region location of the IP address. | - |
| timezone | **string**
Timezone of the IP address geolocation. | - |
## India Tax ID report
This API documentation offers detailed information about the structure of a India Tax ID report, including an example of the report's result and its breakdowns.
For a more general introduction to the India Tax ID report, you can read our
[product documentation](/guide/india-tax-id-report/).
> ⚠️ **Warning:** The India Tax ID report is for use with Indian Permanent Account Number (PAN) cards only.
### [Required applicant data](#device-intelligence-required-applicant-data)
For India Tax ID reports, the following applicant data must be provided:
* `first_name`
* `last_name`
* PAN in the [`id_numbers`](#id-number-object) object.
### [Supported document types](#pan-supported-document-types)
* Indian PAN card
> **Note:** An India Tax ID report does not require a document upload.
### India Tax ID: Result logic
The `result` field indicates the overall report result. Possible values for PAN reports are `clear` or `consider`:
| Report result | Logic |
| ------------- | ---------------------------------------------------------- |
| clear | The applicant's PAN is valid and full name matches. |
| consider | The applicant's PAN is invalid or full name doesn't match. |
> ⚠️ **Warning:** The report is withdrawn if the required applicant data is not provided or the PAN is not for an individual person.
In addition, the applicant's PAN and full name are returned in the [`properties`](#device-intelligence-properties) attribute.
### India Tax ID: Breakdowns
Breakdowns can have a `clear` or `consider` result.
| Breakdown | description |
| ------------ | -------------------------------------------------------------------------------------------------------------- |
| `pan_valid` | **object**
Asserts whether the applicant's PAN is valid1. |
| `name_match` | **object**
Asserts whether the applicant's provided full name matches that in the database.2 |
1. Entrust uses a third-party subprocessor to match the provided PAN against the central Indian government database.
2. Entrust uses fuzzy matching on the name fields. This is because information can be provided in many different ways and errors in data submission or collection can be quite high. Fuzzy matching allows capturing data variations.
### India Tax ID: Properties
The applicant's PAN and full name is returned in the `properties` attribute.
| Field | Description |
| ----------- | --------------------------------------------------- |
| `pan` | The applicant's PAN (10 digit alphanumeric number). |
| `full_name` | The applicant's full name. |
## Ping
`GET /ping`
Runs a health check on the API.
If the [regional base URL](#regions) you're using is operational, the `ping` endpoint will return `OK` in
Text format.
You can also subscribe to webhook notifications from
[https://status.onfido.com](https://status.onfido.com).
## Address Picker
`GET /v3.6/addresses/pick?postcode={postcode}`
Performs a search for addresses by postcode (UK only).
Returns data in the form: `{"addresses": []}`.
The Entrust Address Picker will always use a third-party subprocessor for address cleansing. In this way, it can be used to make sure addresses passed to the [create applicant endpoint](#create-applicant) are valid.
### [Query string parameters](#address-picker-query-string-parameters)
`postcode` (required): the applicant's postcode.
## Generate SDK token
`POST /v3.6/sdk_token`
> ⚠️ **Warning:** Generating an SDK token will enable applicants to send
> personal data to Entrust via one of our SDKs. For more information on how Entrust uses
> personal data, view our [Privacy Policy](https://onfido.com/privacy/).
> ⚠️ **Warning:** For customers integrated with Workflow Studio, SDK tokens are exposed and returned in the payload of a [workflow run object](/api/latest/#workflow-run-object) when created.
> This endpoint documentation is only relevant to customers who are yet to migrate to Workflow Studio and are integrated with our Checks and Reports API.
Entrust's Identity Verification SDKs are authenticated using SDK tokens. This endpoint generates an SDK token, returning a `token` object containing the SDK token.
SDK tokens can only be used in our input-capture SDKs. They are restricted to
an individual applicant, and expire after 90 minutes.
You'll need to generate and include a new token each time you initialize the Entrust Identity Verification SDKs.
The SDK token object returned in the response is of the form: `{"token": "header.payload.signature"}`.
The composition and length of SDK tokens is variable and can change over time.
### [Request body parameters](#sdk-token-request-body)
| Parameter | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `applicant_id` | **required**
Specifies the applicant for the SDK instance. |
| `application_id` | **optional, should not be used if `referrer` provided**
The application ID (or "application bundle ID") - used with the iOS and Android SDKs. |
| `referrer` | **optional, should not be used if `application_id` provided**
The referrer URL pattern - used with the Web SDK. |
| `cross_device_url` | **optional**
The URL to be used by the Web SDK for the cross-device flow. (Max 24 characters).
This replaces the default id.onfido.com and requires additional setup to map back to the Entrust hosted cross-device address. |
Each authenticated instance of the SDK will correspond to a single applicant as specified by the `applicant_id`.
### The application\_id
The `application_id` is the "Application ID" or "Bundle ID" on iOS and Android
that was set up during development. For iOS, this is usually in the form
`com.your-company.app-name`. For Android, this is usually in the form
`com.example.yourapp`. Make sure to use a valid `application_id` or you'll
receive a [401 error](#error-codes-and-what-to-do).
If you want to disable the application ID check, you can pass the wildcard `*`. Alternatively, don't pass either of the `application_id` and `referrer` parameters.
#### The referrer argument
The referrer argument specifies the URL of the web page where the Web SDK will
be used. The referrer sent by the browser must match the referrer URL pattern
in the SDK token for the SDK to successfully authenticate. The referrer is based on
the Google Chrome [match
pattern](https://developer.chrome.com/extensions/match_patterns) URLs. URLs
can contain wild card characters.
The referrer pattern guarantees that other malicious websites cannot reuse the
token in case it is lost. You can read more about referrer policy [in
Mozilla's
documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy).
If you want to disable the referer header check, you can pass the wildcard `*`. Alternatively, don't pass either of the `application_id` and `referrer` parameters.
> ⚠️ **Warning:** You must use a site referrer policy that lets the
> `Referer` header be sent. If your policy does not allow this (e.g.
> `Referrer-Policy: no-referrer`), then you'll receive a `401 bad_referrer`
> error when trying to use the Web SDK.
Permitted referrer patterns are as follows:
| Section | Format | Example |
| -------- | -------------------------------------------- | ----------------------------- |
| Referrer | `scheme://host/path` | `https://*.//*` |
| Scheme | `*` or `http` or `https` | `https` |
| Host | `*` or `*.` then any char except `/` and `*` | `*.` |
| Path | Any char or none | `/*` |
An example of a valid referrer is `https://*.example.com/example_page/*`.
#### The cross\_device\_url argument
The cross-device flow of the Web SDK allows users to continue the identity verification process
from their phone where they can take pictures of their document and themselves rather than uploading
images from their desktop. This feature is available to all customers and uses the URL id.onfido.com
as the default. The `cross_device_url` argument is used to white-label the default Entrust cross-device
URL to one of your choosing with a maximum character length of 24 including `https://`. While the
cross-device flow is available to all customers, white-labeling the URL using this argument is a premium
enterprise feature that must be activated for your account before it may be used. Please talk to
your account executive for more information about purchasing this feature.
Example SMS before and after using this feature:
Before:
`Continue your identity verification by tapping https://id.onfido.com/`
After:
`Continue your identity verification by tapping /`
## [Repeat attempts](#repeat-attempts-1)
The repeat attempts endpoint allows you to request a list of repeat attempt matches for [Document reports](#document-report) to show instances of repeat fraud where users submit multiple requests using the same document.
A repeat attempt is any previous Document report that was submitted using a document that matches other previously onboarded documents in your Entrust database. For each repeat attempt match, Entrust returns whether the name, date of birth and document number on the document matches the personal document data used for each previous attempt.
If the personal document data doesn't match, this indicates that one, or potentially multiple, of the documents might be fraudulent. A large number of repeat attempts can also signal fraudulent behavior.
### Document Known Faces
Document Known Faces is an add-on to Repeat Attempts and flags when identity documents have the same face but different PII (personal identifiable information) data, i.e. name, date of birth or document number.
Document Known Faces will not flag cases where the same document is reused with identical PII data (i.e. no changes to name, date of birth or document number) but the faces failed to match. In this scenario, the `unique_mismatches_count` will remain 0 as this metric only tracks changes in PII data, not facial mismatches.
Document Known Faces requires the customer's explicit opt-in.
> **Note:** The repeat attempts endpoint is for use with Document reports only.
### Retrieve repeat attempts
`GET /v3.6/repeat_attempts/{report_uuid}`
> ⚠️ **Warning:** This endpoint documentation is only relevant to customers who have yet to migrate to Workflow Studio and are integrated with our Checks and Reports API.
> For Studio customers, Repeat Attempts results can be consumed by making a [Retrieve Workflow Run](/api/latest/#retrieve-workflow-run) call to the Entrust Identity Verification API. Results are found in the `output` property.
Returns all repeat attempts for a given Document report.
> ℹ️ **Note:** The Document report must have completed before you can request repeat attempts via this endpoint.
#### Response
Returns a repeat attempts object containing an array of repeat attempts.
| Attribute | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `report_id` | **string**
The uuid of the completed Document report. |
| `repeat_attempts` | **array of objects**
An array of repeat attempt objects. If no repeat attempts were found, the array will be empty. The number of objects returned can increase over time if more matches are received. |
| `attempts_count` | **int**
The total number of attempts using the same document, including the current report under assessment. |
| `attempts_clear_rate` | **float**
A number between 0 and 1 which indicates the proportion of attempts that have been cleared, including the current report under assessment. |
| `unique_mismatches_count` | **int**
The number of unique entries in the `repeat_attempts` field for which at least one of the fields is a mismatch. |
#### Repeat attempts object
The `repeat_attempts` array of objects is nested inside the repeat attempts response object.
When a customer opts in for Document Known Faces, a new field named `face` is included in the Repeat Attempts response indicating whether the match was found through Document Known Faces.
The Document Known Faces response is available only on API version >= 3.6.
| Attribute | Description | Possible values |
| --------------- | ---------------------------------------------------------------------------------- | ------------------- |
| `report_id` | **string**
The uuid of the matching Document report. | - |
| `applicant_id` | **string**
The uuid of the applicant for the matching Document report. | - |
| `date_of_birth` | **string**
Whether the dates of birth are exactly the same or are different. | `match`, `mismatch` |
| `names` | **string**
Whether the names are exactly the same or are different. | `match`, `mismatch` |
| `face` | **string**
Whether the match was found through Document Known Faces. | `match`, `mismatch` |
| `result` | **string**
The report result of this attempt. | `clear`, `consider` |
| `created_at` | **datetime**
When the matching report was created. | - |
| `completed_at` | **datetime**
When the matching report was completed. | - |
> ⚠️ **Warning:** Document reports flagged as `suspected` for [`data_consistency`](#data_consistency) will not be returned by this endpoint. This is to ensure that data was correctly extracted, and the matches are relevant.
## Autofill
`POST /v3.6/extractions`
> ⚠️ **Warning:** Using this endpoint in a live context will cause you to
> send personal data to Entrust. Always make sure you inform your users about
> this and obtain any necessary permissions. For more information on how Entrust
> uses personal data, view our [Privacy
> Policy](https://onfido.com/privacy/).
> ⚠️ **Warning:** This endpoint documentation is only relevant to customers who have yet to migrate to Workflow Studio and are integrated with our Checks and Reports API.
> For Studio customers, Autofill is implemented as part of your identify verification flows by adding an [Autofill task](/guide/autofill/#autofill-task) to a Studio workflow from the Workflow Builder.
Autofill takes an [uploaded document](#upload-document) and returns information extracted from the document. This is a synchronous request, which means the extracted information will be presented immediately in the API response.
### [Request body parameters](#autofill-request-body)
| Parameter | Description |
| ------------ | -------------------------------------------------------------------------------------- |
| document\_id | **required**
The unique identifier of the uploaded document to run extraction on |
### Extraction result
If data has been successfully extracted, the API response will contain the properties `document_classification` and `extracted_data`.
`document_classification` has the following properties:
| Field | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| issuing\_country | Document country in 3-letter ISO code |
| document\_type | Type of document. See [Document types](#document-types). Only certain document types are supported by Autofill. Please contact [identity-client-support@entrust.com](mailto:identity-client-support@entrust.com) to find out more. |
| issuing\_state | The state that issued the document. Only returned for a subset of documents. |
| subtype | The document subtype. Only extracted from USA and UK Driving Licences. For USA DLs, it returns `full` or `u21`. For UK DLs, it returns `full` or `provisional`. |
| version | The document issuing version. Only returned for a subset of documents. |
`extracted_data` has the following properties:
> ⚠️ **Warning:** As extraction is done on a best-effort basis, and also information varies across different documents, none of these properties are guaranteed to be present in the response.
Extraction data will not be populated if the document is issued by a country subject to comprehensive US sanctions.
| Field | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| document\_number | The official document number. |
| first\_name | First name. |
| last\_name | Last name. |
| middle\_name | Middle name. |
| full\_name | Full name. |
| spouse\_name | Spouse name (French documents only). |
| widow\_name | Widow name (French documents only). |
| gender | Gender. Valid values are `Male` and `Female`. |
| date\_of\_birth | Date of birth in YYYY-MM-DD format. |
| date\_of\_expiry | Date of expiry in YYYY-MM-DD format. |
| expiry\_date | Date of expiry in YYYY-MM-DD format. |
| nationality | Nationality in 3-letter ISO code. |
| mrz\_line1 | Line 1 of the MRZ code. |
| mrz\_line\_1 | Line 1 of the MRZ code. |
| mrz\_line2 | Line 2 of the MRZ code. |
| mrz\_line\_2 | Line 2 of the MRZ code. |
| mrz\_line3 | Line 3 of the MRZ code. |
| mrz\_line\_3 | Line 3 of the MRZ code. |
| address\_line\_1 | Line 1 of the address. |
| address\_line\_2 | Line 2 of the address. |
| address\_line\_3 | Line 3 of the address. |
| address\_line\_4 | Line 4 of the address. |
| address\_line\_5 | Line 5 of the address. |
| issuing\_authority | Issuing authority. |
| issuing\_country | Document country in 3-letter ISO code. |
| document\_type | Type of document. See [Document types](#document-types). Only certain document types are supported by Autofill. Please contact [identity-client-support@entrust.com](mailto:identity-client-support@entrust.com) to find out more. |
| place\_of\_birth | Place of birth. |
| issuing\_state | The state that issued the document. |
| issuing\_date | Issuing date in YYYY-MM-DD format. |
| personal\_number | The owner's unique identification number. |
### Unsuccessful extraction
#### Classification failure
If the document cannot be recognised, a `classification_failure` will be returned.
#### Extraction failure
If no data can be extracted, an `extraction_failure` will be returned.
## Generate OAuth access token
Generates an OAuth access token to be used for machine-to-machine authentication with [client credentials grant](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/).
`POST /v3.6/oauth/token`
The necessary fields should be retrieved from the [Dashboard](https://dashboard.onfido.com/) when creating a new OAuth application.
### [Request body parameters](#oauth-token-request-body)
| Parameter | Description |
| --------------- | --------------------------------------------------------------------------------------------- |
| `client_id` | **required**
The client\_id of the OAuth application to generate the access token. |
| `client_secret` | **required**
The client\_secret of the OAuth application to generate the access token. |
The access token has an expiration of 60 minutes, and the endpoint has a caching layer which makes it idempotent while the access token is valid, meaning that for each client\_id/client\_secret pair we will return the same access token while it's still valid.
### OAuth Scopes
You can control the level of access each OAuth application can have when invoking the Public API. This is managed with scopes in the [Dashboard](https://dashboard.onfido.com/).
*Note:* The list of selected scopes can't be changed when requesting a new access token, meaning the allowed list is fixed per OAuth application.
The following table lists the necessary scopes for each API endpoint:
| Resource path | HTTP method | Required scope |
| -------------------------------------------- | ----------- | ----------------- |
| /applicants | GET | applicants:read |
| /applicants | POST | applicants:write |
| /applicants/:id | GET | applicants:read |
| /applicants/:id | PUT | applicants:write |
| /applicants/:id | DELETE | applicants:delete |
| /applicants/:id/restore | POST | applicants:write |
| /addresses/pick | GET | applicants:read |
| /biometric\_tokens/:id | GET | biometrics:read |
| /biometric\_tokens/:id | DELETE | biometrics:delete |
| /biometric\_tokens/:id/:token\_id | GET | biometrics:read |
| /biometric\_tokens/:id/:token\_id | PUT | biometrics:write |
| /biometric\_tokens/:id/:token\_id | DELETE | biometrics:delete |
| /checks | GET | checks:read |
| /checks | POST | checks:write |
| /checks/:id | GET | checks:read |
| /checks/:id/download | GET | checks:read |
| /checks/:id/resume | POST | checks:write |
| /checks/:id/tags | POST | checks:write |
| /documents | GET | documents:read |
| /documents | POST | documents:write |
| /documents/:id | GET | documents:read |
| /documents/:id/download | GET | documents:read |
| /documents/:id/nfc\_face | GET | documents:read |
| /documents/:id/video/download | GET | documents:read |
| /electronic\_signature/documents | GET | workflows:read |
| /evidence\_file | GET | checks:read |
| /extractions | POST | autofill:write |
| /id\_photos | GET | biometrics:read |
| /id\_photos | POST | biometrics:write |
| /id\_photos/:id | GET | biometrics:read |
| /id\_photos/:id/download | GET | biometrics:read |
| /live\_photos | GET | biometrics:read |
| /live\_photos | POST | biometrics:write |
| /live\_photos/:id | GET | biometrics:read |
| /live\_photos/:id/download | GET | biometrics:read |
| /live\_videos | GET | biometrics:read |
| /live\_videos/:id | GET | biometrics:read |
| /live\_videos/:id/download | GET | biometrics:read |
| /live\_videos/:id/frame | GET | biometrics:read |
| /motion\_captures | GET | biometrics:read |
| /motion\_captures/:id | GET | biometrics:read |
| /motion\_captures/:id/download | GET | biometrics:read |
| /motion\_captures/:id/frame | GET | biometrics:read |
| /qualified\_electronic\_signature/documents | GET | workflows:read |
| /repeat\_attempts/:report\_id | GET | reports:read |
| /reports | GET | reports:read |
| /reports/:id | GET | reports:read |
| /reports/:id/cancel | POST | reports:write |
| /reports/:id/resume | POST | reports:write |
| /sdk\_token | POST | applicants:write |
| /watchlist\_monitors | GET | monitors:read |
| /watchlist\_monitors | POST | monitors:write |
| /watchlist\_monitors/:id | GET | monitors:read |
| /watchlist\_monitors/:id | DELETE | monitors:delete |
| /watchlist\_monitors/:id/matches | GET | monitors:read |
| /watchlist\_monitors/:id/matches | PATCH | monitors:write |
| /watchlist\_monitors/:id/new\_report | POST | monitors:write |
| /webhooks | GET | webhooks:read |
| /webhooks | POST | webhooks:write |
| /webhooks/:id | DELETE | webhooks:delete |
| /webhooks/:id | GET | webhooks:read |
| /webhooks/:id | PUT | webhooks:write |
| /webhooks/resend | POST | webhooks:write |
| /workflow\_runs | GET | workflows:read |
| /workflow\_runs | POST | workflows:write |
| /workflow\_runs/:id | GET | workflows:read |
| /workflow\_runs/:id/evidence\_folder | GET | workflows:read |
| /workflow\_runs/:id/evidence\_summary\_file | GET | workflows:read |
| /workflow\_runs/:id/signed\_evidence\_file | GET | workflows:read |
| /workflow\_runs/:id/tasks | GET | workflows:read |
| /workflow\_runs/:id/tasks/:task\_id | GET | workflows:read |
| /workflow\_runs/:id/tasks/:task\_id/complete | POST | workflows:write |
| /workflow\_runs/:id/timeline\_file | POST | workflows:write |
| /workflow\_runs/:id/timeline\_file/:file\_id | GET | workflows:read |
| /workflows/:id/versions/:version\_id | GET | workflows:read |
# Responsible Disclosure
## Responsible Disclosure Policy
Security is a top priority for Entrust and we value the work done by researchers in improving the security of our products and services. We encourage responsible vulnerability research and disclosure and if you discover a vulnerability in any of our systems, please let us know about it so we can address it as quickly as possible.
We are committed to working with the community to verify, reproduce, and respond to all the submissions in a timely manner.
Our full policy can be found at the following URLs:
* [https://www.entrust.com/legal-compliance/security/onfido-responsible-disclosure/](https://www.entrust.com/legal-compliance/security/onfido-responsible-disclosure/)
* [https://vdp.onfido.com/](https://vdp.onfido.com/)
### Reporting a Vulnerability
If you believe you’ve discovered a security vulnerability, please let us know by submitting a report at [https://vdp.onfido.com/p/Send-a-report](https://vdp.onfido.com/p/Send-a-report) or via email at [responsibledisclosure@entrust.com](mailto:responsibledisclosure@entrust.com).
Entrust highly appreciates the efforts made by the reporting party in identifying the vulnerability or error. Reporting of such vulnerabilities and errors will contribute to improving the security and reliability of our product and services.
### Bug Bounty
Entrust currently operates a private bug bounty on the YesWeHack platform. If you want to actively participate in the program, please let us know and contact us at [bugbounty@entrust.com](mailto:bugbounty@entrust.com).
You can find more information [here](https://www.entrust.com/legal-compliance/security/).
### Contact
Please submit any vulnerability reports at [https://vdp.onfido.com/p/Send-a-report](https://vdp.onfido.com/p/Send-a-report). If you aren’t sure whether a system or an issue is in scope or not, contact us at [bugbounty@entrust.com](mailto:bugbounty@entrust.com).