Quick Start

Welcome

Let's get you set up on the world's leading identity verification engine so that you can onboard users ASAP.

Our Quick Starts are designed to get you started running verification checks via the API swiftly and easily.

If you're looking for ways to customize your workflow, you may want to check out the API Reference Guide for more detailed information.

If you want to find out more about seamless integration with our mobile SDKs then head over to mobile SDKs.

If you have access to the client Dashboard, check out the step-by-step integration guide.

Overview

Diagrammatic Overview

The Onfido API allows you to submit verification checks programmatically. The API is built using RESTful endpoints and standard HTTP verbs.

All Standard checks have a workflow involving a form sent to the applicant to complete.

All Express checks have the following basic workflow.

1) An Applicant is created.

2) Documents and images are uploaded to the Applicant object (if required).

3) A Check is constructed consisting of one or more Reports.

Key Concepts

Let's get you familiar with the relevant terminology to help you perform checks smoothly.

Applicant

An applicant is the individual the check is being performed on.

Check

A check is a request to carry out one or more reports on an applicant. For example, a customer can perform a check containing a Document Report and a Facial Similarity Report.

A check is a container for single or multiple reports.

A check has two types that specify how reports are performed: Standard or Express.

Standard Check

A standard check sends an email to an applicant with a link to a form. The Applicant then completes the form with their information.

Express Check

An express check involves submitting all the applicant's information up-front via the API.

Report

A report is a single verification request - for example a Document Report. A report cannot exist without a check to contain it.

Asynchronous Reports

Report results can arrive at different times (described as asynchronous).

When some reports are delayed, this can hold up completion of a check. Webhooks should be set up for notifications of check and/or report progress.

Variants

A variant is a version of a report - similar to ice cream having different flavors. An example is - a Facial Similarity Report that can have a 'Standard' (Photo) or 'Video' variant.

Authentication

You will need an account with Onfido to gain access to the API.

1) Get an account

Contact our sales team to get the right account for you. Once you've completed this, you have access to the Onfido Dashboard.

2) Access the Dashboard

Log in to your account to view the Onfido Dashboard.

3) Get API tokens

There are two types of tokens: Sandbox Tokens for testing and Live Tokens to generate live requests.

Sandbox Token

It is easy to generate sandbox tokens from the Dashboard.

  1. Select 'API' from the main menu.
  2. Click 'Generate Sandbox Tokens'.

Use the sandbox token to test before going live. Sandbox requests return dummy responses and incur no charge.

Make sure you are using the correct token. All sandbox tokens start with the prefix "test_".

Rate limits with API requests

For sandbox requests, there is currently a rate limit of 30 requests per minute. When you hit the limit, you will see an HTTP 429 - too many requests error. You are prevented from making further sandbox requests within the one-minute time period.

Live Token

If you haven't already got one, contact our friendly sales team to obtain a live token. This will involve updating your account with current billing information.

Typically, live tokens are issued after completion and verification of integration testing.

Make sure you are using the correct token. A live token starts with the prefix "live_".

Token expiration times

A live token only expires if your account closes.

Authentication error messages

An issue with authentication is indicated by an HTTP 401 - Authorization error.

This can occur for the following reasons:

  • API token not included in the header.
  • Request made over HTTP instead of HTTPS.
  • Request not made using TLS 1.2 or above.

Region

In this guide, we talk about our API endpoint https://api.onfido.com/.

However, if you want your check data to be stored at rest exclusively in a particular region, then you must instead use a region-specific endpoint. See how to choose your region.

Getting Started

You are about to perform an Express Check composed of a Document Report and a Facial Similarity Report - standard variant (Photo).

This is a robust verification workflow that:

1) Ensures an applicant's identity document is genuine.

2) Compares the photo on the identity document with an applicant's recent photo to ensure it is the same person on both.

3) Verifies that the photo is genuine and not for example a photo of another photo or a screen.

Overview of steps

Face Check Doc Photo Diagram

1) Create an applicant.

2) Upload an applicant's identity document.

3) Upload an applicant's photo.

4) Set up a webhook if required.

5) Submit the Express Check - Document Report and Facial Similarity Report.

6) Onfido conducts the check and returns the results.

7) View results.

You will need:

  • An API token

    Log in to the Onfido Dashboard to get your API token.

    NOTE: A sandbox token begins with test and the live token begins with live.

    NOTE: Enter your own data where you see "< >"

