Quick Start

Welcome

Here you will find everything you need to start integrating with Onfido's solutions.

In this section you will find guidance on:

  • How to authenticate for API access
  • What the key objects are: Applicant, Check, and Reports.
  • How to get started building an integration

For our full API reference, including code examples, head over to the API documention or read more about our mobile SDKs. If you have access to the client Dashboard, check out the step-by-step integration guide.

Authentication

The API uses token-based authentication. You will be provided with a token which must be included in the header of all requests made to the API.

All API requests must be made over HTTPS. Any requests made over HTTP will fail.

There are 2 types of tokens:

1. Sandbox Token

  • You can generate sandbox tokens from the client Dashboard.
  • Requests made with the sandbox token can be used to test our API before going live. Sandbox requests will return dummy responses, and no credit will be deducted from your account.
  • To ensure that you are using a sandbox token, check that the token name starts with the prefix sandbox_ and that it is of type Test, and not Live.

2. Live Token

  • Live tokens are generally only issued after completion and verification of integration testing.
  • Requests made with the live token require current billing information in the client Dashboard.
  • To ensure that you are using a live token, check that the token name starts with the prefix live_ and that it is of type Live, and not Test.

Create an Applicant

Before you can start any checks, you need to create an applicant. More information on how to create an applicant can be found in the API documentation.

Collect the necessary applicant information for the reports you need. On submit, send a POST to https://api.onfido.com/v2/applicants with the required information in JSON format.

Example request:

$ curl https://api.onfido.com/v2/applicants \
  -H "Authorization: Token token=your_api_token" \
  -d 'title=Mr' \
  -d 'first_name=John' \
  -d 'last_name=Smith' \
  -d 'gender=male' \
  -d 'dob=2013-02-17' \
  -d 'telephone=02088909293' \
  -d 'country=GBR' \
  -d 'addresses[][building_number]=100' \
  -d 'addresses[][street]=Main Street' \
  -d 'addresses[][town]=London' \
  -d 'addresses[][postcode]=SW4 6EH' \
  -d 'addresses[][country]=GBR' \
  -d 'addresses[][start_date]=2013-08-10'

You will get a response object back that looks like:

Example Response from Create Applicant

{
  "id": "1030303-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "href": "/v2/applicants/1030303-123123-123123",
  "title": "Mr",
  "first_name": "John",
  "middle_name": null,
  "last_name": "Smith",
  "gender": "male",
  "dob": "2013-02-17",
  "telephone": "02088909293",
  "mobile": null,
  "country": "GBR",
  "mothers_maiden_name": null,
  "previous_last_name": null,
  "nationality": null,
  "country_of_birth": null,
  "town_of_birth": null,
  "id_numbers": [],
  "addresses": [
    {
      "flat_number": null,
      "building_number": "100",
      "building_name": null,
      "street": "Main Street",
      "sub_street": null,
      "town": "London",
      "state": null,
      "postcode": "SW4 6EH",
      "country": "GBR",
      "start_date": "2013-08-10",
      "end_date": null
    }
  ]
}

Applicant details can be updated between check creations.

Create a Check

A check is the containing body for reports, and is associated with an applicant. You can create more than one report per check.

Decide which report types you want to include in your check, and then POST to https://api.onfido.com/v2/applicants/{applicant_id}/checks with the required information in JSON format.

If you would like to request different sets of reports for different buckets of applicants, please contact client-support@onfido.com to set up report type groups. Certain reports are generated instantly and their results are returned in the response, while other reports take longer to be processed.

You will need to set up webhooks to listen for the results of non-instant reports. We will discuss webhooks more below. If you would rather retrieve the results of all your reports at a later time, add the async=true parameter to the POST request.

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 cancelled). You will receive an error message if you try to create a check for an applicant with an ongoing check.

Example request:

$ curl https://api.onfido.com/v2/applicants/1030303-123123-123123/checks \
  -H "Authorization: Token token=your_api_token" \
  -d 'type=standard' \
  -d 'reports[][name]=identity' \
  -d 'reports[][name]=criminal_history' \
  -d 'reports[][variant]=enhanced' \
  -d 'reports[][options][][name]=adults_barred_list' \
  -d 'criminal_history_report_details[job_role]=carer' \
  -d 'criminal_history_report_details[place_of_work]=care home' \
  -d 'tags[]=My tag' \
  -d 'tags[]=Another tag'

