API v2 to v3 migration guide
Start here
The following guide is designed to help you migrate from Onfido API v2 to API v3.
You can also go to our API reference to find out about our supported client libraries in API v3.
Skip to comprehensive tables for v2 -> v3 mappings for report names and endpoints.
If you have any difficulties migrating, please email our Client Support team.
Authentication
Authentication is exactly the same in API v3. You'll still use the same API tokens and base URLs, and 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 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 withinaddress
)mothers_maiden_name
previous_last_name
nationality
country_of_birth
town_of_birth
addresses
(has becomeaddress
- read more in the following section of this guide)
An example of a valid API v3 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, only a single address can be provided, not a list of past addresses.
"Applicant provides data" replaces standard checks
API v3 has no concept of "standard" and "express" checks.
If you previously used express checks in 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, 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.
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.
Currently, this functionality (and therefore download_uri
) does not exist in
API v3.
Report type groups
Report type groups do not exist in API v3. 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.onfido.com/v3/reports/<REPORT_ID>"
}
}
}
Checks in API v3
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.
- 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.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/checks HTTP/1.1
Host: api.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.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json
{
"type": "express",
"reports": [
{
"name": "identity",
"variant": "kyc"
}
]
}
Now (v3):
POST /v3/checks HTTP/1.1
Host: api.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.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json
{
"type": "express",
"reports": [
{
"name": "watchlist",
"variant": "kyc"
}
]
}
Now (v3):
POST /v3/checks HTTP/1.1
Host: api.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.onfido.com
Authorization: Token token=<YOUR_API_TOKEN>
Content-Type: application/json
{
"type": "express",
"reports": [
{
"name": "right_to_work"
}
]
}
Now (v3):
POST /v3/checks HTTP/1.1
Host: api.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
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 mapping
You'll find a very similar table in our API reference documentation.
Report name (v2 terminology) | Report name in v3 |
---|---|
Document | document |
Document (options: document_address_information ) |
document_with_address_information |
Document (options: driving_licence_information ) |
document_with_driving_licence_information |
Facial Similarity (variant: standard ) |
facial_similarity_photo |
Facial Similarity (variant: video ) |
facial_similarity_video |
Known Faces | known_faces |
Identity (variant: kyc ) |
identity_enhanced |
Watchlist (variant: kyc ) |
watchlist_enhanced |
Watchlist (variant: full ) |
watchlist_standard |
Watchlist (options: peps ) |
watchlist_peps_only |
Watchlist (options: sanctions ) |
watchlist_sanctions_only |
Proof of Address | proof_of_address |
Right to Work | right_to_work |
Endpoints: v2 → v3 mapping
The following table lists endpoint mappings from v2 to v3 in full. Any unlisted endpoints are unchanged:
Endpoint | v2/v3 comparison |
---|---|
Upload document | v2: POST /v2/applicants/{applicant_id}/documents/ |
v3: POST /v3/documents/ |
|
Retrieve document | v2: GET /v2/applicants/{applicant_id}/documents/{document_id} |
v3: GET /v3/documents/{document_id} |
|
List documents | v2: GET /v2/applicants/{applicant_id}/documents/ |
v3: GET /v3/documents?applicant_id=<APPLICANT_ID> |
|
Download document | v2: GET /v2/applicants/{applicant_id}/documents/{document_id}/download |
v3: GET /v3/documents/{document_id}/download |
|
Create check | v2: POST /v2/applicants/{applicant_id}/checks/ |
v3: POST /v3/checks/ |
|
Retrieve check | v2: GET /v2/applicants/{applicant_id}/checks/{check_id} |
v3: GET /v3/checks/{check_id} |
|
List checks | v2: GET /v2/applicants/{applicant_id}/checks/ |
v3: GET /v3/checks?applicant_id=<APPLICANT_ID> |
|
Retrieve report | v2: GET /v2/checks/{check_id}/reports/{report_id} |
v3: GET /v3/reports/{report_id} |
|
List reports | v2: GET /v2/checks/{check_id}/reports/ |
v3: GET /v3/reports?check_id=<CHECK_ID> |
|
Resume report | v2: POST /v2/checks/{check_id}/reports/{report_id}/resume |
v3: POST /v3/reports/{report_id}/resume |
|
Cancel report | v2: POST /v2/checks/{check_id}/reports/{report_id}/cancel |
v3: POST /v3/reports/{report_id}/cancel |
|
OCR Autofill | v2: POST /v2/ocr/ |
v3: POST /v3/extractions |
|
Retrieve RTG * | v2: GET /v2/report_type_groups/{report_type_group_id} |
v3: REMOVED | |
List RTGs * | v2: GET /v2/report_type_groups/ |
v3: REMOVED |
- RTG = Report type group