Token authentication

The Onfido API uses token-based authentication. API 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 Onfido Dashboard.

You can make requests using sandbox tokens to test our API before you go live.

Pre-determined 'consider' results

Pre-determined responses can be generated by modifying the first_name and last_name parameters of the applicant object.

Using the 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 for an active workflow 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 returned in the Workflow Run API payload, 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 endpoint.

Breakdowns and sub-breakdowns

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 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.

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 and set the last_name parameter to the document type you intend to test.

The sandbox supports the following document type options:

* 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.

Sub-results

You can trigger responses for particular sub-results for sandbox Document reports, showing possible individual breakdown results which can lead to different sub-results.

To do this, create an applicant and set the last_name parameter to one of the following strings:

• "clear"
• "rejected"
• "suspected"
• "caution"

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.

Breakdowns and sub-breakdowns

You can trigger pre-determined responses for particular breakdowns and sub-breakdowns 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 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.

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 four possible keywords as the report_uuid in the request URL:

• match
• mismatch
• error
• empty

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 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.

Rate limits

Onfido's 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).

Onfido uses the token bucket algorithm to handle usage.

Any request over the limit will return a 429 Too Many Requests error.

Onfido offers region-specific environments: EU, US, and Canada. You can use these to store the data in your Onfido account at rest within a specific geographic region.

Regions have unique base URLs and API token formats for both live and sandbox environments.

Example error object

Applicant object

ID number object

The ID number array of objects is nested inside the applicant object.

Address object

The applicant address object is nested inside the applicant object.

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 report. If you provide address data in this form, Onfido uses a third-party subprocessor for address cleansing.

Location object

The location object is nested inside the applicant object.

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, 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

Creates a single applicant. Returns an applicant object.

When you create an applicant, some characters are forbidden. You should remove any duplicate whitespaces before creating an applicant, otherwise this may result in a data comparison failure.

The minimum required (and recommended) applicant data depends on the type of report requested. For example, for Document reports.

Request body parameters

location

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.

1...
2"location": {
3        "ip_address": "127.0.0.1",
4        "country_of_residence": "GBR"
5    }
6...

You can also provide location information during document upload.

If you submit location information in multiple requests, the document upload location will take precedence.

consents

Where required, you must collect end user consent before creating a check with Onfido. If you do not, Onfido 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 parameter when creating an applicant or uploading a document.

• privacy_notices_read

End users located in the United States, must read the Privacy Notices and Terms of Service before giving consent for Onfido.

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 requests will fail with a validation error.

• ssn_verification

End users must give consent to process their Social Security Number (SSN) before you can submit an 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.

1...
2"consents": [
3         {
4            "name": "privacy_notices_read",
5            "granted": true
6        },
7        {
8            "name": "ssn_verification",
9            "granted": true
10        }
11    ]
12...

You can also provide consents when updating an applicant.

Retrieve applicant

Retrieves a single applicant. Returns an applicant object.

Update applicant

Updates an applicant's information. Returns the updated 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

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 Onfido's production object storage and relational database system after a deletion delay which can be configured by emailing our client support team. After deletion, applicant details cannot be recovered or queried, and Onfido will not be able to troubleshoot. Within the delay period, the applicant can be restored. For more information about Onfido's deletion service, see our Data Deletion FAQ.

Once deleted, Onfido 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

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

Lists all applicants you've created, sorted by creation date in descending order. Returns data in the form: {"applicants": [<LIST_OF_APPLICANT_OBJECTS>]}.

Requests to this endpoint will be paginated to 20 items by default.

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:

The custom X-Total-Count header gives the total resource count.

Document object

Upload document

Uploads a single document as part of a multipart request. Returns a document object.

We provide a sample document to test 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.

Request body parameters

location

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.

1...
2-F 'location[ip_address]=127.0.0.1' \
3-F 'location[country_of_residence]=GBR'
4...

You can also provide location information during applicant creation.

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.

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.

When the image fails validation, returns a 422 validation_error. There can be one or more failed image quality validations for a request. The list of reasons is provided in the fields property.

Sample images to trigger various error responses can be provided.

Retrieve document

Retrieves a single document. Returns a document object.

List documents

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": [<LIST_OF_DOCUMENT_OBJECTS>]}.

Query string parameters

applicant_id (required): the ID of the applicant ID whose documents you want to list.

Download document

Downloads specific documents belonging to an applicant. If successful, the response will be the binary data representing the image.

