Overview

The Assure API is a RESTful service that can be used to scan and verify identity documents using one more of the supported identity verification providers.

The purpose of the Assure API is to provide a simple way of integration that works in both browser and native mobile contexts and that supports asynchronous operations.

Introduction

Online identity assurance is the ability to determine the identity of a person on the Internet with an associated level of certainty. Ensuring that the person on the other end of the communication is who they claim to be is a fundamental principle for enabling relations that require higher levels of trust such as eCommerce, eGoverment or eBanking. Many institutions struggle with registering new customers due to the lack of trustworthy methods that are also easy to integrate and provide a good customer experience.

Digital onboarding offers challenges that face to face onboarding does not. Companies need to ensure who their customer is remotely and detect potential risks for diminishing the chance of being used for illegal activities, such as money-laundering, fraud or funding terrorism. For doing so, solutions such as Onfido and Electronic Identification (Electronic ID) are of great value. However, these solutions don’t offer a consistent quality cross-country, making the integration more complex for companies that need to identify people in different markets.

The Assure API tackles the problem of identifying unknown newcomers on the Internet by providing an agile and consistent manner for accessing these third-party providers.

Supported providers

The table below lists the third-party providers currently integrated in the Assure API. For details about using each of these providers, please refer to the Provider Details section below.

Third party provider
Onfido
Electronic Identification (eID)

Key Concepts

Identity Verification Provider

Third-party provider that performs the electronic verification of a person’s identity document.

End-user

The person whose identity will be verified/looked up (i.e. the “applicant”).

Service Provider

The entity who will integrate with the Assure API.

Verification request 

The action of verifying the end-user’s identity using one of the identity verification providers.

Result

The information returned by the identity verification provider with the outcome of the verification request.
This result is normalized by the Assure API and part of a process.

Process

A resource of the Assure API.
A container for all the information associated to a verification request. Must be created by the service provider using the Assure API.

Dossier

A resource of the Assure API.
A container for all the information regarding all processes. Must be created by the service provider using the Assure API.

The image below depicts the entity relationship model of the Assure API:

Privacy and Data Policy

The current version of the Assure API safeguards, on behalf of the customer, the identity document verification results for an undetermined amount of time. Nevertheless, the data owner (customer) can call the API to delete the respective Personally Identifiable Information (PII) of the process. PII will be completely redacted and the process marked as deleted.

Getting Started

Accessing the API

Please refer to the documentation on Accessing Signicat REST Services.

Reference Documentation

For detailed reference documentation on the API and test examples please refer to the Assure API Swagger Documentation page.

Using the API

The Assure API is used to perform identity verification using an ID document.

The basic flow for doing that can be summed up as follows:

  1. Initial setup – Set up the necessary resources (Dossiers and Processes). At least one Dossier and one Process should be created.
  2. Upload ID images – Upload images of the ID document and of the end-user. This can either be done by integrating with the provider’s SDK or through the Assure API. Please refer to the Upload ID images section for details.
  3. Call for verification – Send a request for the identity verification to be performed.
  4. Get result – Obtain the result of that verification. This can either be done synchronously – by requesting the current result – or asynchronously – by waiting for a callback notification with the final result.

The steps below contain detailed descriptions of each part of the flow above.
Each step has links to the Assure API Swagger documentation, where you will find all the technical details and can try out the API for yourself.

Step 1: Initial Setup
1.1 – Create a dossier

After obtaining an access token to access the Assure API, the first thing thing you need to do is create a dossier.

After creating a dossier, you can see all of its contents anytime you want to.

Note that there should be one dossier for each end-user (i.e. you should not use the same dossier for different end-users).

1.2 – Create a new process

Now that you have a dossier, you can create one or more processes inside it.

When creating a new process, you must specify which identity verification provider you want to use to perform the document verification.
You must also specify what type of document will be used.

Depending on the provider, some of the other fields in the request body may also be required.

Information about this process will be kept inside the dossier.

You can also check out the full contents of a process at any time.

Step 2: Upload ID images

At this point, you need to upload images of the ID document and of the end-user. You can either do it directly to the provider by integrating with their SDK (2.1) or you can do it through the Assure API (2.2). Please refer to the section about uploading ID images for more details.

Regardless the approach used for sending the ID information, you can always check the images after they were uploaded:

Option 2.1 – Use the provider’s SDK for capturing and uploading images

To supply the provider with the necessary ID information, you can integrate the provider’s iOS/Android/JS (Web) SDK and use their tools to capture and upload the ID data.

If you are using this approach, you must use the “authorization” token that was retrieved in the Create Process response body (see Step 1.2 above).

Option 2.2 – Upload the images through the API

As an alternative to using the provider’s SDK, you can send the images by using the Set Image endpoint of the Assure API.

Note that, in this case, the images must already exist and that not all providers support this approach (see section about uploading id images for more details).

If you are using this approach:

Step 3: Call for verification

Now that all the necessary information has been provided, you can request the identity verification to be performed.

Note: If you want to receive a notification from the Assure API when the verification is completed, you must include a “notificationUrl” and an “authorizationHeader” in this request’s body. Check out the Swagger model for this request body for more information.

Important: After this point, no more images should be uploaded to the provider (Step 2). If it is necessary to change the images, you should create a new process and upload the images using the new “processId“.

Step 4: Get result

