API v2 to v3.1 migration guide

Start here

The following guide is designed to help you migrate from Onfido API v2 to API v3.1. If you're migrating from API v3 to v3.1, please review our separate guide.

If you're updating to API v3.1 onwards and are currently using api.onfido.com, you must now use the api.eu.onfido.com base URL. You can read more about our supported regions.

You can also read about our supported API client libraries and which libraries support which versions of the API.

Skip to comprehensive tables for v2 -> v3 versions mappings for report names and endpoints.

If you have any difficulties migrating, please email our Product Support team.

Authentication

Authentication is exactly the same in all versions of our API. The sandbox and live environments are configured in the same way.

Read more about token authentication in our API reference.

Summary of differences

This section summarises the differences in API v3 versions compared to v2, which you should consider when migrating.

Applicant creation

In the request body when creating an applicant, the following fields no longer exist:

• gender
• telephone
• mobile
• country (now solely within address)
• mothers_maiden_name
• previous_last_name
• nationality
• country_of_birth
• town_of_birth
• addresses (has become address - read more in the following section of this guide)

An example of a valid API v3 version request body for creating an applicant:

    {
      "first_name": "Jane",
      "last_name": "Doe",
      "dob": "1990-01-31",
      "address": {
          "building_number": "100",
          "street": "Main Street",
          "town": "London",
          "postcode": "SW4 6EH",
          "country": "GBR"
        }
    }

You can review the new form of the applicant object.

Applicant addresses

addresses has become address, and is now a single address rather than an array of addresses. The country field within address is the only place you need to provide information about an applicant's country of residence.

In API v3 versions, only a single address can be provided, not a list of past addresses.

"Applicant provides data" replaces standard checks

API v3 versions have no concept of "standard" and "express" checks.

If you previously used express checks in API v2, you no longer need to pass a type in check creation requests.

If you previously used standard checks to gather applicant information with the applicant form, simply set applicant_provides_data to true.

Asynchronous checks are the default

In API v3 versions, async has changed to asynchronous and is set to true by default. If set to false, report results in the check request response will only be returned when all reports are complete. You can configure webhooks to notify you when the report is complete.

Client libraries

Please review our client libraries versioning guide to see which libraries support which versions of the API.

Default base URL for EU is now api.eu.onfido.com

You should use the api.eu.onfido.com base URL if you're deployed in the EU region, which is now the API base URL in our documentation examples. You can read more about our supported regions.

Documents

Documents are no longer nested under the /applicants resource. They're now managed under /documents.

Document IDs in the Document Report

You can still specify which document to use as part of a Document report when creating a check. Simply use the document_ids field when creating a check.

"document_ids": ["<DOCUMENT_ID>"]

If unspecified, the most recently uploaded document (or documents for a two-sided ID document) will be used.

Document uploads

The new endpoint is POST /documents/ and you should provide an applicant ID in the request body to associate a document with an applicant.

Driving licence naming inconsistencies are fixed

In API v3, the spelling driving_licence is used everywhere and there is no inconsistency.

Facial Similarity score

The score value is now returned in the properties object under the new face_match sub-breakdown. You can read more in our API documentation.

Identity reports

identity_enhanced reports replace all Identity reports in API v3. They do not support previous addresses.

PDF downloads

In API v2, a download_uri string is returned in check response objects, which is a link to a PDF output of the check results.

This is now available as an API v3.1 endpoint.

Report type groups

Report type groups do not exist in API v3 versions. Instead, we've simplified how to create a check. Read more in the section later in this guide on check creation.

Webhook event objects

The completed_at timestamp in webhook event objects has been replaced by completed_at_iso8601 (it now conforms to ISO 8601). For example:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "payload": {
    "resource_type": "report",
    "action": "report.completed",
    "object": {
      "id": "<REPORT_ID>",
      "status": "complete",
      "completed_at_iso8601": "2019-10-28T15:00:39Z",
      "href": "https://api.eu.onfido.com/v3/reports/<REPORT_ID>"
    }
  }
}

Checks in API v3 versions

Checks are no longer nested under the /applicants resource. They're now managed under /checks.

Check creation

Check creation is designed to be much simpler in API v3 versions.

• the new endpoint is POST /checks/
• we've removed the concept of variants and options (see the section 'Report names, options and package variants' later in this guide)
• you now simply pass report names to the report_names array of strings
• an applicant ID is now required in the request body

Example check creation (Document and Facial Similarity Photo reports)

Before (v2):

POST /v2/applicants/<APPLICANT_ID>/checks HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "type": "express",
  "reports": [
    {
      "name": "document"
    },
    {
      "name": "facial_similarity",
      "variant": "standard"
    }
  ]
}

Now (v3):

POST /v3.1/checks HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "applicant_id": "<APPLICANT_ID>",
  "report_names": [
    "document",
    "facial_similarity_photo"
  ]
}

Example check creation (Identity Enhanced report)

Before (v2):

POST /v2/applicants/<APPLICANT_ID>/checks HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "type": "express",
  "reports": [
    {
      "name": "identity",
      "variant": "kyc"
    }
  ]
}

Now (v3):

POST /v3.1/checks HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "applicant_id": "<APPLICANT_ID>",
  "report_names": [
    "identity_enhanced"
  ]
}

Example check creation (Watchlist Enhanced report)

Before (v2):

POST /v2/applicants/<APPLICANT_ID>/checks HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "type": "express",
  "reports": [
    {
      "name": "watchlist",
      "variant": "kyc"
    }
  ]
}

Now (v3.1):

POST /v3.1/checks HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "applicant_id": "<APPLICANT_ID>",
  "report_names": [
    "watchlist_enhanced"
  ]
}

Example check creation (Right to Work report)

Before (v2):

POST /v2/applicants/<APPLICANT_ID>/checks HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "type": "express",
  "reports": [
    {
      "name": "right_to_work"
    }
  ]
}

Now (v3):

POST /v3.1/checks HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json

{
  "applicant_id": "<APPLICANT_ID>",
  "report_names": [
    "right_to_work"
  ]
}

Report names in API v3 versions

The concept of package variants and options for reports does not exist in API v3. The same functionality is achieved using more descriptive report names.

Report names: v2 → v3 versions mapping

You'll find a very similar table in our API reference documentation.

Endpoints: v2 → v3 versions mapping

The following table lists endpoint mappings from v2 to v3 in full. Any unlisted endpoints are unchanged:

• RTG = Report type group