Create an Applicant

1. To create a new applicant:

POST https://api.onfido.com/v2/applicants/

2. Include your API token in the Authorization header:

Authorization: Token token=<YOUR_API_TOKEN>

3. Specify the applicant's first name and last name in the body of the request as follows.

ParametersValueNotes
first_nameapplicant's forenamenone
last_nameapplicant's surnamenone
  • If you don't have an applicant's name, it is possible to enter dummy values and create an Applicant ID.

4. Submit your request.

Example Request 1 - Creating a new applicant called 'Paddington Bear'

curl https://api.onfido.com/v2/applicants \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -d 'first_name=Paddington' \
  -d 'last_name=Bear'

Response

After submitting a request, a typical response is shown below.

NOTE: The response includes additional fields that were not requested.

Example Response

{
  "id": "<APPLICANT_UUID>",
  //This is your Applicant ID. You will need this to perform checks on this applicant.
  "created_at": "2018-07-20T10:50:33Z",
  "sandbox": false,
  "title": null,
  "first_name": "Paddington",
  "middle_name": null,
  "last_name": "Bear",
  "email": null,
  "gender": null,
  "dob": null,
  "telephone": null,
  "mobile": null,
  "nationality": null,
  "country": "gbr",
  // The country field refers to the jurisdiction where we will perform the check.
  "href": "/v2/applicants/<APPLICANT_UUID>",
  //This is the URI of the applicant request.
  "mothers_maiden_name": null,
  "country_of_birth": null,
  "town_of_birth": null,
  "previous_last_name": null,
  "id_numbers": [],
  "addresses": []
}

You have now created an applicant and have an Applicant ID. You can now upload an Identity document.

Upload an ID document

You will need:

  • An image file (or files) of the Identity document in JPEG, PNG or PDF format.

    For best results, this should be a clear image without blur or glare.

  • One file for each side of the Identity document (if required in the table below)

  • A supported document. (If unsure, check the country specific full list of supported identity documents)

  • An accepted identity document
CountryNameTypeBoth sides required?
AllPassportpassportNo

EU and EFTA statesNational Identity Cardnational_identity_cardYes

CANDriving Licencedriving_licenceYes

CHNHong Kong Identity Cardnational_identity_cardNo

GBRDriving Licencedriving_licenceNo

GBRBiometric Residence Permituk_biometric_residence_permitYes

INDAadhaarnational_identity_cardNo

INDPANtax_idNo

MEXINEvoter_idYes

USADriving Licensedriving_licenceNo

1. To submit a new Identity document request:

POST https://api.onfido.com/v2/applicants/<APPLICANT ID>/documents

NOTE: The Applicant ID is specified in the URI.

2. Include your API token in the Authorization header:

Authorization: Token token=<YOUR_API_TOKEN>

3. Set the file location, file type and document side as follows:

ParametersValueNotes
fileThe file to upload e.g. path/to/document.png-
typeThe type of document e.g. driving_licenceSee above table. Specify "unknown" if you are unsure of the document type and we will try to identify it.
sideSpecify 'front' or 'back' (of the document) e.g. frontThis is required.

4. Submit the request.

Example Request 1 - UK Driving Licence (only one side necessary)

curl https://api.onfido.com/v2/applicants/<APPLICANT_ID>/documents \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -F 'file=@path/to/document.png;type=image/png' \
  -F 'type=driving_licence' \
  -F 'side=front'

Response

Example Response 1 - Completed

{
  "id": "<DOCUMENT_ID>",
  "created_at": "2018-07-20T13:45:28Z",
  "file_name": "document.png",
  "file_type": "jpg",
  "file_size": 706584,
  "type": "driving_licence",
  "side": "front",
  "issuing_country": null,
  "href": "/v2/applicants/<APPLICANT_ID>/documents/<DOCUMENT_ID>",
  "download_href":"/v2/applicants/<APPLICANT_ID>/documents/<DOCUMENT_ID>/download"
}

You have now successfully uploaded an identity document.

Upload a photo

You will need:

  • A photo of the applicant in JPEG or PNG format.

    For best results, this should be an immediately captured 'selfie' of the applicant - without blur or glare.

1. To submit a new photo request

POST https://api.onfido.com/v2/live_photos