When you submit the request, you will get a response object that looks like:

Example Response from Create Check

{
  "id": "8546921-123123-123123",
  "created_at": "2014-05-23T13:50:33Z",
  "href": "/v2/applicants/1030303-123123-123123/checks/8546921-123123-123123",
  "type": "standard",
  "status": "awaiting_applicant",
  "result": null,
  "results_uri": "https://onfido.com/dashboard/information_requests/1234",
  "redirect_uri": null,
  "reports": [
    {
      "id": "6951786-123123-422221",
      "name": "identity",
      "created_at": "2014-05-23T13:50:33Z",
      "status": "awaiting_data",
      "result": null,
      "href": "/v2/checks/8546921-123123-123123/reports/6951786-123123-422221",
      "breakdown": {},
      "properties": {}
    },
    {
      "id": "6951786-123123-316712",
      "name": "document",
      "created_at": "2014-05-23T13:50:33Z",
      "status": "awaiting_data",
      "result": null,
      "href": "/v2/checks/8546921-123123-123123/reports/6951786-123123-316712",
      "breakdown": {},
      "properties": {}
    }
  ],
  "tags": [
    "My tag",
    "Another tag"
  ]
}

Retrieve Checks or Reports

Once you receive a notification from your webhook that your checks or reports are complete, you can use the id to retrieve the check or report associated with the event object.

To retrieve a check, send a GET request to https://api.onfido.com/v2/applicants/{applicant_id}/checks/{check_id}. A single check can be retrieved by calling this endpoint with the check's unique identifier. The reports object can also be expanded with the expand=reports request parameter.

Example Request:

$ curl https://api.onfido.com/v2/applicants/1030303-123123-123123/checks/8546921-123123-123123 \
  -H "Authorization: Token token=your_api_token"

You will get response objects that look like this:

Example Retrieve Check

{
  "id": "e4aa9d00-4968-4ca0-a8ae-bbc1914ee502",
  "created_at": "2017-03-10T18:10:16Z",
  "status": "complete",
  "redirect_uri": null,
  "type": "express",
  "result": "clear",
  "sandbox": true,
  "report_type_groups": [
    "3932"
  ],
  "tags": [],
  "results_uri": "https://onfido.com/dashboard/information_requests/2906681",
  "download_uri": "https://onfido.com/dashboard/pdf/information_requests/2906681",
  "form_uri": null,
  "href": "/v2/applicants/0b53866b-872b-47c0-9c31-57e976d8c71d/checks/e4aa9d00-4968-4ca0-a8ae-bbc1914ee502",
  "reports": [
    "caf36db3-649b-459d-a314-ad14e7920293"
  ],
  "paused": false,
  "version": "2.0"
}

Example Expanded Retrieve Check

{
  "id": "e4aa9d00-4968-4ca0-a8ae-bbc1914ee502",
  "created_at": "2017-03-10T18:10:16Z",
  "status": "complete",
  "redirect_uri": null,
  "type": "express",
  "result": "clear",
  "sandbox": true,
  "report_type_groups": [
    "3932"
  ],
  "tags": [],
  "results_uri": "https://onfido.com/dashboard/information_requests/2906681",
  "download_uri": "https://onfido.com/dashboard/pdf/information_requests/2906681",
  "form_uri": null,
  "href": "/v2/applicants/0b53866b-872b-47c0-9c31-57e976d8c71d/checks/e4aa9d00-4968-4ca0-a8ae-bbc1914ee502",
  "reports": [
    {
      "created_at": "2017-03-10T18:10:16Z",
      "href": "/v2/checks/e4aa9d00-4968-4ca0-a8ae-bbc1914ee502/reports/caf36db3-649b-459d-a314-ad14e7920293",
      "id": "caf36db3-649b-459d-a314-ad14e7920293",
      "name": "identity",
      "properties": {},
      "result": "clear",
      "status": "complete",
      "variant": "kyc",
      "breakdown": {
        "date_of_birth": {
          "result": "clear"
        },
        "address": {
          "result": "clear"
        }
      }
    }
  ],
  "paused": false,
  "version": "2.0"
}

If you only want to retrieve one report, send a GET request to https://api.onfido.com/v2/checks/{check_id}/reports/{report_id}. You will get a response object that looks like this:

