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

To test only 'consider' report responses:

1. Create an applicant which has the last name "Consider"
2. Create a check with this applicant

All reports specified in check creation will return a consider report result. If you use any other applicant last name, the result will be clear.

Different reports have different minimum requirements for applicant data (even in the sandbox).

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

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.

Breakdowns and sub-breakdowns

You can trigger 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 breakdown - sub-breakdown combinations:

1. Create an applicant which has the first_name as the "breakdown - sub-breakdown" combination you intend to trigger.

Sandbox supports the following options:

• "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"

2. Create a check with this applicant.

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. These responses show a Document report response including the specific properties for the associated document type.

To test different document types:

1. Create an applicant which has the last_name as the document type you intend to test.

Sandbox supports the following 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.

2. Create a check with this applicant.

Sub-results

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

To do this:

1. Create an applicant which has the last_name as one of the following strings:

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

2. Create a check with this applicant.

Breakdowns and sub-breakdowns

You can trigger 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 breakdown - sub-breakdown combinations:

1. Create an applicant which has the first_name as the "breakdown - sub-breakdown" combination you intend to trigger.

Sandbox supports the following options:

• "Visual Authenticity - Spoofing Detection"
• "Face Comparison - Face Match"
• "Image Integrity - Source Integrity"
• "Image Integrity - Face Detected"

2. Create a check with this applicant.

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

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.

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

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.3/applicants?page=3059](https://api.eu.onfido.com/v3.3/applicants?page=3059); rel="last", [https://api.eu.onfido.com/v3.3/applicants?page=2](https://api.eu.onfido.com/v3.3/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

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.

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

Delete monitor

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.

List matches (BETA)

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.

1HTTP/1.1 200 Success
2Content-Type: application/json
3
4{
5  "matches": [
6    {
7      "id": <MATCH_ID>,
8      "enabled": true
9    },
10    {
11      "id": <MATCH_ID>,
12      "enabled": false
13    },
14    ...
15  ]
16}

Set match status (BETA)

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

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)

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.

1HTTP/1.1 201 Created
2Content-Type: application/json
3Location: "/api/v3.3/checks/<CHECK_ID>"

Document report: Object

We host a separate page which contains a detailed description of the Document report object values from an API user's perspective.

Results

The result field indicates the overall report result. Possible values for Document reports are clear and 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:

Document report: 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, 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.

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.

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

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 ¹
• expiry_date ²
• mrz
• barcode

1. If this is flagged, the document has expired. Onfido 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 18 years. Configurable to set a different minimum age value. Onfido 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 colour 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¹
• 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.

compromised_document:

Asserts whether the image of the document has been found in our internal database of compromised documents.

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.

1. You can configure your account to always trigger Visual Document Verification if nfc_active_authentication is returned as null (even if nfc_passive_authentication is clear). In this case, the visual authentication, image integrity and data consistency checks will be performed and the results returned in the breakdowns.

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

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