2. Include your API token in the Authorization header.

Authorization: Token token=<YOUR_API_TOKEN>

3. Set the file location and Applicant ID as follows:

ParametersValueNotes
fileThe file to upload e.g. path/to/photo.png-
applicant_idEnter the <APPLICANT_ID>-

Live photos are automatically validated at the point of upload to ensure best results. If you wish to disable this setting, you can do so by setting the argument to false:

ParametersValueNotes
advanced_validationFalse-

4. Submit the request.

The following is an example request:

Example Request 1 - Valid photo

curl https://api.onfido.com/v2/live_photos \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -F 'applicant_id=<APPLICANT_ID>' \
  -F 'file=@path/to/photo.png;type=image/png'

Response

Following upload of a valid photo:

Example Response 1 - Successful upload

{
  "id": "<LIVE_PHOTO_ID>",
  "created_at": "2018-07-23T08:37:32Z",
  "file_name": "photo.png",
  "file_type": "image/png",
  "file_size": 196437,
  "href": "/v2/live_photos/<LIVE_PHOTO_ID>",
  "download_href": "/v2/live_photos/<LIVE_PHOTO_ID>/download"
}

You have now successfully uploaded a photo and can proceed to submit the check.

Set up a webhook

You will need:

  • A webhook url

NOTE: You can create a temporary endpoint URL easily using free hosted services.

Set up your webhook as follows:

1. Create a POST request to the following URI:

POST https://api.onfido.com/v2/webhooks

2. Include your API token in the Authorization header:

Authorization: Token token=<YOUR_API_TOKEN>

NOTE: Enter your own data where you see "< >"

3. Next, set the url that will listen to notifications as follows:

ParametersValueNotes
urle.g. https://webhookendpoint.urlThe url that will listen to notifications (must be https)

4. Submit the request

Example request - Setting up a webhook

curl https://api.onfido.com/v2/webhooks \
  -H "Authorization: Token token=<YOUR_API_TOKEN>" \
  -d 'url=https://webhookendpoint.url'

Response

Following a webhook request:

Example Response

{
  "id": "<WEBHOOK_ID>",
  "url": "https://webhookendpoint.url",
  "enabled": true,
  "token": "<WEBHOOK_SECRET_TOKEN>",
  "environments": [
    "live",
    "sandbox"
  ],
  "href": "/v2/webhooks?id=<WEBHOOK_ID>",
  "events": [
    "report.completed",
    "report.withdrawn",
    "report.resumed",
    "report.cancelled",
    "report.awaiting_approval",
    "report.initial_result_received",
    "report.initiated",
    "check.started",
    "check.completed",
    "check.form_completed",
    "check.form_opened",
    "check.reopened",
    "check.withdrawn"
  ]
}

5. After receiving a webhook notification, be sure to acknowledge success by responding with an HTTP 20x response. (Otherwise, a notification is resent up to 4 times over next 12 hours.)

Submit the check

You are now going to submit an Express Check composed of a Document Report and a Facial Similarity Report.

1. To submit a new check request:

POST https://api.onfido.com/v2/applicants/<APPLICANT_ID>/checks

2. Include your API token in the Authorization header:

Authorization: Token token=<YOUR_API_TOKEN>

3. Next, set your parameters as follows:

ParameterValueNotes
typeexpressThis refers to an up-front check
reportsdocumentThese are the reports you are requesting.
facial_similarity
variantstandardThis is the name for the 'Photo' variant. (Another variant is 'Video')
asynctrueSee explanation below

NOTE: To retrieve all your report results at the same time, add the async=true parameter to your POST request. (No reports are returned immediately).

4. If you have set up a webhook, you can retrieve individual results upon notification.

5. Submit your request.

The following are examples of express facial similarity checks.

Example Request 1

curl https://api.onfido.com/v2/applicants/<APPLICANT_ID>/checks \
  -H "Authorization: Token token=<YOUR_API_TOKEN>" \
  -d 'type=express' \
  -d 'reports[][name]=document' \
  -d 'reports[][name]=facial_similarity' \
  -d 'reports[][variant]=standard' \
  -d 'async=true'

To see an example of a successful check response. See View Results.

Conclusion

You have now completed a Check composed of a Document Report and a Facial Similarity (photo) Report.

View Results

Results have an overall result for the check as well as individual results for each report.

