Developer Pages

# Onfido

Page contents

# Supported features

Onfido (opens new window) 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
  • NFC reading of ID document's chip (beta)

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

Note

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.

Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide
Slideshow slide

After the verification is finished, you can call the Get process (opens new window) 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, i.e. 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 click-to-zoom

The colour codes illustrate the flow decision:

  • Green = Must
  • Grey = Optional
  • White = Not used

# Step A: Create dossier

  • Use the Create dossier (opens new window) endpoint to create a placeholder for all of your end-user’s data.
  • Save the dossierId you get in the response to be used in the next requests.

Note:

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 (opens new window) 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 (opens new window) endpoint to create an identity verification process in that dossier. Ensure you give it the dossierId you got in the Create dossier response. Also, enter the Onfido provider in the request body. Here is an example JSON request body:
{
    "provider": "onfido",
    "processType": "documentSelfie",
    "documentType": "passport",
    "notificationUrl": "https://webhook.site/#!/705bcdd5-72dc-4018-832f-5b64ba26b5d8",
    "processParameters": {
        "location": {
            "countryOfResidence": "PRT"
        }
    }
}

  • 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 will get a notification (in the provided URL) when the process is finished. If you need a notification URL for testing, you can use one of the following options:

  • You must Save the processId from the response to use on the next steps.

# 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 (opens new window) endpoint.

There are two ways you can set the location, either via countryOfResidence or ipAddress:

Location from country of residence:

{
    "processParameters": {
        "location": {
            "countryOfResidence": "PRT"
        }
    }
}

Location from IP address:

{
    "processParameters": {
        "location": {
            "ipAddress": "176.78.162.201
        }
    }
}

Important

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 (opens new window) 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 OpenAPI docs under Create process > processParameters (opens new window).

If an end-user is a US resident, they must consent to the collection, use, and handling of biometric identifiers and information by Onfido.

Note

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 (opens new window), Onfido Privacy Policy (opens new window) and Onfido Terms of Service (opens new window).” 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 (opens new window) endpoint.

Important

Sending the privacy consent as true means that the end-user has read Onfido’s Privacy notices and consent (opens new window) 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 OpenAPI docs under Create process > processParameters (opens new window).

# Step D2: Upload images

# Step E: Start verification

  • Extra optional step: Before requesting the verification to start, you may want to call Get process (opens new window) to get the following process info:
    • The provider is”onfido”
    • The status is “pending”
  • Wait for the callback notification

Important

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

After you get the notification in the URL you provided in step C, you know that the verification result is ready.

The process now contains data about the process’ final result. For more details about how to use the Get process endpoint, 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 click-to-zoom

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.

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

Main aim of Onfido's user interface:

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

# Integration steps overview

This diagram provides an abstraction of the client-side implementation.

Onfido SDK process diagram click-to-zoom

The next sections describe all the necessary steps, including the integration with Assure before and after the Onfido SDK integration in step 3:

  1. Create a dossier.
  2. Create a process.
  3. Integrate with the Onfido mobile SDK to check the ID document.
  4. Start verification.
  5. Get result.

Note:

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

Note:

Ensure you use one dossier per end-user.

# Create a process

To be able to create a process (opens new window), you need to get some information from your mobile app, send it to your backend server and afterwards to the Assure API.

Tips:

  • processType: The value depends on the check you are doing. If it is just a document check, you should use document. If you're using also face comparison, you should use documentSelfie (if using a photograph) or documentVideo if 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 request:

