Overview

The Assure API is a RESTful service that allows scanning and verifying an id document 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 of determining 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 remotely ensure who their customer is and detect potential risks for diminishing the chance of being used for illegal activities, such as money-laundry, fraud or funding terrorism. KYC (Know Your Customer) guidelines rely on procedures such as collecting and validating identification documents and looking up if those identities are present on sanctions and PEP (Politically Exposed Person) lists. 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 on 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.

Key Concepts

Identity Verification Provider

Third-party provider that allows performing an electronic verification of a person’s identity document (see the full list of currently supported providers below).

End User

The person whose identity will be verified.

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 will be normalized by the Assure API and included as part of a process.

Process 

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

Dossier 

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

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

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

Performing an Identity Verification Using an ID Document

This section contains a detailed step by step description on how to perform an identity document verification from start to finish.
Each step contains links to the Assure API Swagger documentation, where you will find all the technical details and can try out the API for yourself.

The image below gives an overview of a basic flow when using the Assure API to perform an identity verification using an id document:

First you need to create a new dossier and a new process inside it. Then, you must upload the id document to the identity verification provider and, finally, request for the identity verification to be performed.

In the end you will be able to see the result of that verification inside the process.

Step 1: Create a dossier

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

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

Step2: Create a new process

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

When creating a new process you must specify which identity verification provider you want to use for later performing the document verification and what type of document will be used – these fields are always mandatory. Depending on the provider, some of the other fields in the request body can also be required. Apart from these, you can also include information about the end user (ex: “first name”, last name”, “gender”, “nationality”), but only some providers will make use of it (see section about the providers for more details).

Information about this process will be kept inside the dossier.

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

Step 3: Upload the ID document’s images

At this point, you need to upload the id document’s images to the identity verification provider. Depending on the provider, you can either do it directly using their SDK and/or you can do it using the Assure API. Please refer to the section about the providers for more details.

If you are using the provider’s SDK to upload the images:

If you are using the API to upload the images:

You can always check the images that have already been uploaded to the provider, regardless they were uploaded through the API or using the provider’s SDK.

Step 4: Start the verification

Now that the process contains all the necessary information, you can request for the identity verification to be performed.

Important: After this point you should not upload any more images to the provider. If necessary, you should create a new process and upload the images using that new “processId“.

Step 5: Getting the verification results

All results relative to the identity verification will be stored within the process. Some of the identity verification providers will return some information as soon as the start verification request is performed (Step 4). But they can also require a manual approval to be performed, which will imply 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 shared by the provider.

Thus, in order to get the final information about an identity verification process you can either

1) Keep looking at the process information by calling the Get Process endpoint

or you can also

2) Get a notification from the Assure API

For more details about the Process structure and the information it contains please refer to the section below about “Process Details”.

Lookup in PEP/Sanctions lists

To help you “Know Your Customer” (KYC) and be compliant to the European Union’s Anti Money Laundry (AML) directives, the Assure API provides a lookup endpoint that allows you to check if a person is present in PEP or Sanctions lists.

Checkout Swagger for more details on this lookup endpoint.

Please refer to the section below to see the list of third-party providers currently integrated in the Assure API that allow performing this check over PEP/Sanctions lists.

Detailed Information

Process Details

Because the Assure API support asynchronous behavior, the information on a process will be updated (see section “Process Structure“) as the results sent by the identity verification providers are obtained (see the section about the process status).

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 overtime and is divided into 3 main areas:

Structure example for Electronic ID Structure example for Onfido

 

1. Process information

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

2. Provider-dependent information about the result

The elements in this area will only be generated after the verification is started and after the identity verification providers have shared that information with the Assure API:

3. Normalized 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).

"finalResult": {
    "firstName": "MARIA PAULA",
    "lastName": "SMITH REYNOLDS",
    "dateOfExpiry": "2024-03-02",
    "gender": "F",
    "nationality": "PRT",
    "documentType": "passport",
    "documentNumber": "CA423556",
    "issuingCountry": "PRT",
    "dateOfBirth": "1989-09-09",
    "similarityScore": "high"
  }
Process Status

The information in the process includes a “status” property.

Its value will change during time and its final value will depend on the result of the verification, as mapped by the following table:

Status Type Status Value Description
Not Completed “pending” The process has been created but 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.

 

List of Supported Providers

The table below lists all the third-party providers currently integrated in the Assure API, which service they provide and some details on that service:

Third party provider Services provided ID Document Upload Process elements specific to this provider Notes
Onfido Identity Verification Through API or provider’s SDK
  • “ocr”
  • “manualApproval”
  • 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 (ex: “nationality”, “address”, etc) to improve the quality of the identity verification.
Electronic Identification (eID) Identity Verification Through provider’s SDK only.
  • “facialSimilarity”
  • “documentVerification”
  • When getting an image
    • Allows retrieving a “portrait” image – the portrait image in the id document that was uploaded
Trapets PEP/Sanctions lookup N/A N/A