Check result

If all the reports have passed verification, the check result is clear result:clear

If one or some reports have failed to pass verification, the check result is consider result:consider

Report results

If an individual report has passed, the result is clear result:clear If the report has failed to pass verification, the result is consider result:consider

Report sub results:

The document report and facial similarity report are composed of additional verifications viewable as sub results.

Below is a detailed breakdown of an example response - including all results and sub results.

Example Response 1 - Completed

{
  "id": "<CHECK_ID>",
  "created_at": "2018-07-26T14:02:43Z",
  "status": "complete",
  "redirect_uri": null,
  "type": "express",
  "result": "clear",
}
  //This is the overall check result.
  //`clear` indicates that all the reports have passed verification.
  //If one or some reports have failed to pass verification,
  //the check result is `consider`.
  //The following section is the response for the **Facial Similarity Report**.
{
  "id": "<REPORT_ID>",
  "created_at": "2018-07-26T14:02:43Z",
  "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
  "name": "facial_similarity",
  "properties": {
    "score": "0.75"
  },

  //The `score` is the face comparison score.
  //This is between 0 and 1 and is a measure of
  //how similar the two faces are (where 1 is a perfect match.)

  "result": "clear",

  //The result is `clear` meaning that all
  //the facial similarity verifications have passed.

  "status": "complete",
  "sub_result": "clear",
  "variant": "standard",
  "breakdown": {
    "face_comparison": {
      "result": "clear"
    },
    "image_integrity": {
      "result": "clear"
    },
    "visual_authenticity": {
      "result": "clear"
    }
  }
  //The face comparison sub report is `clear`.
  //The result `consider` appears if the sub report has not
  //passed the verification.
  //The result `fail` may appear for ‘image integrity’
  //if the input image could not be processed.
  //`Visual authenticity` is `clear` indicating that the photo is not a //spoof.
}

More detailed information about the Facial Similarity Report can be found in the API Reference

The following section is an extract of a response for the Document Report.

{
  "created_at": "2018-07-26T14:02:43Z",
  "href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
  "id": "<REPORT_ID>",
  "name": "document",
  "properties": {
    "nationality": "",
    "last_name": "Bear",
    "issuing_country": "GBR",
    "gender": "",
    "first_name": "Paddington",
    "document_type": "driving_licence",
    "document_numbers": [
      {
        "value": "9999999999",
        "type": "document_number"
      }
    ],
    "date_of_expiry": "1900-01-01",
    "date_of_birth": "1900-01-01"
  }
}

Data extracted from the document through OCR is returned in the properties attribute.

View a full breakdown and more detailed information about the Document Report in the API Reference

Retrieve Checks or Reports

When performing a check, some results may appear immediately, whilst others may arrive at different times.

View a check

You can view a check status and result instantly in JSON format via the API. This will show the status and results for the individual reports as well.

If you have set up webhooks, a notification is sent upon completion of a check and/or report (depending what you specified).

To view an earlier check via the API:

GET https://api.onfido.com/v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID>

Example Request:

curl https://api.onfido.com/v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID> \
  -H "Authorization: Token token=<YOUR_API_TOKEN>"

You will get response objects that look like this:

Example Retrieve Check

{
  "id": "<CHECK_ID>",
  "created_at": "2017-03-10T18:10:16Z",
  "status": "complete",
  "redirect_uri": null,
  "type": "express",
  "result": "clear",
  "sandbox": true,
  "report_type_groups": [
    "1234"
  ],
  "tags": [],
  "results_uri": "https://onfido.com/dashboard/information_requests/12345",
  "download_uri": "https://onfido.com/dashboard/pdf/information_requests/12345",
  "form_uri": null,
  "href": "/v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID>",
  "reports": [
    <DOCUMENT_REPORT_ID>,
    <FACIAL_SIMILARITY_REPORT_ID>
  ],
  "paused": false,
  "version": "2.0"
}

More detailed information about Retrieving Checks can be found in the API Reference.

More information about Retrieving Reports can also be found in the API Reference.

Getting Started

You are about to perform an Express Check composed of a Document Report and a Facial Similarity Report - video variant.

This check requires integration with an Onfido SDK. The SDK captures images and/or video of an applicant performing multiple challenges. These include reading aloud randomly generated 3 digit sequences, and performing simple head movements.

