> For the complete documentation index, see [llms.txt](/llms.txt)

# API v2 to v3.6 migration guide

## Start here

The following guide is designed to help customers migrate from API v2 to API v3.6. If you're migrating from API v3 to v3.6, please refer to our [separate guide](/api/api-v3-to-v3.6-migration-guide).

If you're updating to API v3.1 onwards and are currently using `api.onfido.com` as a base URL, you must now use the `api.eu.onfido.com` base URL. You can read more about our supported regions in our [API reference](/api/latest/#regions).

Entrust's API versioning policy has changed from v3.6 onwards. Please refer to [our API versioning policy page](/api/api-versioning-policy/).

You can also read about [our supported API client libraries](/api/api-versioning-policy#client-libraries) and which libraries support which versions of the API.

If you have any difficulties migrating, please contact Entrust's [Customer Support team](mailto:identity-support@entrust.com).

## 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](/api/latest/#token-authentication).

## Applicant creation

In the request body when [creating an applicant](/api/latest/#create-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)

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

```json
{
  "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 format of the applicant object in our [API reference](/api/latest/#applicant-object).

### Applicant addresses

The `addresses` attribute 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 (array) of past
addresses.

### Applicant consent

From API v3.4 onwards, there is new applicant data required when creating identity verification flows.

#### Location

From API v3.4 onwards, Entrust has introduced a new `location` parameter in the [applicant](/api/latest/#applicants) and [documents](/api/latest/#documents) resources for specifying the location of an applicant.

**The `location` parameter is mandatory for all applicants in order to create identity verification flows from API v3.4 onwards.** If you do not provide it, all verification requests will fail with a [validation error](/api/latest/#error-codes-and-what-to-do).

#### Consent

Entrust has introduced a new `consents` parameter in the [applicant resource](/api/latest/#applicants).

**The `consents` parameter is mandatory for any applicant who is located in the US in order to create identity verification flows from API v3.4 onwards.** If you do not provide the consents parameter, and the location of the applicant is the US, all verification requests will fail with a [validation error](/api/latest/#error-codes-and-what-to-do).

For customers who have not migrated to [Workflow Studio](/getting-started/classic-to-studio-migration/) and are creating identity verification flows using our checks API endpoint, the `privacy_notices_read_consent_given` parameter no longer exists in check creation.

You can read our [Privacy notices and consent migration guide](/guide/migration-guide-onfido-privacy-notices-and-consent/) for further guidance on how to update your integration to collect end user consent in API 3.6.

## Base URL

The base URL for the [European region](/api/latest/#regions) has changed to `api.eu.onfido.com` from API v3.1 onwards, and is now the default base URL for the API.

If you're deployed in the [European region](/api/latest/#regions) using `api.onfido.com`, you should use the new base URL `api.eu.onfido.com` with API v3.6.

You can read more about our [supported regions](/api/latest/#regions).

## Client libraries

Please refer to our [client libraries versioning guide](/api/api-versioning-policy#client-libraries) to see which libraries support which versions of the API.

## Documents

Documents are no longer nested under the `applicants` [resource](/api/latest/#applicants), they are now managed using the dedicated `documents` [resource](/api/latest/#documents).

### Document uploads

A new API endpoint for [uploading documents](/api/latest/#upload-document) is now available. You should provide an applicant ID in the request body to associate a document with an applicant.

## Driving license naming

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

## Identity reports

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

## Webhook event objects

The `completed_at` timestamp in webhook event objects has been replaced by
`completed_at_iso8601` (it now conforms to [ISO
8601](https://www.iso.org/iso-8601-date-and-time-format.html)). For example:

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

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

## Differences in the Checks and Reports API endpoints

> ⚠️ **Warning:** The API changes documented below are applicable to our Checks and Reports API
> endpoints, and are only relevant to customers who have not migrated to a
> Workflow Studio integration.
> <br />
> For information on migrating to Workflow Studio, please refer to our{' '}
> <a href="https://documentation.identity.entrust.com/getting-started/classic-to-studio-migration/">
> Studio migration guide
> </a>
> .

### "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`](/api/latest/#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](/api/latest/#webhooks) to notify you when the
report is complete.

### Document IDs in Document and Facial Similarity reports

You can still specify which document to use as part of a Document report, and now also Facial Similarity reports, when creating a check. Simply use the `document_ids` field when creating a check:

`"document_ids": [""]`

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

### 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](https://documentation.identity.entrust.com/api/latest/#facial-similarity-reports).

### 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](/api/latest/#download-check).

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

### 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):

```http
POST /v2/applicants//checks HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=
Content-Type: application/json

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

Now (v3.6):

```http
POST /v3.6/checks HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=
Content-Type: application/json

{
  "applicant_id": "",
  "report_names": [
    "document",
    "facial_similarity_photo"
  ]
}
```

**Example check creation (Identity Enhanced report)**

Before (v2):

```http
POST /v2/applicants//checks HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=
Content-Type: application/json

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

Now (v3.6):

```http
POST /v3.6/checks HTTP/1.1
Host: api.eu.onfido.com
Authorization: Token token=
Content-Type: application/json

{
  "applicant_id": "",
  "report_names": [
    "identity_enhanced"
  ]
}
```

### 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](#report-names-v2-v3-mapping)

You'll find a very similar table in [our API reference
documentation](https://documentation.identity.entrust.com/api/latest/#report-names-in-api).

| 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: aml`)                         | `watchlist_aml`                             |
| Watchlist (`variant: full`)                        | `watchlist_standard`                        |
| Watchlist (`options: peps`)                        | `watchlist_peps_only`                       |
| Watchlist (`options: sanctions`)                   | `watchlist_sanctions_only`                  |
| Proof of Address                                   | `proof_of_address`                          |

### Endpoints: v2 → v3 versions 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.6/documents/`                                              |
| **Retrieve document** | v2: `GET /v2/applicants/{applicant_id}/documents/{document_id}`          |
|                       | v3: `GET /v3.6/documents/{document_id}`                                  |
| **List documents**    | v2: `GET /v2/applicants/{applicant_id}/documents/`                       |
|                       | v3: `GET /v3.6/documents?applicant_id=`                    |
| **Download document** | v2: `GET /v2/applicants/{applicant_id}/documents/{document_id}/download` |
|                       | v3: `GET /v3.6/documents/{document_id}/download`                         |
| **Create check**      | v2: `POST /v2/applicants/{applicant_id}/checks/`                         |
|                       | v3: `POST /v3.6/checks/`                                                 |
| **Retrieve check**    | v2: `GET /v2/applicants/{applicant_id}/checks/{check_id}`                |
|                       | v3: `GET /v3.6/checks/{check_id}`                                        |
| **List checks**       | v2: `GET /v2/applicants/{applicant_id}/checks/`                          |
|                       | v3: `GET /v3.6/checks?applicant_id=`                       |
| **Retrieve report**   | v2: `GET /v2/checks/{check_id}/reports/{report_id}`                      |
|                       | v3: `GET /v3.6/reports/{report_id}`                                      |
| **List reports**      | v2: `GET /v2/checks/{check_id}/reports/`                                 |
|                       | v3: `GET /v3.6/reports?check_id=`                              |
| **Resume report**     | v2: `POST /v2/checks/{check_id}/reports/{report_id}/resume`              |
|                       | v3: `POST /v3.6/reports/{report_id}/resume`                              |
| **Cancel report**     | v2: `POST /v2/checks/{check_id}/reports/{report_id}/cancel`              |
|                       | v3: `POST /v3.6/reports/{report_id}/cancel`                              |
| **OCR Autofill**      | v2: `POST /v2/ocr/`                                                      |
|                       | v3: `POST /v3.6/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