Path parameters

document_id (required): the unique identifier (UUID) of the document.

Download 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.

Download document video

Downloads a document video. If successful, the response will be the binary data representing the video.

Path parameters

document_id (required): the unique identifier (UUID) of the document.

Live photo object

Upload live photo

Uploads a live photo as part of a multipart request. Returns a live photo object.

We provide a sample photo to test 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.

Request body parameters

Retrieve live photo

Retrieves a single live photo. Returns a live photo object.

List live photos

Lists the live photos that belong to an applicant. Returns data in the form: {"live_photos": [<LIST_OF_LIVE_PHOTO_OBJECTS>]}.

Query string parameters

applicant_id (required): the ID of the applicant whose live photos you want to list.

Download live photo

Downloads a live photo. If successful, the response will be the binary data representing the image.

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.

Retrieve live video

Retrieves a single live video. Returns the corresponding live video object.

List live videos

Lists all the live videos that belong to an applicant.

Returns data in the form: {"live_videos": [<LIST_OF_LIVE_VIDEO_OBJECTS>]}.

Query string parameters

applicant_id (required): the ID of the applicant whose live videos you want to list.

Download live video

Downloads a live video. Returns the binary data representing the video.

Download live video 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.

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.

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.

Link object

Object for the configuration of the Workflow Run link.

Create Workflow Run

Creates and starts a Workflow Run. Returns a 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 your Studio via Onfido Dashboard. An Applicant ID is mandatory for creating a Workflow Run.
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
• Custom input data

Request body parameters

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 and update 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 Onfido Dashboard.

If Custom Input Data is configured, then it becomes mandatory when creating a Workflow Run.

Link object

Object for the configuration of the Workflow Run link.

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 Onfido's 44 supported languages and their relevant codes in our SDK customisation guide.

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

Retrieves the Workflow Runs of the client. Returns a list of Workflow Run objects. The page size is 20 objects.

Query String 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 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.

Retrieve Workflow Run

Retrieves a Workflow Run. Returns a Workflow Run object.

Path parameters

workflow_run_id (required): the unique identifier of the Workflow Run you want to retrieve.

Retrieve Workflow Run 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 for more information.

Note: If you invoke this endpoint for Sandbox workflow runs, a mock evidence summary file will be returned.

Path parameters

workflow_run_id (required): the unique identifier of the Workflow Run for which you want to retrieve the evidence summary file.

List Tasks

Retrieves the Tasks of a Workflow Run. Returns a subset of the Task object.

The response contains only Tasks that were already started or completed, ordered by the created_at field, in ascending order.

Path parameters

workflow_run_id (required): the unique identifier of the Workflow Run to which the Tasks belong.

Example response

1[
2  {
3    "id": "<TASK_ID>",
4    "task_def_id": "<TASK_DEF_ID>",
5    "workflow_run_id": "<WORKFLOW_RUN_ID>",
6    "created_at": "2022-06-28T15:39:42Z",
7    "updated_at": "2022-07-28T15:39:52Z",
8  },
9  {
10    "id": "<TASK_ID>",
11    "task_def_id": "<TASK_DEF_ID>",
12    "workflow_run_id": "<WORKFLOW_RUN_ID>",
13    "created_at": "2022-06-28T15:40:42Z",
14    "updated_at": "2022-07-28T15:40:52Z",
15  }
16  ...
17]

Retrieve Task

Retrieves a Task. Returns a Task object.

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 cancelled before it completed

Complete Task

Completes a Send / Receive Data 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

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.

Motion capture object

Retrieve motion capture

Retrieves a single motion capture. Returns the corresponding motion capture object.

List motion captures

Lists all the motion captures that belong to an applicant.

Returns data in the form: {"motion_captures": [<LIST_OF_MOTION_CAPTURE_OBJECTS>]}.

Query string parameters

applicant_id (required): the ID of the applicant whose motion captures you want to list.

Download motion capture

Downloads a motion capture. Returns the binary data representing the motion capture.

Download motion capture frame

Instead of the whole motion capture data, a single frame can be downloaded using this endpoint. Returns the binary data representing the frame.

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.

Monitor object

Create monitor

Creates a new 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

Retrieve monitor

Retrieves a single monitor. Returns a monitor object.

List monitors

Returns all available monitors for an applicant. Returns data in the form: {"monitors": [<LIST_OF_MONITOR_OBJECTS>]}.

Query string parameters