Onfido logo home page
Watch a demo
Get in touch
Arrow back Back to guides
We've scheduled essential maintenance on the Onfido platform, affecting all regions. Read more.

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

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 would like to move to a new major version you will likely need to update your integration.

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

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:

Language Library API version support Notes
Ruby onfido-ruby   
API v2 support only up to v0.15.0
API v3 support only up to v1.1.0
Java onfido-java   
API v3 support only up to v1.5.0
Node.js onfido-node   
API v3 support only up to v1.6.0
Also supports TypeScript.
Python onfido-python   
API v3 support only up to v1.3.0
PHP api-php-client   
API v3 support only up to v5.2.0
Made with OpenAPI generator.

 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

  "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>"

Example v2 webhook event object

  "payload": {
    "resource_type": "report",
    "action": "report.completed",
    "object": {
      "id": "<REPORT_ID>",
      "status": "complete",
      "href": "https://api.onfido.com/v2/checks/<CHECK_ID>/reports/<REPORT_ID>",
      "completed_at": "2019-11-25 10:11:36 UTC"

Our Solutions

Onfido uses 256-bit SSL encryption 100% of the time on every device.


Onfido has been certified by BSI to ISO 27001 under certificate number IS 660122.

© Onfido™, 2020. All rights reserved.
Company Registration Number: 07479524.