The SDK does not perform the check.

This is a highly robust verification workflow to ensure safe on-boarding. It does the following:

1) Ensures an applicant's identity document is genuine.

2) Compares an applicant's identity document photo with an applicant's video to ensure it is the same person on both.

3) Ensures the applicant is a live person and not a spoof e.g. video of someone else or person wearing a mask.

Overview of steps

Face Check Doc Video Diagram

0) Set up a webhook.

1) Create an applicant (via the back-end).

2) Pass the 'Applicant ID' to SDK Configuration.

3) Applicant uploads document and performs video challenges via the SDK.

4) Submit the Express Check - Document Report and Facial Similarity Report (via the back-end).

5) Onfido conducts the check and returns the results.

6) View results.

You will need:

NOTE: A sandbox token begins with test and the live token begins with live.

NOTE: Enter your own data where you see "< >"

Prerequisites

In order to perform a check, ensure that you have completed the following steps:

1. Added the SDK dependency for Android or iOS.

2. Configured the SDK using your Mobile SDK Token.

Set up a webhook

You will need:

  • A webhook url

NOTE: To perform initial testing, a temporary endpoint URL can be created easily using free hosted services.

Set up your webhook as follows:

1. Create a POST request to the following URI:

POST https://api.onfido.com/v2/webhooks

2. Include your API token in the Authorization header:

Authorization: Token token=<YOUR_API_TOKEN>

NOTE: Enter your own data where you see "< >"

3. Next, set the url that will listen to notifications as follows:

ParametersValueNotes
urle.g. https://webhookendpoint.urlThe url that will listen to notifications (must be https)

4. Submit the request

Example request - Setting up a webhook

curl -X POST \
  https://api.onfido.com/v2/webhooks \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -F url='https://webhookendpoint.url'

Response

Following a webhook request:

Example Response

{
  "id": "<WEBHOOK_ID>",
  "url": "https://webhookendpoint.url",
  "enabled": true,
  "token": "<WEBHOOK_SECRET_TOKEN>",
  "environments": ["live", "sandbox"],
  "href": "/v2/webhooks?id=<WEBHOOK_ID>",
  "events": [
    "check.completed",
  ]
}

5. After receiving a webhook notification, be sure to acknowledge success by responding with an HTTP 20x response. (Otherwise, a notification is resent up to 4 times over next 12 hours.)

Create an Applicant

1. To create a new applicant:

POST https://api.onfido.com/v2/applicants/

2. Include your API token in the Authorization header:

Authorization: Token token=<YOUR_API_TOKEN>

3. Specify the applicant's first name and last name in the body of the request as follows.

ParametersValueNotes
first_nameapplicant's forename e.g. Paddingtonnone
last_nameapplicant's surname e.g. Bearnone
  • If you don't have an applicant's name, it is possible to enter dummy values and create an applicant.

4. Submit your request.

Example Request - Creating a new applicant called 'Paddington Bear'

curl https://api.onfido.com/v2/applicants \
  -H 'Authorization: Token token=<YOUR_API_TOKEN>' \
  -d 'first_name=Paddington' \
  -d 'last_name=Bear'

Response

After submitting a request, a typical response is shown below.

NOTE: The response includes additional fields that were not requested.

Example Response

{
  "id": "<APPLICANT_UUID>",
  //This is your Applicant ID. You will need this to perform checks on this applicant.
  "created_at": "2018-07-20T10:50:33Z",
  "sandbox": false,
  "title": null,
  "first_name": "Paddington",
  "middle_name": null,
  "last_name": "Bear",
  "email": null,
  "gender": null,
  "dob": null,
  "telephone": null,
  "mobile": null,
  "nationality": null,
  "country": "gbr",
  // The country field refers to the jurisdiction where we will perform the check.
  "href": "/v2/applicants/<APPLICANT_UUID>",
  //This is the URI of the applicant request.
  "mothers_maiden_name": null,
  "country_of_birth": null,
  "town_of_birth": null,
  "previous_last_name": null,
  "id_numbers": [],
  "addresses": []
}

You have now created an applicant and have an Applicant ID to pass to the SDK Configuration.

SDK Configuration

For the applicant to upload an ID document and/or a video.

1. Pass the Applicant ID to configure the SDK.

2. Start the SDK flow (to enable capture of document image and video from the applicant).

