Release notes

Onfido API

API Versioning Policy update

27 February 2023

The API Versioning Policy was updated for API v3.6 onwards to accept backwards compatible changes, read more in our versioning policy documentation.

API v3.6

24 January 2023

🖥 New property for known faces report matches

The Known Faces report will perform matched applicant fuzzy name matching in the matches set so that matches where the suspected field is true should be considered as possible fraud. This will only work for clients where fuzzy name matching is configured, otherwise it will always return true for all matches.

1...
2"matches": [
3  {
4    "applicant_id": "NTH_MATCHED_APPLICANT_ID",
5    "score": 0.9915,
6    "media_id": "LIVE_PHOTO_ID",
7    "media_type": "live_photos",
8    "suspected": true
9  },
10  ....
11]
12
13}
14...

Read more in our product documentation or API reference.

API v3.5

08 November 2022

🖥 New data input and breakdown for Identity Enhanced (KYC) report

The Identity Enhanced (KYC) report will collect national id numbers and phone numbers as optional inputs for non-UK/non-US geos to help improve performance.

As a result, a new breakdown national_id_number will be added for Identity Enhanced (KYC) reports.

id_number resource types have been expanded with the following new values: voter_id, passport, and other.

A new breakdown national_id_number has been added to the breakdown field in the report response:

1...
2"breakdown": {
3  "national_id_number": {
4    "result": "clear",
5    "breakdown": {
6      "national_id_number_matched": {
7        "results": "clear",
8        "properties": {
9          "sources": "Government",
10          "type": "Identity Card"
11        }
12      }
13    }
14  }
15}
16...

Read more in our product documentation or API reference.

Expand the Document report

As part of the Document report, we now assert if a document has been reused in a suspicious way. This verification result will be mapped to the new repeat_attempts sub-breakdown that was added under the compromised_document breakdown. The previous compromised_document verification that asserts whether the document is publicly available as compromised will be mapped to the document_database sub-breakdown.

Below you will find examples comparing the previous and new response format.

API versions prior to v3.5:

1...
2"compromised_document": {
3  "result": "clear"
4  }
5...

API versions higher or equal to v3.5:

1...
2"compromised_document": {
3         "result": "clear",
4         "breakdown": {
5             "document_database": {
6                 "result": "clear",
7                 "properties": {}
8             },
9             "repeat_attempts": {
10                 "result": "clear",
11                 "properties": {}
12             }
13         }
14     },
15...

The compromised_document breakdown will now contain two sub-breakdowns:

compromised_document_database - this is the already existing sub-breakdown that asserts whether the document is publicly available as compromised.

repeat_attempts - a new sub-breakdown that asserts if a document has been reused in a suspicious way.

🏠 Proof of Address improvements

The Proof of Address report has been improved by adding a source_integrity breakdown, as well as adding sub-breakdowns for visual_fraud and digital_tampering.

1...
2"breakdown": {
3  "source_integrity": {
4    "result": "clear",
5    "breakdown": {
6      "visible_fraud": {
7        "result": "clear",
8        "properties": {}
9      },
10      "digital_tampering": {
11        "result": "clear",
12        "properties": {}
13      }
14    }
15  }
16}
17...

The photos_of_screens document source type has been added, as well as support for the following document types:

• general_letter
• insurance_statement
• pension_property_statement_letter
• mortgage_statement
• mobile_phone_bill
• identity_document_with_address

We've also added new document validity rules and expiry_date. Read more in our product documentation or API reference.

API v3.4

4th May 2022

📜 US biometrics law compliance

To ensure compliance with US laws on biometric data, and to take a privacy centric approach to protect the rights of end users, we have built a new process for gathering and submitting US end user consent.

You must now submit the location of all end users and, where the location is the US, confirm that the end user has granted consent for Onfido, before submitting any checks, unless you are using the Onfido SDK, in which case you must instead update your SDK integration to the corresponding version listed in MIGRATION GUIDE: ONFIDO PRIVACY NOTICES AND CONSENT (US) to enable Onfido to collect and process this information automatically.

location has been added to the applicant and document resource:

1...
2"location": {
3        "ip_address": "219.44.17.31",
4        "country_of_residence": "USA"
5    }
6...

consents has been added to the applicant resource:

1...
2"consents": [
3         {
4            "name": "privacy_notices_read",
5            "granted": true
6        }
7    ]
8...

For more information on how to upgrade your integration to use the latest consent parameters please see our migration guide.

🏠 Proof of Address improvements

We've added the address_parsed and unsupported_document_reason properties as well as new support for the address_certificate document type.

API v3.3

18th February 2022

🏠 Expanded Proof of Address report

The Proof of Address report has been expanded to include new supported issuing countries and date validation logic.

The European Union, USA and Canada are now all supported issuing countries, in addition to the UK.

The report also now asserts whether the submitted document has a valid date of issue. We've added the valid_document_date sub-breakdown under document_classification. The relevant part of the response from the API contains the following for a clear breakdown result:

