API versioning policy

Start here

The following guide sets out Onfido's API versioning policy.

Onfido uses an API versioning policy to support the evolution and improvement of our services without impacting our current clients' integrations. It also creates a continuous and predictable release pattern for our API.

How we version (v3.6+)

Onfido introduces a new versioning policy starting from v3.6 (inclusive) in order to deliver features faster to customers without affecting the clients' integrations.

The main difference to prior versions is the introduction of backwards compatible changes into existing versions, this way customers don't require to upgrade minor versions to get new features (for example a new field in the API response).

The table below outlines what is considered a backward and non-backward compatible change in this versioning policy. A non-backward-compatible change requires a new minor version, while a backward-compatible one will be added to the latest minor version.

How we version (up to v3.5)

Onfido introduces new changes to the API in 3 ways depending on the changes being implemented:

• current version implementation
• a minor version release
• a major version release

When Onfido releases a new API version, you can choose to upgrade to gain access to new features. When changes are implemented into the current API version, these features will become available to customers using this version, without needing an upgrade.

The most recent product improvements will be included in the latest version of the API. We recommend upgrading to the latest version in order to take advantage of new functionality and optimize for the best user experience.

Note: A publicly released version of an Onfido API will never change in any way that could impact your integration.

Current version implementation

Onfido will implement changes into current API versions, without a new version release, when the changes being introduced will not interfere with your integration. These changes represent independent features which do not alter pre-existing logic. For example:

• adding new API endpoints
• adding optional request parameters to existing API endpoints
• sending webhooks for new event types (new event types won't be sent to existing webhooks)
• reordering properties returned from existing API endpoints
• adding a new report

In this case, you can use these changes immediately without having to upgrade API version (if you are currently on the API version in which the changes were introduced).

Minor releases

Onfido will release a minor API version when the changes being introduced are considered backwards compatible, i.e. additive changes. For example:

• adding new properties to the responses from existing API endpoints
• altering the message attributes returned by validation failures or other errors
• adding new values to existing properties in responses from existing API endpoints

In this case, it is safe for you to move from one minor version to another (unless you consider additive changes to be backwards incompatible). Minor versions are released more frequently, and contain incremental changes to the API. An example of a minor release would be v3.1.

Major releases

Onfido will release a major API version if any of the changes being introduced are backwards incompatible. In this case, if you intend to move to a new major version you will need to assess the impact to your integration carefully.

Major versions are released less frequently. An example of a major release would be v4.

Onfido considers the following changes to be backwards incompatible:

• removing a feature of the API
• removing or renaming a resource, field, method or an enum value
• changing the type of a field (eg. integer becomes string or float)
• changing the URL format
• adding a new or modifying an existing validation to an existing resource
• changing existing error response codes/messages
• modifying the expected payload of webhooks and async callbacks
• changing authentication mechanism
• changing the length of strings (eg. max_length changing from 100 to 255)
• changing the meaning of a field even if the type is unchanged

Note: Changes related to document fields and document classification do not trigger either a minor or major API release. These changes are instead communicated directly to customers on a case-by-case basis so that any adjustments can be made accordingly.

Upgrading your API version

You can choose to upgrade your integration to a newer API version at any time.

Note: Upgrading your API version will not affect SDK integrations or the structure of webhook events.

For details and dates of API changes, please see our API documentation changelogs.

You'll also find migration guides on our main Developer Hub page.

Support timelines and deprecation

All of our API versions are released with an indefinite support timeline until a deprecation notice is issued. Deprecation notices will give you at least 18 months to migrate to a newer API version.

Deprecation notices will contain:

• WHAT is being deprecated: an entire version (such as v3.1), set of versions (such as v3—v3.5) or particular functionality (such as ping endpoint across v2-3.6)

• WHEN it’ll come in effect: a clear timeline, allowing minimum 18 months to migrate

• HOW it’ll impact you: an outline of clear consequences for deprecation, which could be one of:

  • a complete removal of functionality
  • functionality available, but without product support or updated documentation

• a MIGRATION GUIDE outlining steps to achieve the functionality in a new way

Deprecation notices will be available:

• as a notice on developers.onfido.com
• as an email to clients impacted by it (with reminders every 30 days)
• as a notice next to relevant functionality on this website
• as a header on API responses when clients make an API call to affected endpoint

Client libraries

Onfido's client libraries are updated in line with changes to the API, but are versioned separately. The latest client library version will always support the latest API version available.

For details on which client library versions support each API version please see the following table:

Webhook events

Webhook events are versioned separately from the Onfido API. There are currently 2 webhook event versions, v2 and v3. Webhook event versions are returned in the webhook event object in the href key.

Example v3 webhook event object

The href field in this version is referencing the same API version used to create the check.

1{
2  "payload": {
3    "resource_type": "report",
4    "action": "report.completed",
5    "object": {
6      "id": "<REPORT_ID>",
7      "status": "complete",
8      "completed_at_iso8601": "2019-10-28T15:00:39Z",
9      "href": "https://api.onfido.com/v3/reports/<REPORT_ID>"
10    }
11  }
12}

Example v2 webhook event object

The href field in this version is always referencing API version v2.

1{
2  "payload": {
3    "resource_type": "report",
4    "action": "report.completed",
5    "object": {
6      "id": "<REPORT_ID>",
7      "status": "complete",
8      "completed_at_iso8601": "2019-11-25T10:11:36Z",
9      "href": "https://api.onfido.com/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
10      "completed_at": "2019-11-25 10:11:36 UTC"
11    }
12  }
13}