Example Retrieve Report

{
  "created_at": "2017-03-15T22:38:09Z",
  "href": "/v2/checks/c20f122b-bbe9-4b94-a364-25b2667e1e04/reports/43e85ca8-6daa-43ff-bf41-650b3a5dbd4c",
  "id": "43e85ca8-6daa-43ff-bf41-650b3a5dbd4c",
  "name": "identity",
  "properties": {},
  "result": "clear",
  "status": "complete",
  "variant": "standard",
  "breakdown": {
    "date_of_birth": {
      "result": "clear"
    },
    "address": {
      "result": "clear"
    }
}

To list all checks belonging to an applicant, send a GET request to https://api.onfido.com/v2/applicants/{applicant_id}/checks.

To list all reports belonging to a check, send a GET request to GET https://api.onfido.com/v2/checks/{check_id}/reports.

Webhooks

Onfido provides webhooks to alert you of changes in the status of your resources (i.e., Checks and Reports). These are POST requests to your server that are sent as soon as an event occurs. The body of the request contains details of the event.

All check and report status changes trigger webhook notifications, even for those that complete instantly.

Sandbox checks and reports also trigger webhook notifications. Your can create and configure webhooks to receive status changes from sandbox, live or both environments.

Webhook endpoints can be registered through the Onfido Dashboard or API. To help you diagnose or to understand webhook issues, a log of your wehbook requests is also available under your Dashboard’s Webhook Logs.

More information on our API documentation Webhook section.

Upload Documents and Photos

Some reports require documents (passport, driver's license, etc.) or live photos in order to be processed. Also, for certain document types, both sides of the document must be uploaded, one after the other. Documents are associated with a single applicant, so they can only be uploaded after an applicant has been created.

Either implement a solution to capture the required documents or use one of our document capture SDKs: Javascript, iOS, or Android.

If you are using Onfido's Javascript SDK, you will need to use JSON Web Tokens for authentication. Once you have captured the required documents, POST them to: https://api.onfido.com/v2/applicants/{applicant_id}/documents as a multipart form including the document type and file.

Valid file types are jpg, png, and pdf, and the file size must be between 32KB and 3MB. For 2-sided documents, you must also include the side parameter, either front or back. You will get a response object back that looks like:

Example Response from Upload Document

{
  "id": "7568415-123123-123123",
  "created_at": "2014-05-23 13:50:33Z",
  "href": "/v2/applicants/1030303-123123-123123/documents/7568415-123123-123123",
  "download_href": "/v2/applicants/1030303-123123-123123/documents/7568415-123123-123123/download",
  "file_name": "localfile.png",
  "file_type": "png",
  "file_size": 282870,
  "type": "passport",
  "side": null
}

Live photos, like documents, must be uploaded as a multipart form, and are also subject to file size (32KB-4MB) and file type (jpg, png, and pdf) requirements. Submit live photos as a POST to https://api.onfido.com/v2/live_photos, making sure to include the file and applicant_id as parameters.

By default, 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 optional parameter advanced_validation to false. After submitting, you will get a response object back that looks like:

Example Response from Upload Live Photo

{
  "id": "7410A943-8F00-43D8-98DE-36A774196D86",
  "created_at": "2016-05-11T11:45:26Z",
  "href": "/v2/live_photos/7410A943-8F00-43D8-98DE-36A774196D86",
  "download_href": "/v2/live_photos/7410A943-8F00-43D8-98DE-36A774196D86/download",
  "file_name": "localfile.png",
  "file_type": "png",
  "file_size": 282123
}

Results and Statuses

Results:

When you retrieve a check, you will see results. First, you will get an overall result of clear or consider for the check itself. Also, each individual report will also have a result of clear or consider, (or in the case of identity reports, unidentified). If every report returns a result of clear, then the overall check result will return clear. Otherwise, the overall check result will return consider.

Sub results:

In the case of the document check, we have an additional level of granularity in sub results. If all underlying verifications pass, the sub result will be clear. If the document is unsupported or the image upload is of poor quality, the sub result will be rejected. If the document is suspected to be fraudulent, the sub result will be suspected. If other underlying verifications fail, but they don’t necessarily point to a fraudulent document, the sub result will be caution.

Statuses:

Both checks and reports have statuses that indicate where they are in the processing cycle. More detailed information can be found in the API documentation.