1...
2"document_classification":{
3        "result":"clear",
4        "breakdown":{
5           "valid_document_date":{
6              "result":"clear",
7              "properties":{}
8           },
9...

Read more in our product documentation or API reference.

Watchlist AML report

12th January 2022

🔍 We have introduced a new watchlist variant, Watchlist AML, which checks users against global watchlists and media sources. It expands on the current Watchlist standard report to include adverse media and is 6AMLD compliant.

It is available to use across all versions of the Onfido API. Read more in our product documentation or API reference.

Trusted Faces for Face Authenticate

15th November 2021

👤 You can now enrol any user in Face Authenticate, without them needing to complete a Facial Similarity report with Onfido. This means Face Authenticate is available for everyone with no dependencies.

Trusted Faces allows you to upload any image of the applicant that you trust, whether that is a file from an internal database or an image submitted for a Facial Similarity report.

Image Quality in the API

30th September 2021

✅ We've added the validate_image_quality option when uploading a document using the API. If requested, the submitted image will undergo an image quality validation, which checks the quality of the uploaded image. If the validation fails, a reason for the failure is returned and you can request the end user to retake the photo.

Validating image quality at the point of document upload reduces the risk of an applicant submitting an image that is of insufficient quality to be verified by the Document report, improving pass rates and turn around times.

It is available to use across all versions of the Onfido API. Read more in our API reference.

Face Authenticate

19th August 2021

🔁 It is now possible to re-verify end users who have already had their initial identity verified by Onfido. Face Authenticate offers a fully automated, real time comparison between an applicant's face and the recorded image of the applicant on your Onfido account, verifying if the face is a match and it is a real person.

Face Authenticate can be used for account recovery, approving high risk transactions and enabling access to services along with multiple other use cases. It is available in API v3 onwards using the Onfido SDKs.

Driver's License Data Verification (DLDV) report

3rd August 2021

🚗 United States driving licenses can be verified using a new report type, available in API v3 onwards. The DLDV report allows quick and accurate verification that a given driver's license is real, providing a strong signal against synthetic fraud.

It verifies the authenticity of an end user's driving license by comparing the attributes on the document with the state Department of Motor Vehicles (DMV) databases.

Read more in our product documentation or API reference.

API v3.2

24th June 2021

### 🆗 Barcode validation

We've added the barcode sub-breakdown under data_validation in the Document report.

By comparing a document's barcode against the defined standard, we are able to provide a more robust assessment of the barcode's validity.

This currently only applies to US and Canadian documents which contain a barcode.

The relevant part of the response from the API is in the Document report object. It contains the following for a consider breakdown result:

1...
2   "data_validation": {
3     "result": "consider",
4     "breakdown": {
5       "barcode": {
6         "result": "consider",
7         "properties": {}
8       },
9...

### 📝 Specify documents for Facial Similarity reports

You can now specify which uploaded document to process in both Document and Facial Similarity reports. This guarantees that the same document that was used and verified by the Document report will also be used for the Facial Similarity report, even if you are associating mutliple documents to a single applicant.

Documents can be specified in the same way by using document_ids during check creation:

"document_ids": ["<DOCUMENT_ID>"]

If you specify document_ids with a check that doesn't contain a Document or Facial Similarity report you will receive the following error:

422 document_ids_with_unsupported_report

When document IDs are associated with a Facial Similarity report, the document IDs of the documents used will be returned under the documents attribute of the report object.

👤👤 Document used for face matching

We've added the document_id property to the face_match sub-breakdown under face_comparison in all Facial Similarity report types. This returns the unique identifier of the document used for the Facial Similarity report.

You can use the document ID to find which document the applicant's live photo or video was matched against.

The relevant part of the response from the API is in the Facial Similarity report object.

1...
2   "face_comparison": {
3     "result": "clear",
4     "breakdown": {
5       "face_match": {
6         "result": "clear",
7         "properties": {
8           "score": 0.6512,
9           "document_id": "<DOCUMENT_ID>"
10         }
11       },
12...

Right to Work share code

11th May 2021

🖥 Eligible non-UK and EU applicants can now use Onfido's Applicant Form to submit GOV.UK right to work share codes instead of documents to verify their right to work in the UK. Customers can also submit share codes, if they have them, using all active versions of the Onfido API.

Please note: This product is now deprecated and no longer available.

API v3.1

8th April 2021

🎫 Account for cases where we don’t obtain a US barcode

This will be enabled by default for all new customers.

💬 If you're an existing customer, speak to your Onfido contact to enable this feature!

We've added the multiple_data_sources_present sub-breakdown under data_consistency in the Document report.

This currently only applies to US Driving Licenses and US State Identity Cards, and specifically only when the barcode data is missing. The relevant part of the response from the API is in the Document report object. It contains the following for a consider breakdown result:

1...
2   "data_consistency": {
3     "result": "consider",
4     "breakdown": {
5       "multiple_data_sources_present": {
6         "result": "consider",
7         "properties": {}
8       },
9...

multiple_data_sources_present acts as a validation for the data_consistency breakdown: if 2 sources are present, then data consistency is possible and the other sub-breakdowns are enabled.

multiple_data_sources_present can be disabled if needed. In this case, it will be returned as null and have no impact on the sub-result.

✅ PDF downloads of check results

You can now download PDFs of check results using an endpoint:

GET /v3.1/checks/{check_id}/download

Read more in our API reference.

📩 Webhook control on check

You can now specify which webhooks will be activated for a check upon its creation.

onfido-python

8th October 2020

Joining our other new custom-written client libraries and built with simplicity in mind is onfido-python! 🐍

This project supersedes the auto-generated api-python-client library.

API v3.0

13th January 2020

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

📷 A new biometrics offering

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

🎁 New client libraries

For API v3 versions, we’ve moved away from auto-generated API client (wrapper) libraries via an OpenAPI specification. Our libraries are now custom-written instead, to make your integration even easier.

⌨️ Let us know what you think

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