All identity verification results will be stored in the process. Some providers may return some information as soon as the request to start the verification is performed (Step 3). Others require a manual approval to be performed before a final result is obtained, which will mean that another part of the information can only be obtained after some time.

The Assure API supports this asynchronous behavior by updating the process with the result information as it is received from the provider.

So, in order to get the final information about an identity verification process, you can either explicitly ask for information about the result (4.1) and/or wait to be notified when a final result has been obtained (4.2).

For details about the process structure and the information it may contain please refer to the section below about “Process Details”.

Option 4.1 – Ask for result

Look at the process information by calling the Get Process endpoint

If the process status is “completed” that means the information in the process is final and there will be no more changes.

Option 4.2 – Get a notification from the Assure API

In addition or as an alternative to asking for the result, you can request to be notified when a final result has been obtained.

Integration Details

Uploading ID Images

During the process of performing an identity verification it is required to provide images of the id document and of the end user (Step 2 above).

This can be done either by uploading the images using the Assure API or by using the provider’s SDKs to capture and upload the images.

The table below summarizes which approaches are supported by each provider, how they can be used (availability) and the advantages/disadvantages of each approach:

Direct upload using Assure API Use provider’s SDK to capture and upload images
Web SDK(1) iOS SDK Android SDK
Onfido
Electronic ID

(1) Also available through the Assure API. Check the “Details for using the Start Web Flow SDK Endpoint” section below.

Direct upload using the Assure API

To use this approach, use the Set Image endpoint to upload the images.

Using this approach will make the integration simpler. Note that it is not available for all providers and the images must be provided to the API (i.e. they must have already been captured/digitalized).

Using the provider’s SDKs to capture and upload the images

To use this approach you must integrate with the provider’s SDKs. An exception to this will be if you decide to use the Assure API’s Start Web Flow SDK endpoint – this endpoint automatically integrates with the provider’s JS (Web) SDK (see details below).

Because the SDKs help the end-user capture and upload the images, using the provider’s SDKs may also help guarantee a better quality of those images (and thus, a better quality of the positive results).

An advantage of integrating with the provider’s SDKs directly is that you will get a single solution for uploading the images for all providers and all environments (iOS/Android/JS (Web)).

Details for using the Start Web Flow SDK Endpoint

The Assure API provides an endpoint to seamlessly use the provider’s JS (Web) SDK to capture and upload the ID images. This way you can still use the provider’s SDK without having to integrate with it – you will just use the Assure API.

Because this endpoint creates a new process by itself, the basic flow of the Assure API will be as described below:

  1. Setup
    • Create a new dossier
    • Call the Start Web SDK endpoint (instead of creating a new process)
  2. Upload images
    • Use the provider’s web SDK to capture and upload images (it will be automatically launched in a web view)
  3. Call for verification
    • No need to do this – it will be done automatically.
  4. Get result
    • (same as in the basic flow) Wait for the notification or call the Get Process endpoint.

Process Details

Because the Assure API supports asynchronous behavior, the data on a process will be updated as the results sent by the identity verification providers are obtained.

The sections below provide information about the data, which changes will occur and when.

Process structure

This section explains the structure of a process. The Swagger docs about the Get Process also provide important details on this structure and the information it contains.

The structure of a process changes over time and is divided into 3 main areas:

1. Process information

The elements in this area are generated as soon as the process is created:

2. Provider-dependent information about the result
Provider Process JSON elements
Onfido
  • ocr
  • “manualApproval”
Electronic ID
  • “facialSimilarity”
  • “documentVerification”
3. Uniformized result

The element in this area will only exist if the verification was accepted, i.e. after the verification is completed and the final status of the process is “accepted” (see the section about the process status for more information).

  • This element will always have the same name (“finalResult“) and its structure will always be the same, regardless the provider being used to perform the verification.
  • Its contents will be a normalized (same formats) and uniform (same elements – e.g. firstNamelastNamedateOfBirth) summary of the information collected from the provider.

Example:

"finalResult": {
    "firstName": "MARIA PAULA",
    "lastName": "SMITH JONES",
    "dateOfExpiry": "2024-03-02",
    "gender": "F",
    "nationality": "NOR",
    "documentType": "passport",
    "documentNumber": "CA422356",
    "issuingCountry": "PRT",
    "dateOfBirth": "1979-09-19",
    "similarityScore": "high"
  }
Process Status

The value of the “status” element in the information in the process will change during the process. Its final value will depend on the result of the verification, as mapped in the following table:

Status type Status Value Description
Not Completed “pending” The process has been created by the verification has not yet started.
“processing” The verification of the data in the process has started but is not yet finished.
Completed “accepted” The verification is finished and was accepted (i.e. the data is valid).
“rejected” The verification is finished and was rejected (i.e. the data is not valid).
“inconclusive” The verification is finished but was inconclusive (i.e. the data might not be valid).
“canceled” The verification is finished because it was canceled by the end-user.

Provider Details

In this section you can find some details about each of the currently supported providers.

Provider Alias Integration details
Onfido onfido
  • When creating a process:
    • Requires “firstName” and “lastName” to also be sent in the request body.
    • Uses the rest of the information that can be sent in the request body (e.g. “nationality“, “address“, etc.) to improve the quality of the identity verification.
Electronic ID eid
  • When getting an image
    • Allows retrieval of a “portrait” image – the portrait image in the ID document that was uploaded.

Integration Guides

The links below provide useful examples of how to integrate with the Assure API for different use cases: