Onfido logo home page
Get in touch
Arrow back Back to guides

Why use API v3

API v3 is our best yet

We wanted API v3 to improve on v2 in every possible way. We listened to our customers: we saw what could be clearer, what could be removed, and what could be simplified.

API v3 isn’t a step change, but it is an evolution. It’s designed to get you up and running with our best-in-class identity verification API faster.

(If you’re an existing customer currently using API v2 but migrating to API v3, you may find our migration guide more useful.)

Cleaner API structure

Compared to API v2, we’ve simplified much of our endpoint structure, removed some inconsistencies in naming, and separated the report objects—which correspond to individual products—from check objects to make them more straightforward to process.

Simpler applicant creation

Fields for applicant creation which were duplicated or unnecessary have been removed, and the array addresses has become the single object address nested inside applicant objects. This is now the only place you need to specify a country for an applicant.

Restructured check management

Checks, made up of reports, are the core of our product. Here are the main examples of how we’ve made check creation more streamlined:

  • API v3 removes terminology such as “report type groups”, “variants” and “asynchronous checks”
  • Specifying which report you need is now more straightforward, via an array called report_names
  • If you need to gather applicant information with our applicant form, simply use a Boolean switch in API v3
  • Unless you specify otherwise, report data is returned as soon as it’s available by default for API v3 checks
  • The request structure for creating a check is much simpler, and needs fewer lines of code each time

Introducing a new biometrics offering

Our newest report, Facial Similarity Photo Fully Auto, is only available in API v3. You can read all about it in our comprehensive API v3 reference documentation.

New API client libraries

For API v3, we’re moving away from API client (wrapper) libraries generated from an OpenAPI specification. Since we went live with v3, we’ve released custom-written libraries for it in Java, Node.js, and Ruby. Python is coming soon.

Let us know what you think

If you have any feedback or if you have any questions, contact our Client Support team at client-support@onfido.com.