Submit the check

You are now going to submit an Express Check composed of a Document Report and a Facial Similarity Report (video)

Prerequisites

You should have:

1. Completed testing of the SDK Configuration.

2. Run a successful capture of an ID document image and face video.

Create a check

  • The SDK does not create checks automatically. You therefore need to call your own back-end logic to create a check once a user has completed the SDK flow.

Perform a check via the Onfido API

From your back-end, you can create a check via the Onfido API as follows:

1. To submit a new check request:

2. Include your API token in the Authorization header.

Authorization: Token token=<YOUR_API_TOKEN>

3. Next, set your parameters as follows:

ParameterValueNotes
typeexpressThis refers to an up-front check
reportsdocumentThese are the reports you are requesting.
facial_similarity
variantvideoThis is the name for the 'Video' variant (Another variant is 'Photo')
asynctruesee explanation below

NOTE: To retrieve all your report results at the same time, add the async=true parameter to your POST request. (No reports are returned immediately).

4. If you have set up a webhook, you can retrieve individual results upon notification.

5. Submit your request.

The following are examples of express facial similarity checks.

Example Request

curl https://api.onfido.com/v2/applicants/<APPLICANT_ID>/checks \
  -H "Authorization: Token token=<YOUR_API_TOKEN>" \
  -d 'type=express' \
  -d 'reports[][name]=document' \
  -d 'reports[][name]=facial_similarity' \
  -d 'reports[][variant]=video' \
  -d 'async=true'

To see an example of a successful check response see View Results.

Conclusion

You have now completed a check composed of a Document Report and a Facial Similarity (video) Report.

NOTE: A full integration would typically involve configuring a callback inside the SDK to create checks via your back-end once a user has completed the SDK flow. For details check out the SDK information below:

View Results

Results have an overall result for the check as well as individual results for each report.

Check result

If all the reports have passed verification, the check result is clear result:clear

If one or some reports have failed to pass verification, the check result is consider result:consider

Report results

If an individual report has passed, the result is clear result:clear If the report has failed to pass verification, the result is consider result:consider

Report sub results:

The document report and facial similarity report are composed of additional verifications viewable as sub results.

Below is a detailed breakdown of an example response - including all results and sub results.

Example Response - Completed

{
"id": "<CHECK_ID>",    
"created_at": "2018-07-26T14:02:43Z",
"status": "complete",
"redirect_uri": null,
"type": "express",
"result": "clear",
}
//This is the overall check result.
//`clear` indicates that all the reports have passed verification.
//If one or some reports have failed to pass verification,
//the check result is `consider`.
//The following section is the response for the **Facial Similarity Report**.

```json
"id": "<REPORT_ID>",
"created_at": "2018-07-26T14:02:43Z",
"href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
"name": "facial_similarity",
"properties": {
  "score": "0.75"
},

//The `score` is the face comparison score.
//This is between 0 and 1 and is a measure of
//how similar the two faces are (where 1 is a perfect match.)

"result": "clear",

//The result is `clear` meaning that all
//the facial similarity verifications have passed.

"status": "complete",
"sub_result": clear,
"variant": "video",
"breakdown": {
  "visual_authenticity": {
    "result": "clear",
    "breakdown": {
      "spoofing_detection": {
        "result": "clear",
        "properties": {}
      },
      "liveness_detected": {
        "result": "clear",
        "properties": {}
      }
    }
  }
}
//The `visual_authenticity` result is `clear` and
//`spoofing_detection` is `clear` meaning that the
//live video has no spoofing indicators
//(such as photos of printed photos or photos of
//digital screens).
//The `liveness_detected` result is also `clear`
//meaning that the numbers and head movements were
//correctly executed by the applicant.

"breakdown": {
  "face_comparison": {
    "result": "clear"
  },
  "image_integrity": {
    "result": "clear"
  }  
}
//The face comparison report is `clear`.
//The result `consider` appears if this verification
//has not passed.
//The result `fail` may appear for ‘image integrity’
//if the input image could not be processed.

More detailed information about the Facial Similarity Report can be found in the API Reference

The following section is the response for the Document Report.

Results have an overall result for the check as well as individual results for each report.

Check result

If all the reports have passed verification, the check result is clear result:clear

If one or some reports have failed to pass verification, the check result is consider result:consider

Report results

If an individual report has passed, the result is clear result:clear If the report has failed to pass verification, the result is consider result:consider

Report sub results:

The document report and facial similarity report are composed of additional verifications viewable as sub results.

Below is a detailed breakdown of an example response - including all results and sub results.

Example Response - Completed

{
"id": "<CHECK_ID>",    
"created_at": "2018-07-26T14:02:43Z",
"status": "complete",
"redirect_uri": null,
"type": "express",
"result": "clear",
}
//This is the overall check result.
//`clear` indicates that all the reports have passed verification.
//If one or some reports have failed to pass verification,
//the check result is `consider`.
//The following section is the response for the **Facial Similarity Report**.

```json
"id": "<REPORT_ID>",
"created_at": "2018-07-26T14:02:43Z",
"href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
"name": "facial_similarity",
"properties": {
  "score": "0.75"
},

