Onfido
Supported features
Onfido is a third-party eIDV provider integrated with Assure API. Signicat supports the following identity verification features from Onfido:
- ID document check
- Face match between ID document and selfie
- Liveness check of live video recording
User flow example
The following verification example shows a typical user flow where we use Onfido's native SDK to take a photo of an ID document and a selfie to match those images. The Assure API can be used either in a web or in a native (mobile) context. In this example, the images are from a web environment.
This is just an example of how the verification flow could look like. The screens will probably look differently in your own implementation.
This example assumes you already have created a dossier and a process.
After the verification is finished, you can call the Get process endpoint to inspect the final result (see step F below). Inside the process, you can see the process details, like the final result status ( e.g. accepted) and also the provider specific information with the results from the analysis of the the document verification and facial similarity.
Integration use cases for Onfido
This section assumes you already have done the initial integration steps with the Assure API, see set up client credentials and access token.
In the following, we present the two most common use cases for Onfido:
Both options can be used either in a web or in a native (mobile) context. The steps in the two flows are quite similar, except for some smaller differences in the Create process and Upload images steps.
UC 1: Use Onfido and integrate only with Assure API (web or mobile usage)
I want to use Onfido to verify the identity of an end-user using their identity document.
I want to be able to upload the ID images directly through the Assure API without having to integrate with Onfido's SDK.
I want to be notified when a final result has been obtained (either successfully or not).
Note: This use case seamlessly fits both web (JS) and mobile (Android/iOS) applications.
Use case 1 flow
The colour codes illustrate the flow decision:
- Green = Must
- Grey = Optional
- White = Not used
Step A: Create dossier
- Use the Create dossier endpoint to create a placeholder for all of your end-user's data.
- Save the
dossierIdyou get in the response to be used in the next requests.
Ensure you use one dossier per end-user.
Step B: Get document types (optional)
This step is not required, but you may want to get the list of documents accepted by Onfido so you know which documentType Onfido supports (to be passed on to the next request).
In this use case, the document type is a passport (see example code in the next step).
Step C: Create process
Use the Create process endpoint to create an identity verification process inside the dossier.
Ensure you use the dossierId from the "Create dossier" response.
- Set the provider to
onfido.
Here is an example JSON request body:
{
"provider": "onfido",
"processType": "documentSelfie",
"documentType": "passport",
"processParameters": {
"location": {
"countryOfResidence": "NLD"
}
}
}
- In this example, you ask the end-user to perform an identity verification using their passport and a selfie image.
- You must always send the end-user's location in an Onfido "Create process" request. For more details, see the Location section.
- You must save the
processIdfrom the response to use on the next steps.
It is recommended to subscribe to Assure Events to be notified when the result is available (either successfully or not). For more information, see Assure Events.
Location
You must always send the end-user's location in an Onfido "Create process" request. Otherwise, you will get an error when you call the Start verification endpoint.
There are two ways you can set the location, either via countryOfResidence or ipAddress:
Location from country of residence:
{
"processParameters": {
"location": {
"countryOfResidence": "NLD"
}
}
}
Location from IP address:
{
"processParameters": {
"location": {
"ipAddress": "176.78.162.201",
}
}
}
If Onfido is unable to infer the country of residence from the IP address, you will get an error when you call the Start verification endpoint. For that reason, we strongly recommend you ask the end-user for their country of residence (as in the first example above).
You can find more information about the location field in the API Reference under Create process > processParameters.
Onfido privacy consent
If an end-user is a US resident, they must consent to the collection, use, and handling of biometric identifiers and information by Onfido.
You only need to get the privacy consent from the end-user when the processType is documentSelfie or documentVideo and your end-user is a US resident.
In this case, you must:
- Explain to the end-user that you use a third-party provider, Onfido, to process their identity check.
- Present the end-user with the "Onfido Terms and condition" page to get their consent: "I have read, understand and accept Onfido Facial Scan Policy and Release, Onfido Privacy Policy and Onfido Terms of Service.” You may change the phrasing to be consistent with your user experience, as long as you obtain confirmation that the end user has read, understood and accepted Onfido's policies and terms of service. For example, "By continuing to use this service you confirm that you have read, understand and accept Onfido's …" or "By clicking 'accept' you confirm you have read, understand and accept Onfido's …". For standard example texts and screen images, see the Translations for Capture SDK section.
- Ensure you present this information and get the end-user's consent within your application before you upload any images to Onfido.
After you have done the steps above, you can send the consents value in the Create process request. If the end-user does not provide their consent, you don't even need to bother creating a process for them given that it will fail when you call the Start verification endpoint.
Sending the privacy consent as true means that the end-user has read Onfido's Privacy notices and consent and has agreed to them.
You are responsible for ensuring this is true before processing.
Here is an example of a Create process request where the end-user has given their consent:
{
"provider": "onfido",
"processType": "documentSelfie",
"documentType": "passport",
"processParameters":
{
"location":
{
"countryOfResidence": "USA"
},
"consents":
{
"privacy": true
}
}
}
You can find more information about the consents field in the API Reference under Create process > processParameters.
Step D2: Upload images
- Use the Set images to the process endpoint to upload the images the end-user captured during the identity verification. This JSON example file contains specimen images of a Norwegian passport and a selfie: NOR_passport-specimen_and_selfie.json
- Extra optional step: Check the images that were uploaded using the Get Image endpoint. You should only be able to retrieve “FRONT” and “SELFIE”. “BACK” will only be available if you used a 2-sided document and “PORTRAIT” is not made available by Onfido.
Step E: Start verification
- Use the startVerification endpoint to perform a verification of the identity document that was uploaded.
- Extra optional step: Before requesting the verification to start, you may want to call Get process to get the following process info:
- The provider is”onfido”
- The status is “pending”
If the end-user resides in the USA and they did not give consent in the Create process step, Start verification will fail. For more information, see the Onfido consent section.
Step F: Get process
If you have subscribed to Assure Events as recommended in step C, you know when the verification result is ready.
- Call the Get process endpoint: Then use the
dossierIdandprocessIdreceived in the Assure Events notification.
The process now contains data about the process' final result. For more details about this, see Service details for Onfido > Get process.
UC 2: Use Onfido and integrate with Onfido's SDK (web or mobile usage)
I want to use Onfido to verify the identity of an end-user using their identity document.
I want the required ID images to be captured and uploaded using Onfido's iOS SDK.
Note: This use case seamlessly fits both web (JS) and mobile (Android/iOS) applications.
Use case 2 flow
The colour codes illustrate the flow decision:
- Green = Must
- Grey = Optional
- White = Not used
In this case, you will perform the same steps as in Use Case 1, except from some differences in the "Create process" and "Upload images" steps. For details, see the SDKs section.
UC 3: Use Onfido to extract extra driving licence information
If you want to extract extra information from a driving licence, you can send the requestExtraDataFromDrivingLicense parameter when calling either the Create Process or Start capture flow endpoint.
Here is "Start capture flow" request example:
{
"providers": [
{
"provider": "onfido",
"processType": "document",
"requestExtraDataFromDrivingLicense": true
}
],
"redirectUrl": "<REDIRECT_URL>"
}
Then you will get extra information in the Get Process response, see example in the Get process > accepted section.
Supported DL documents
You can extract extra information from the driving licences of the following countries/states:
European driving licences (expand/collapse)
- Albania
- Andorra
- Armenia
- Austria
- Belarus
- Belgium
- Bosnia and Herzegovina
- Bulgaria
- Croatia
- Cyprus
- Czech Republic
- Denmark
- Estonia
- Finland
- France
- Germany
- Greece
- Hungary
- Jersey
- Iceland
- Ireland
- Italy
- Latvia
- Lichtenstein
- Lithuania
- Luxembourg
- Malta
- Moldova
- Monaco
- Netherlands
- North Macedonia
- Norway
- Poland
- Portugal
- Romania
- Serbia
- Slovakia
- Slovenia
- Spain
- Sweden
- Switzerland
- Ukraine
- United Kingdom of Great Britain and Northern Ireland
US driving licences (expand/collapse)
- California
- Colorado
- District of Columbia
- Florida
- Georgia
- Illinois
- Maryland
- Massachusetts
- Michigan
- New Jersey
- New York
- North Carolina
- Ohio
- Pennsylvania
- Texas
- Virginia
- Washington
- Wisconsin
Other driving licences (expand/collapse)
- Israel
- Saint-Barthélemy
- Russian Federation
Mobile SDKs (Android and iOS)
The aim of this topic is to help a developer integrating with the Assure API using Onfido's mobile SDKs. This is a more detailed description of Use case 2 above.
Please, keep in mind that the following descriptions do not contain all the necessary steps for production mode. In addition, you must add validations, tests and error handling, which is outside the scope of this documentation.
Using the third-party SDKs means that the end-user will see Onfido's user interface when performing the identity verification on their mobile or desktop.
- Check the end-user's ID document.
- Perform a face match between the ID document and selfie of the end-user.
- Perform a liveness check of the live video recording of the end-user.
Before you start the SDK integration, we recommend to familiarise yourself with the general steps for integrating with the Assure API.
Requirements
Before you start the SDK integration, you should be aware of the following requirements for Onfido's SDKs:
- We advise you to always use the latest Onfido SDK version. For more information about the minimum required version, see Onfido Privacy notices and consent (US).
- Check the supported device versions in Onfido's official documentation.
- The app needs camera and microphone permission.
- Your app must always communicate with your own server and never directly with the Assure API (see Usage recommendations).
- Since you are integrating with the Assure API in a native app context, you should choose the eIDV generic flow.
Integration steps overview
This diagram provides an abstraction of the client-side implementation.
Onfido SDK process diagram
The next sections describe all the necessary steps, including the integration with Assure before and after the Onfido SDK integration in step 3:
- Create a dossier.
- Create a process.
- Integrate with the Onfido mobile SDK to check the ID document.
- Start verification.
- Get result.
All the steps are similar for iOS and Android except the SDK integration in step 3, which is described below in different tabs for iOS and Android.
Create a dossier
Use the Create dossier endpoint to create a placeholder for all of your end-user's data:
curl -X POST \
<ENVIRONMENT>/assure/dossiers \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
Save the dossierId from the response body to use in the next requests.
After creating a dossier, you can see all of its contents anytime you want to. To do that, use the Get dossier endpoint giving it the dossierId.
Create a process
To be able to create a process, you need to get some information from your mobile app, send it to your backend server and afterwards to the Assure API.
Here is an example request:
{
"provider": "onfido",
"processType": "document",
"processParameters": {
"mobileAppId": "com.example.mymobileapp"
}
}
processType: The value depends on the check you are doing. If it is just a document check, you should usedocument. If you're using also face comparison, you should usedocumentSelfie(if using a photograph) ordocumentVideoif you are also checking for liveness.mobileAppId: This is a unique ID of the mobile app that will integrate with the provider's iOS/Android SDK. This is either a bundle ID for iOS or application ID for Android, e.g.com.example.mymobileapp.
Here is an example response:
{
"processId": "710a4326-ef7f-4bed-85c4-aa523f742742",
"status": "pending",
"createdAt": "2019-04-12T09:35:19Z",
"updatedAt": "2019-04-14T09:35:19Z",
"authorization": "eyJhbGciOiJJ9.eyJwYXlsb2FYVjRGVhZU252alVsekNHaUMzR9.uW-2dEu_rYUyhF_E",
"provider": "onfido",
"processType": "document"
}
Save the information from the response. You will need it in the next steps.
Integrate with the Onfido mobile SDK to check the ID document
To check the ID document of the end-user, you must now integrate with the Onfido SDK for either Android or iOS:
- Android
- iOS
Import the SDK
For advice about which SDK version you should download, see the Requirements section.
You can use Gradle to download/upgrade Onfido's SDK version automatically, instead of manually downloading the zip file from Onfido's github page.
You can set up the download instructions like this:
build.gradle
...
repositories {
...
maven {
...
maven {
url "https://dl.bintray.com/onfido/maven"
}
}
}
...
dependencies {
...
implementation 'com.onfido.sdk.capture:onfido-capture-sdk-core:x.x.x'
}
...
If these instructions stop working (for example, if they become outdated), then you can contact us by creating a support ticket in the Signicat Dashboard.
Initialise and run the SDK (Java code example)
You must send the authorization field that you received in the backend response to the mobile app.
Sample code for starting the SDK:
OnfidoConfig config = new OnfidoConfig.Builder(activity)
.withSDKToken(authorization) //this is the authorization you received from Assure API
.withCustomFlow(steps) //these steps will have to be configured by you depending on the document you're using and the processType
.build();
Onfido onfido = OnfidoFactory.create(activity).getClient();
onfido.startActivityForResult(activity, ONFIDO_PROCESS_REQUEST_ID, config); //ONFIDO_PROCESS_REQUEST_ID is the ID that comes to the onActivityResult method.
After you have started the SDK, the SDK communicates directly with Onfido and sends the images and videos etc. Then Onfido analyses the process and you will receive a result from the SDK saying if it was a success or not. The process of the mobile app ends here.
You can customise the SDK by following the steps described in https://github.com/onfido/onfido-android-sdk depending on the document you're using.
Import the SDK
For advice about which SDK version you should download, see the Requirements section.
To import the SDK package, do the following steps:
-
Make sure you have downloaded and installed the latest version of CocoaPods.
-
Add the following row to your
Podfile:pod 'Onfido', '~> 23.0.1' -
Run
pod install. -
Make sure you use the
.xcworkspacefile to open your project in Xcode, instead of the.xcodeprojfile, from here and onwards.
Initialise and run the SDK (Swift code example)
Start the Onfido Mobile SDK by setting the SDK field withSDKToken with the authorization that you received in the the backend response.
Sample code for starting the SDK:
import UIKit
import Onfido
final class ViewController: UIViewController {
let authorization = String
init(authorization: authorization) {
self.authorization = authorization
super.init()
}
override func viewDidLoad() {
super.viewDidLoad()
self.runFlow(authorization: self.authorization)
}
private func runFlow(authorization: String) {
let responseHandler: (OnfidoResponse) -> Void = { response in
if case let OnfidoResponse.error(innerError) = response {
print(innerError)
} else if case OnfidoResponse.success = response {
print("Success")
} else if case OnfidoResponse.cancel = response {
print("Canceled by user")
}
}
let faceStep = FaceStepVariant.photo(withConfiguration: PhotoStepConfiguration())
let config = try! OnfidoConfig.builder()
.withSDKToken(authorization)
.withWelcomeStep()
.withDocumentStep()
.withFaceStep(ofVariant: faceStep)
.build()
let onfidoFlow = OnfidoFlow(withConfiguration: config)
.with(responseHandler: responseHandler)
do {
let onfidoRun = try onfidoFlow.run()
onfidoRun.modalPresentationStyle = .formSheet // to present modally
self.present(onfidoRun, animated: true, completion: nil)
} catch let error {
// cannot execute the flow
// check CameraPermissions
print(error)
}
}
}
Customisation
Welcome screen
You can decide if you want to show a pre-defined Onfido welcome screen:
...
let config = try! OnfidoConfig.builder()
.withWelcomeStep()
...
.build()
Face match
You can perform the face match in two possible ways, either by asking the user to take a selfie photo or to make a live video recording. The Onfido API will then later on compare this photo/video with images retrieved from the identity documents and run a facial similarity check.
Face match with photo
Use the following sample code when the user is required to take a selfie photo:
let stepConfig = VideoStepConfiguration(showIntroVideo: true)
let facePhto = FaceStepVariant.photo(withConfiguration: PhotoStepConfiguration()
let config = try! OnfidoConfig.builder()
...
.withFaceStep(ofVariant: facePhoto)
...
.build()
Face match with live video recording
Performing a face match with a live video recording adds extra security to the identification. In this case, the user is asked to move their head and read random numbers displayed on the device screen.
Use the following sample code when the user is required to make a live video recording:
let stepConfig = VideoStepConfiguration(showIntroVideo: true)
let faceVideo = FaceStepVariant.video(withConfiguration: stepConfig)
let config = try! OnfidoConfig.builder()
...
.withFaceStep(ofVariant: faceVideo)
...
.build()
Start verification
Your server (backend) must request the Assure API to start performing the identity verification.
To do this, you just call the Start verification endpoint. No parameters are necessary.
Get result
After Onfido has analysed the images/videos, Onfido will send a callback to Assure API with the result.
It is recommended to subscribe to Assure Events to be notified when the result is available (either successfully or not). For more information, see Assure Events.
You can call the Get process endpoint to get the full information about the process.
For result examples, see Onfido results..
You can also get a zip file with the packaged process by calling the Download full result endpoint.
Service details for Onfido
This section goes more into detail about some useful endpoints when integrating with Onfido:
Start Capture flow
Capture SDK
More information will follow.
Onfido native JS SDK configuration
The Capture configuration also includes specific configuration fields when using the Onfido native SDK. These configuration fields allow you to specify the workflow and the graphical user interface. This configuration applies when the sdk field in the "Start Capture flow" request is set to native and provider to onfido.
For more details, see the onfidoConfig element in the API Reference for either Create or Update capture configuration.
Get process
This section describes the final result status that you receive in the Get process response for Onfido.
Final result status
Onfido always performs a documentVerification. Depending on the process type you choose (see below), it can also perform a facialSimilarity verification between the picture/video of the end-user and the photo in the ID document.
Based on Onfido's results, the Assure API returns a final status for that process:
Process types
Process types for Onfido are:
documentdocumentSelfiedocumentVideo
If the process type is documentSelfie or documentVideo, the final status depends on the result of both facialSimilarity and documentVerification. If the process type is document only, the final status depends exclusively on the result of documentVerification.
For detailed description of processType, see the API Reference.
accepted
Onfido processes are accepted when all underlying verifications have passed. This means there are no
indications the document is fraudulent.
Response example: Passport (expand/collapse)
In this example, clear is passed as value in the result and breakdowns fields, which means all the underlying verifications have passed.
{
"processId": "686f23a4-b50e-4e36-9387-d94b95ef8ed0",
"provider": "onfido",
"processType": "documentSelfie",
"status": "accepted",
"depictions": [
"front",
"selfie"
],
"finalResult": {
"firstName": "WILLEKE LISELOTTE",
"lastName": "DE BRUIJN",
"dateOfExpiry": "2031-08-30",
"dateOfBirth": "1965-03-10",
"documentType": "passport",
"documentNumber": "SPECI2021",
"issuingCountry": "NLD",
"similarityScore": "medium"
},
"providerSpecific": {
"documentVerification": {
"firstName": "WILLEKE LISELOTTE",
"lastName": "DE BRUIJN",
"dateOfBirth": "1965-03-10",
"documentType": "passport",
"documentNumber": "SPECI2021",
"dateOfExpiry": "2031-08-30",
"issuingCountry": "NLD",
"subResult": "clear",
"ageValidation": "clear",
"policeRecord": "clear",
"dataConsistency": "clear",
"dataValidation": "clear",
"imageIntegrity": "clear",
"dataComparison": "clear",
"compromisedDocument": "clear",
"result": "clear",
"breakdowns": {
"imageIntegrity": {
"result": "clear",
"breakdown": {
"supportedDocument": {
"result": "clear",
"properties": {}
},
"colourPicture": {
"result": "clear",
"properties": {}
},
"imageQuality": {
"result": "clear",
"properties": {}
},
"conclusiveDocumentQuality": {
"result": "clear",
"properties": {}
}
}
},
"dataConsistency": {
"result": "clear",
"breakdown": {
"lastName": {
"result": "clear",
"properties": {}
},
"firstName": {
"result": "clear",
"properties": {}
},
"dateOfExpiry": {
"result": "clear",
"properties": {}
},
"nationality": {
"result": "clear",
"properties": {}
},
"gender": {
"result": "clear",
"properties": {}
},
"multipleDataSourcesPresent": {
"result": "clear",
"properties": {}
},
"documentType": {
"result": "clear",
"properties": {}
},
"issuingCountry": {
"result": "clear",
"properties": {}
},
"dateOfBirth": {
"result": "clear",
"properties": {}
},
"documentNumbers": {
"result": "clear",
"properties": {}
}
}
},
"dataComparison": {
"result": "clear",
"breakdown": {
"firstName": {
"result": "clear",
"properties": {}
},
"lastName": {
"result": "clear",
"properties": {}
},
"dateOfExpiry": {
"result": "clear",
"properties": {}
},
"gender": {
"result": "clear",
"properties": {}
},
"documentType": {
"result": "clear",
"properties": {}
},
"issuingCountry": {
"result": "clear",
"properties": {}
},
"dateOfBirth": {
"result": "clear",
"properties": {}
},
"documentNumbers": {
"result": "clear",
"properties": {}
}
}
},
"ageValidation": {
"result": "clear",
"breakdown": {
"minimumAcceptedAge": {
"result": "clear",
"properties": {}
}
}
},
"policeRecord": {
"result": "clear"
},
"visualAuthenticity": {
"result": "clear",
"breakdown": {
"faceDetection": {
"result": "clear",
"properties": {}
},
"template": {
"result": "clear",
"properties": {}
},
"pictureFaceIntegrity": {
"result": "clear",
"properties": {}
},
"other": {
"result": "clear",
"properties": {}
},
"securityFeatures": {
"result": "clear",
"properties": {}
},
"fonts": {
"result": "clear",
"properties": {}
},
"originalDocumentPresent": {
"result": "clear",
"properties": {}
},
"digitalTampering": {
"result": "clear",
"properties": {}
}
}
},
"dataValidation": {
"result": "clear",
"breakdown": {
"expiryDate": {
"result": "clear",
"properties": {}
},
"mrz": {
"result": "clear",
"properties": {}
},
"gender": {
"result": "clear",
"properties": {}
},
"dateOfBirth": {
"result": "clear",
"properties": {}
},
"documentExpiration": {
"result": "clear",
"properties": {}
},
"documentNumbers": {
"result": "clear",
"properties": {}
}
}
},
"compromisedDocument": {
"result": "clear",
"breakdown": {
"documentDatabase": {
"result": "clear",
"properties": {}
},
"repeatAttempts": {
"result": "clear",
"properties": {}
}
}
}
},
"visualAuthenticity": "clear"
},
"facialSimilarity": {
"result": "clear",
"imageIntegrity": "clear",
"faceComparison": "clear",
"visualAuthenticity": "clear",
"similarityScore": "medium",
"breakdowns": {
"imageIntegrity": {
"result": "clear",
"breakdown": {
"faceDetected": {
"result": "clear",
"properties": {}
},
"sourceIntegrity": {
"result": "clear",
"properties": {}
}
}
},
"faceComparison": {
"result": "clear",
"breakdown": {
"faceMatch": {
"result": "clear",
"properties": {
"score": 0.6512,
"livePhotoId": "6131b376-a2fd-4b51-98e3-d72ce17ff915",
"documentId": "c35dde29-b384-47b6-b3b2-3fd251cb96a5"
}
}
}
},
"visualAuthenticity": {
"result": "clear",
"breakdown": {
"spoofingDetection": {
"result": "clear",
"properties": {
"score": 0.9512
}
}
}
}
}
}
},
"createdAt": "2025-01-08T16:20:57Z",
"updatedAt": "2025-01-08T16:22:15Z"
}
Response example: Extended driving licence information (expand/collapse)
{
"processId": "b481a2e7-ba64-4889-bede-236a0a4a05d0",
"provider": "onfido",
"processType": "document",
"status": "accepted",
"finalResult": {
"firstName": "WILLEKE LISELOTTE",
"lastName": "DE BRUIJN",
"dateOfBirth": "1965-03-10",
"documentType": "driversLicense",
"documentNumber": "C1234567",
"issuingCountry": "NLD",
"personalIdentificationNumber": "111111111",
"placeOfBirth": "AMSTERDAM",
"dateOfIssue": "2018-07-14"
},
"providerSpecific": {
"documentVerification": {
"firstName": "WILLEKE LISELOTTEP",
"lastName": "DE BRUIJN",
"dateOfBirth": "1965-03-10",
"documentType": "driversLicense",
"documentNumber": "C1234567",
"issuingCountry": "NLD",
"dateOfIssue": "2018-07-14",
"placeOfBirth": "AMSTERDAM",
"personalIdentificationNumber": "111111111",
"subResult": "clear",
"ageValidation": "clear",
"dataValidation": "clear",
"imageIntegrity": "clear",
"compromisedDocument": "clear",
"result": "clear",
"driversLicense": true,
"restrictedLicence": false,
"rawVehicleClasses": "A1,A2,A,B1,B",
"vehicleClassDetails": [
{
"category": "A1",
"obtainmentDate": "2002-10-14",
"expiryDate": "2036-07-23"
},
{
"category": "A2",
"obtainmentDate": "2018-07-11",
"expiryDate": "2033-07-14"
},
{
"category": "A",
"obtainmentDate": "2018-07-11",
"expiryDate": "2033-07-14"
},
{
"category": "B1",
"obtainmentDate": "2004-10-07",
"expiryDate": "2036-07-23"
},
{
"category": "B",
"obtainmentDate": "2004-10-07",
"expiryDate": "2036-07-23"
}
],
"manualTransmissionRestriction": false,
"passengerVehicle": {
"obtainmentDate": "2004-10-07",
"expiryDate": "2036-07-23"
},
"breakdowns": {
"issuingAuthority": {
"breakdown": {
"nfcActiveAuthentication": {
"properties": {}
},
"nfcPassiveAuthentication": {
"properties": {}
}
}
},
"imageIntegrity": {
"result": "clear",
"breakdown": {
"supportedDocument": {
"result": "clear",
"properties": {
"onfidoSupportedDocument": "clear",
"customSupportedDocument": "clear",
"issuingCountrySubjectToSanctions": "clear"
}
},
"colourPicture": {
"result": "clear",
"properties": {}
},
"imageQuality": {
"result": "clear",
"properties": {}
},
"conclusiveDocumentQuality": {
"result": "clear",
"properties": {
"cornerRemoved": "clear",
"abnormalDocumentFeatures": "clear",
"obscuredSecurityFeatures": "clear",
"watermarksDigitalTextOverlay": "clear",
"puncturedDocument": "clear",
"obscuredDataPoints": "clear",
"missingBack": "clear",
"digitalDocument": "clear"
}
}
}
},
"dataConsistency": {
"breakdown": {
"dateOfExpiry": {
"properties": {}
},
"lastName": {
"properties": {}
},
"firstName": {
"properties": {}
},
"nationality": {
"properties": {}
},
"gender": {
"properties": {}
},
"multipleDataSourcesPresent": {
"properties": {}
},
"documentType": {
"properties": {}
},
"issuingCountry": {
"properties": {}
},
"dateOfBirth": {
"properties": {}
},
"documentNumbers": {
"properties": {}
}
}
},
"dataComparison": {
"breakdown": {
"dateOfExpiry": {
"properties": {}
},
"lastName": {
"properties": {}
},
"firstName": {
"properties": {}
},
"gender": {
"properties": {}
},
"documentType": {
"properties": {}
},
"issuingCountry": {
"properties": {}
},
"dateOfBirth": {
"properties": {}
},
"documentNumbers": {
"properties": {}
}
}
},
"ageValidation": {
"result": "clear",
"breakdown": {
"minimumAcceptedAge": {
"result": "clear",
"properties": {}
}
}
},
"policeRecord": {},
"dataValidation": {
"result": "clear",
"breakdown": {
"expiryDate": {
"properties": {}
},
"mrz": {
"properties": {}
},
"gender": {
"properties": {}
},
"dateOfBirth": {
"result": "clear",
"properties": {}
},
"documentExpiration": {
"properties": {}
},
"barcode": {
"properties": {}
},
"documentNumbers": {
"result": "clear",
"properties": {
"documentNumber": "clear"
}
}
}
},
"visualAuthenticity": {
"result": "clear",
"breakdown": {
"faceDetection": {
"result": "clear",
"properties": {}
},
"template": {
"result": "clear",
"properties": {}
},
"pictureFaceIntegrity": {
"result": "clear",
"properties": {}
},
"other": {
"result": "clear",
"properties": {}
},
"securityFeatures": {
"result": "clear",
"properties": {}
},
"fonts": {
"result": "clear",
"properties": {}
},
"originalDocumentPresent": {
"result": "clear",
"properties": {
"scan": "clear",
"screenshot": "clear",
"photoOfScreen": "clear",
"documentOnPrintedPaper": "clear"
}
},
"digitalTampering": {
"result": "clear",
"properties": {}
}
}
},
"compromisedDocument": {
"result": "clear",
"breakdown": {
"documentDatabase": {
"result": "clear",
"properties": {}
},
"repeatAttempts": {
"properties": {}
}
}
}
},
"visualAuthenticity": "clear"
}
},
"createdAt": "2024-12-26T15:40:55Z",
"updatedAt": "2024-12-26T15:42:10Z"
}
For more detailed field descriptions and response examples, see the providerSpecific element for Onfido in the API Reference.
inconclusive
Onfido processes are inconclusive when subResult is suspected. To know which breakdown caused the process to be inconclusive, you can check the breakdowns field.
Response example (expand/collapse)
{
"processId": "c0321717-ba80-468b-876c-006071a4b6ab",
"provider": "onfido",
"processType": "documentSelfie",
"status": "inconclusive",
"depictions": [
"front",
"selfie"
],
"providerSpecific": {
"documentVerification": {
"firstName": "WILLEKE LISELOTTE",
"lastName": "DE BRUIJN",
"gender": "F",
"nationality": "NLD",
"dateOfBirth": "1965-03-10",
"documentType": "passport",
"documentNumber": "SPECI2021",
"dateOfExpiry": "2031-08-30",
"issuingCountry": "NLD",
"dateOfIssue": "2021-08-30",
"placeOfBirth": "SPECIMEN",
"personalIdentificationNumber": "999999990",
"mrzLine1": "P<NLDDE<BRUIJN<<WILLEKE<LISELOTTE<<<<<<<<<<<",
"mrzLine2": "SPECI20142NLD6503101F2403096999999990<<<<<84",
"subResult": "suspected",
"ageValidation": "clear",
"dataConsistency": "clear",
"dataValidation": "consider",
"imageIntegrity": "clear",
"compromisedDocument": "consider",
"result": "consider",
"aliasName": "MOLENAAR",
"breakdowns": {
"issuingAuthority": {
"breakdown": {
"nfcActiveAuthentication": {
"properties": {}
},
"nfcPassiveAuthentication": {
"properties": {}
}
}
},
"imageIntegrity": {
"result": "clear",
"breakdown": {
"supportedDocument": {
"result": "clear",
"properties": {
"onfidoSupportedDocument": "clear",
"customSupportedDocument": "clear",
"issuingCountrySubjectToSanctions": "clear"
}
},
"colourPicture": {
"result": "clear",
"properties": {}
},
"imageQuality": {
"result": "clear",
"properties": {}
},
"conclusiveDocumentQuality": {
"result": "clear",
"properties": {
"cornerRemoved": "clear",
"abnormalDocumentFeatures": "clear",
"obscuredSecurityFeatures": "clear",
"watermarksDigitalTextOverlay": "clear",
"puncturedDocument": "clear",
"obscuredDataPoints": "clear",
"missingBack": "clear",
"digitalDocument": "clear"
}
}
}
},
"dataConsistency": {
"result": "clear",
"breakdown": {
"dateOfExpiry": {
"result": "clear",
"properties": {}
},
"lastName": {
"result": "clear",
"properties": {}
},
"firstName": {
"result": "clear",
"properties": {}
},
"nationality": {
"properties": {}
},
"gender": {
"result": "clear",
"properties": {}
},
"multipleDataSourcesPresent": {
"properties": {}
},
"documentType": {
"result": "clear",
"properties": {}
},
"issuingCountry": {
"result": "clear",
"properties": {}
},
"dateOfBirth": {
"result": "clear",
"properties": {}
},
"documentNumbers": {
"result": "clear",
"properties": {}
}
}
},
"dataComparison": {
"breakdown": {
"dateOfExpiry": {
"properties": {}
},
"lastName": {
"properties": {}
},
"firstName": {
"properties": {}
},
"gender": {
"properties": {}
},
"documentType": {
"properties": {}
},
"issuingCountry": {
"properties": {}
},
"dateOfBirth": {
"properties": {}
},
"documentNumbers": {
"properties": {}
}
}
},
"ageValidation": {
"result": "clear",
"breakdown": {
"minimumAcceptedAge": {
"result": "clear",
"properties": {}
}
}
},
"policeRecord": {},
"dataValidation": {
"result": "consider",
"breakdown": {
"expiryDate": {
"result": "clear",
"properties": {}
},
"mrz": {
"result": "clear",
"properties": {}
},
"gender": {
"result": "clear",
"properties": {}
},
"dateOfBirth": {
"result": "clear",
"properties": {}
},
"documentExpiration": {
"result": "consider",
"properties": {}
},
"barcode": {
"properties": {}
},
"documentNumbers": {
"result": "clear",
"properties": {}
}
}
},
"visualAuthenticity": {
"result": "clear",
"breakdown": {
"faceDetection": {
"result": "clear",
"properties": {}
},
"template": {
"result": "clear",
"properties": {}
},
"pictureFaceIntegrity": {
"result": "clear",
"properties": {}
},
"other": {
"result": "clear",
"properties": {}
},
"securityFeatures": {
"result": "clear",
"properties": {}
},
"fonts": {
"result": "clear",
"properties": {}
},
"originalDocumentPresent": {
"result": "clear",
"properties": {
"scan": "clear",
"screenshot": "clear",
"photoOfScreen": "clear",
"documentOnPrintedPaper": "clear"
}
},
"digitalTampering": {
"result": "clear",
"properties": {}
}
}
},
"compromisedDocument": {
"result": "consider",
"breakdown": {
"documentDatabase": {
"result": "consider",
"properties": {}
},
"repeatAttempts": {
"properties": {}
}
}
}
},
"visualAuthenticity": "clear"
},
"facialSimilarity": {
"result": "consider",
"imageIntegrity": "clear",
"faceComparison": "consider",
"visualAuthenticity": "clear",
"similarityScore": "low",
"breakdowns": {
"imageIntegrity": {
"result": "clear",
"breakdown": {
"faceDetected": {
"result": "clear",
"properties": {}
},
"sourceIntegrity": {
"result": "clear",
"properties": {}
}
}
},
"faceComparison": {
"result": "consider",
"breakdown": {
"faceMatch": {
"result": "consider",
"properties": {
"score": 0.3243,
"livePhotoId": "9bb44a2f-82f9-446b-9b07-65a0f7377fb4",
"documentId": "e974e10f-98d8-448c-a566-ec0256cb4575"
}
}
}
},
"visualAuthenticity": {
"result": "clear",
"breakdown": {
"spoofingDetection": {
"result": "clear",
"properties": {
"score": 0.6951
}
}
}
}
}
}
},
"createdAt": "2025-01-09T19:33:02Z",
"updatedAt": "2025-01-09T19:35:11Z"
}
-
For more detailed field descriptions and response examples, see the
providerSpecificelement for Onfido in the API Reference. -
To know more about each breakdown, check the Onfido documentation:
rejected
Onfido processes are rejected when subResult is rejected. To know what breakdown caused the process to be rejected, you can check the breakdowns field.
Response example (expand/collapse)
{
"processId": "bee4331f-5d43-43fe-9d28-e4a92409975c",
"provider": "onfido",
"processType": "documentSelfie",
"status": "rejected",
"depictions": [
"front",
"selfie"
],
"providerSpecific": {
"documentVerification": {
"subResult": "rejected",
"imageIntegrity": "consider",
"result": "consider",
"breakdowns": {
"imageIntegrity": {
"result": "consider",
"breakdown": {
"supportedDocument": {
"result": "clear",
"properties": {}
},
"imageQuality": {
"result": "unidentified",
"properties": {}
}
}
}
}
},
"facialSimilarity": {
"result": "clear",
"imageIntegrity": "clear",
"faceComparison": "clear",
"visualAuthenticity": "clear",
"similarityScore": "medium",
"breakdowns": {
"imageIntegrity": {
"result": "clear",
"breakdown": {
"faceDetected": {
"result": "clear",
"properties": {}
},
"sourceIntegrity": {
"result": "clear",
"properties": {}
}
}
},
"faceComparison": {
"result": "clear",
"breakdown": {
"faceMatch": {
"result": "clear",
"properties": {
"score": 0.6512,
"livePhotoId": "ad637140-ca35-47b6-9efb-94c544cdc151",
"documentId": "18a49575-ec7a-4328-afbc-23bbf511035b"
}
}
}
},
"visualAuthenticity": {
"result": "clear",
"breakdown": {
"spoofingDetection": {
"result": "clear",
"properties": {
"score": 0.9512
}
}
}
}
}
}
},
"createdAt": "2025-01-09T19:42:24Z",
"updatedAt": "2025-01-09T19:43:11Z"
}
-
For more detailed field descriptions and response examples, see the
providerSpecificelement for Onfido in the API Reference. -
To know more about each breakdown, check the Onfido documentation:
canceled
The identity verification process was cancelled by the end-user.
Response example (expand/collapse)
{
"status": "canceled",
"processId": "60ff4aff-90ab-4f99-bcb8-63553d243ff1",
"provider": "onfido",
"processType": "documentSelfie",
"createdAt": "2022-02-14T14:18:38Z",
"updatedAt": "2022-02-14T14:18:38Z",
"providerSpecific": {}
}
failed
A process gets the failed status if an error prevented the verification from completing. Examples could be time-out and server errors, expired tokens, validation errors etc.
Response example (expand/collapse)
{
"status": "failed",
"processId": "47d4021c-2744-4491-b0a7-b433345bfc74",
"provider": "onfido",
"processType": "documentSelfie",
"createdAt": "2022-02-14T14:04:58Z",
"updatedAt": "2022-02-14T14:05:06Z",
"failReason": {
"type": "upload_failed",
"message": "There was a validation error on this request (status code 422) | Field errors: {face_detection=[Multiple faces in image. Please note this validation can be disabled by setting the advanced_validation parameter to false.]}"
}
}
In this case, the end-user has tried to upload an image with multiple faces instead of taking a selfie. You can find more information about the failReason field in the API Reference.
Download full result
In the Get process response, you get the results for Onfido's breakdown listing (e.g. visualAuthenticity) in the provider-specific area. Information about the sub-breakdowns as they were obtained from the provider (e.g. "supported_document") is only returned in the provider's raw JSON result. This is available in a zip file obtained from the Download full result service.
You can always get a zip file for Onfido processes that have been completed with success.
Data files
document_verification.json
This "raw" file contains all information about the facial similarity report.
facial_similarity.json
This "raw" file is only retrieved if processType is documentSelfie or documentVideo. It contains all information about the document report.