# Onfido

Page contents

Supported features
User flow example
Integration use cases for Onfido
- UC 1: Use Onfido and integrate only with Assure API (web or mobile usage)
- UC 2: Use Onfido and integrate with Onfido's SDK (web or mobile usage)
SDKs

Onfido (opens new window) is a third party eIDV provider integrated with Assure API.

# Supported features

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 done the initial integration steps with the Assure API, i.e. set up client credentials and OIDC token. It also assumes you have set up the dossier, process and configured the provider. The example screens correspond to Use case 1 > step D1 described below where the provider's SDK is launched:

After the verification is finished, you can call the Get process endpoint to inspect the final result (see step F in Use case 2 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 OIDC token.

In the following, we present the two most common use cases for Onfido:

Integrate with only the Assure API
Integrate using the Onfido SDK

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 differences in step C and D.

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

click-to-zoom

The colour codes illustrate the flow decision:

Green = Must
Grey = Optional
White = Not used

# Step A: Create dossier

Save the dossierId from the response body to use on the next requests.

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

# Step C: Create process

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.

Important

In order to receive notifications in production, you must request Signicat to whitelist your URL. To get help with this, send an email to support@signicat.com.

To perform tests in pre-production, use one of the following options:

Webhook URL (opens new window) (see the above code example)
Hookbin (opens new window)

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

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.

# Step D2: Upload images

This JSON example file contains specimen images of a Norwegian passport and a selfie: NOR_passport-specimen_and_selfie.json (opens new window)

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

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

Call the Get process endpoint: Use the dossierId and processId in the callback notification.

The process now contains data about the process’ final result (for more information, see Get process > Onfido results).

For more information about the provider-specific information in the Get process response, see the Get process endpoint description.

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

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.

# SDKs

The aim of this topic is to help a developer integrating with the Assure API using Onfido's 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 in the Assure Integration guide.

# Requirements

Before you start the SDK integration, you should be aware of the following requirements for Onfido's SDKs:

We advice you to always use the latest Onfido SDK version. For more information about the minimum required version, see Onfido Privacy notices and consent (US) (opens new window).
Check the supported device versions in Onfido's official documentation (opens new window).
The app needs camera and microphone permission.
Your app must always communicate with your own server and never directly with the Assure API. See more details about this requirement and other recommendations on the developer pages.
Since you are integrating with the Assure API in a native app context, you should choose the eIDV generic flow.

# Mobile SDKs (Android and iOS)

The aim of this topic is to help a developer integrating with the Assure API using FaceTec's iOS and Android SDK.

# Integration steps overview

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

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 (Use case 2 above also includes some optional steps).

Here is an overview of all the necessary steps:

Create a dossier.
Create a process.
Integrate with the Onfido mobile SDK to check the ID document.
Start verification.
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

Use the Create dossier endpoint to create a placeholder for all of your end-user’s data.
Save the dossierId you get in the response.

Note:

Ensure you use one dossier per end-user.

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

Use the Create process endpoint to create an identity verification process in the dossier.

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

# Web SDK

More information will follow soon.

← FaceTec ReadID →

# Onfido

# Supported features

# User flow example

# Integration use cases for Onfido

# UC 1: Use Onfido and integrate only with Assure API (web or mobile usage)

# Step A: Create dossier

# Step B: Get document types (optional)

# Step C: Create process

# Location

# Onfido privacy consent

# Step D2: Upload images

# Step E: Start verification

# Step F: Get process

# UC 2: Use Onfido and integrate with Onfido's SDK (web or mobile usage)

# SDKs

# Requirements

# Mobile SDKs (Android and iOS)

# Integration steps overview

# Create a dossier

# Create a process

# Integrate with the Onfido mobile SDK to check the ID document

# Start verification

# Get result

# Web SDK