//The `score` is the face comparison score.
//This is between 0 and 1 and is a measure of
//how similar the two faces are (where 1 is a perfect match.)

"result": "clear",

//The result is `clear` meaning that all
//the facial similarity verifications have passed.

"status": "complete",
"sub_result": clear,
"variant": "video",
"breakdown": {
  "visual_authenticity": {
    "result": "clear",
    "breakdown": {
      "spoofing_detection": {
        "result": "clear",
        "properties": {}
      },
      "liveness_detected": {
        "result": "clear",
        "properties": {}
      }
    }
  }
}
//The `visual_authenticity` result is `clear` and
//`spoofing_detection` is `clear` meaning that the
//live video has no spoofing indicators
//(such as photos of printed photos or photos of
//digital screens).
//The `liveness_detected` result is also `clear`
//meaning that the numbers and head movements were
//correctly executed by the applicant.

"breakdown": {
  "face_comparison": {
    "result": "clear"
  },
  "image_integrity": {
    "result": "clear"
  }  
}
//The face comparison report is `clear`.
//The result `consider` appears if this verification
//has not passed.
//The result `fail` may appear for ‘image integrity’
//if the input image could not be processed.

More detailed information about the Facial Similarity Report can be found in the API Reference

The following section is the response for the Document Report.

"created_at": "2018-07-26T14:02:43Z",
"href": "/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
"id": "<REPORT_ID>",
"name": "document",
"properties": {
  "nationality": "",
  "last_name": "Bear",
  "issuing_country": "GBR",
  "gender": "",
  "first_name": "Paddington",
  "document_type": "passport",
  "document_numbers": [
    {
      "value": "9999999999",
      "type": "passport"
    }
  ],
  "date_of_expiry": "1900-01-01",
  "date_of_birth": "1900-01-01"
},
//Data extracted from the document through OCR is
//returned in the `properties` attribute.

//More detailed information about the Document Report
//can be found in the [API Reference](https://documentation.onfido.com/#document-report)

Retrieve Checks or Results

When performing a check, some results may appear immediately, whilst others may arrive at different times.

View a check

You can view a check status and result in JSON format via the API. This will show the status and results for the individual reports as well.

If you have set up webhooks, a notification is sent upon completion of a check and/or report (depending what you specified).

To view an earlier check via the API:

GET https://api.onfido.com/v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID> 

Example Request:

curl https://api.onfido.com/v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID> \
  -H "Authorization: Token token=<YOUR_API_TOKEN>"

You will get response objects that look like this:

Example Retrieve Check

{
  "id": "<CHECK_ID>",
  "created_at": "2017-03-10T18:10:16Z",
  "status": "complete",
  "redirect_uri": null,
  "type": "express",
  "result": "clear",
  "sandbox": true,
  "report_type_groups": [
    "1234"
  ],
  "tags": [],
  "results_uri": "https://onfido.com/dashboard/information_requests/12345",
  "download_uri": "https://onfido.com/dashboard/pdf/information_requests/12345",
  "form_uri": null,
  "href": "/v2/applicants/<APPLICANT_ID>/checks/<CHECK_ID>",
  "reports": [
    <DOCUMENT_REPORT_ID>,
    <FACIAL_SIMILARITY_REPORT_ID>
  ],
  "paused": false,
  "version": "2.0"
}

More detailed information about Retrieving Checks can be found in the API Reference.

More information about Retrieving Reports can also be found in the API Reference.