{
    "provider": "onfido",
    "processType": "document",
    "notificationUrl": "https://mycallback-url.com",
    "processParameters": {
        "mobileAppId": "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:

# 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 (opens new window) 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. Assure API will process the results and send a callback to the notificationUrl you defined in the createProcess call. The callback has no personal information, so you can call the Get process (opens new window) endpoint to get the full information about the process.

For result examples, see Onfido results..

Download full result

You can also get a zip file with the packaged process by calling the Download full result (opens new window) endpoint. For more information, see Download full result.

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

# Onfido native SDK

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 OpenAPI documentation for either Create (opens new window) or Update capture configuration (opens new window).

# Get process

This section describes the final result statuses for Onfido. For a more general description of how the "Get process" endpoint works, see Service details > Get process and the API reference (opens new window).

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

Assure API's "final status" Onfido result: documentVerification Onfido result: facialSimilarity
accepted The ID is valid. The faces match.
rejected The ID is not valid. (any)
inconclusive The ID is valid but suspicious. (any)
inconclusive (any) At least one of the facialSimilarity verifications did not succeed.
# Process types

Process types for Onfido are:

  • document
  • documentSelfie
  • documentVideo

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 OpenAPI docs (opens new window).

# accepted

The status is accepted when all underlying verifications have passed. This means there are no indications the document is fraudulent.

This is a response example of an Onfido process that was accepted:

    {
        "provider": "onfido",
        "status": "accepted",
        "processId": "4e48363a-37cb-4cff-8f91-afc9e52271fc",
        "createdAt": "2019-09-19T22:10:56Z",
        "updatedAt": "2019-09-19T22:11:23Z",
        "finalResult": {
            "firstName": "MARIA PAULA",
            "lastName": "SANTOS MENDES",
            "dateOfExpiry": "2020-07-08",
            "gender": "F",
            "nationality": "PRT",
            "documentType": "identityCard",
            "documentNumber": "1234567890",
            "issuingCountry": "PRT",
            "dateOfBirth": "2002-04-29",
            "similarityScore": "high"
        },
        "providerSpecific": {
            "facialSimilarity": {
                "result": "clear",
                "imageIntegrity": "clear",
                "faceComparison": "clear",
                "visualAuthenticity": "clear",
                "similarityScore": "high"
            },
            "documentVerification": {
                "lastName": "SANTOS MENDES",
                "dateOfExpiry": "2020-07-08",
                "subResult": "clear",
                "dataConsistency": "clear",
                "gender": "F",
                "documentType": "identityCard",
                "documentNumber": "1234567890",
                "dateOfBirth": "2002-04-29",
                "ageValidation": "clear",
                "policeRecord": "clear",
                "dataValidation": "clear",
                "result": "clear",
                "firstName": "MARIA PAULA",
                "imageIntegrity": "clear",
                "nationality": "PRT",
                "issuingCountry": "PRT",
                "dataComparison": "clear",
                "visualAuthenticity": "clear",
                "compromisedDocument": "clear",
                "mrzLine1": "I<PRT122336694<ZY42<<<<<<<<<<<",
                "mrzLine2": "8302304F21207081PRT<<<<<<<<<<<6"
            }
        }
    }

In this example, clear is passed as value in the result and sub-result fields, which means all the underlying verifications have passed.

For more detailed field and value descriptions, see the providerSpecificelements for Onfido, i.e. facialSimilarity and documentVerification, in the Open API documentation > Get process (opens new window).

# inconclusive

A process can get the inconclusive status if one of the facial similarity verifications did not succeed or if the document is suspected to be fraudulent.

This is a response example of an Onfido process that was inconclusive:

    {
        "provider": "onfido",
        "status": "inconclusive",
        "processId": "85210241-4e70-4451-8ea3-7cd3c4d8843a",
        "createdAt": "2019-09-23T10:05:53Z",
        "updatedAt": "2019-09-23T10:09:49Z",
        "providerSpecific": {
            "facialSimilarity": {
                "result": "consider",
                "similarityScore": "high"
            },
            "documentVerification": {
                "lastName": "SPECIMEN",
                "dateOfExpiry": "2024-11-01",
                "subResult": "suspected",
                "gender": "F",
                "documentType": "passport",
                "documentNumber": "00000000",
                "dateOfBirth": "2002-04-29",
                "result": "consider",
                "firstName": "LAERKE OEYVOR AASE",
                "nationality": "NOR",
                "issuingCountry": "NOR",
                "mrzLine1": "PVNORSPECIMEN<<LAERKE<OEYVOR<AASE<<<<<<<<<<<",
                "mrzLine2": "00000000<0NOR7505319F24110154197505311234586"
            }
        }
    }

In this example some of the underlying verifications has passed the valuesconsider and suspected.

An inconclusive result does not contain a finalResult element but contains some data obtained from the document.

See the following sub-sections for more details about the inconclusive reasons.

# Facial similarity verification (inconclusive)

At least one of the facialSimilarity verifications did not succeed. Reasons for this can be:

  • The quality and integrity of the uploaded files were not sufficient to perform a face comparison (imageIntegrity).
  • The face in the document does not match the face in the selfie/video (faceComparison).
  • The person in the selfie/video is not real, or no liveness was detected (visualAuthenticity).

For more details, see Onfido's provider specific element, facialSimilarity in the OpenAPI documentation (opens new window).

# Suspected fraud (inconclusive)

It could also be that the document is suspected to be fraudulent, for example:

  • One or more validatable elements are incorrect, e.g. date of birth, expiry date etc. (dataValidation).
  • One or more visual elements are incorrect, e.g. it is a photo of a printed photo, the security features are not present etc. (visualAuthenticity).
  • The document is registered in Onfido's database as a compromised document (compromisedDocument).
  • The data in the document is not consistent, e.g. between the MRZ lines and the OCR extracted text on passport for expiry date, birth date etc. (dataConsistency).
  • The document is reported as stolen etc. (policeRecord).

For more detailed field and value descriptions, see Onfido's provider specific element, documentVerification, in the OpenAPI documentation (opens new window).

# rejected

The verification cannot be processed further. Reasons for this may for example be poor image quality (imageIntegrity), unknown document type (documentType), the end-user is below the minimum accepted age (ageValidation) etc.

This is a response example of an Onfido process that was rejected:

    {
        "provider": "onfido",
        "status": "rejected",
        "processId": "88d490a0-7184-4aba-804d-4dac400f5660",
        "createdAt": "2019-09-23T15:43:37Z",
        "updatedAt": "2019-09-23T15:46:30Z",
        "providerSpecific": {
            "facialSimilarity": {
                "result": "consider",
                "similarityScore": "medium"
            },
            "documentVerification": {
                "result": "consider",
                "subResult": "rejected",
                "documentType": "unknown"
            }
        }
    }

A rejected result does not contain a finalResult element. Also, the provider-specific elements are few since there will probably be little data obtained from the document.

For more details, see Onfido's provider specific elements, imageIntegrity, documentTypeand ageComparison in the OpenAPI documentation (opens new window).

# canceled

The verification was canceled (by the end-user).

{
    "status": "canceled",
    "processId": "60ff4aff-90ab-4f99-bcb8-63553d243ff1",
    "provider": "onfido",
    "processType": "documentSelfie",
    "notificationUrl": "https://webhook.site/#!/705bcdd5-72dc-4018-832f-5b64ba26b5d8",
    "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.

This is a response example of an Onfido process that failed:

{
    "status": "failed",
    "processId": "47d4021c-2744-4491-b0a7-b433345bfc74",
    "provider": "onfido",
    "processType": "documentSelfie",
    "notificationUrl": "https://webhook.site/#!/705bcdd5-72dc-4018-832f-5b64ba26b5d8",
    "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 OpenAPI documentation (opens new window).

# 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 (see code example below). Information about the sub-breakdowns as it was 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 (opens new window) service.

For a more general description of how the Get process endpoint works, see Other services and endpoints > Get process.

Last updated: 30/05/2023 08:22 UTC

← ReadID →