Identity verification

Assure API integration details

277 views December 3, 2019 December 13, 2019 0

Here you will find detailed information about how to use the Assure API. For the API description, go here.

Getting started

At this point we assume you already know your client_id and client_secret and also have the access token (further referred to as <OIDC_ACCESS_TOKEN>) that is required for calling each endpoint.

It is also assumed that you have access to the Assure API at some <ENVIRONMENT> (ex: https://preprod.signicat.com).

If you do not have this information, please contact Signicat support.

API reference documentation

For detailed API reference documentation, please check the Assure API Reference page.

Documentation of third party provider SDKs

For detailed documentation on how to use the third party provider’s SDK’s, please check the Third-Party Providers’ SDKs page.

Integration details – identity document verification

In the API reference docs you have a list of supported providers and an overview of the flows for performing identity document verification. In this document you will find all possible alternatives to do that and detailed information on each step.

The image below presents all possible paths to integrate with the Assure API for validating a person’s identity using an ID document.

The recommended integration path is: A > B > C > D1 > E > F. This path is the only one that can be used to integrate with any provider in any environment. Also, because in this path the provider’s SDK will be used to capture and upload the images, it’s more likely you will obtain better quality of the final result.

One alternative path is A > B > C > D2 > E > F. The advantage will be not having to integrate with the provider’s SDK. However, this option is only available for Onfido. Also, since the ID images will not be captured using the provider’s SDK, the verification result quality may suffer.

Another alternative path is A > G > F. Because this is an encapsulation of the provider’s Web SDKs into the Assure API, it has the same advantage as the recommended path above regarding the quality of the final result. However, this is only available when integrating in a web environment (also meaning it will not be available for Read ID, which has no support for web).

Step A: Create Dossier

Use the Create Dossier endpoint to create a new dossier:

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

When is it necessary to create a Dossier?

A Dossier should contain information about only one end user. This means that a dossier should be created for each new end user.

Step B: Get Document Types

The Get Document Types endpoint returns a list of all the ID documents supported on each country by a given provider.

We recommend that you use this service and keep the results for further usage. Not all paths/providers require that you use this information but it will most likely be useful to know.

curl -X GET \
  <ENVIRONMENT>/assure/eid/document-types \
  -H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <>' \

Step C: Create Process

Use the Create Process endpoint to create a new process inside the dossier:

curl -X POST \
  <ENVIRONMENT>/assure/dossiers/<DOSSIER_ID>/processes \
  -H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
     "provider": "onfido",
     "documentType": "passport",
     "notificationUrl": "https://mycallback-url.com",
     "authorizationHeader": "Token xSUNmskaIUGh9hn5B7bKJbNOho"
   }'

Make sure to:

  • Use the “dossierId” from the previous step (<DOSSIER_ID>).
  • Set the “provider” with the alias of the provider you want to perform the verification.

If you are going to use the Assure API to upload the images, you must also indicate:

If you want to later receive a notification that the verification is finished, you must also indicate:

  • The “notificationUrl” – A url where a callback notification will be sent as soon as the verification is finished.
  • The “authorizationHeader” – This will add an “Authorization” header to the request that is sent to the “notificationUrl“).

Depending on the provider you will use to perform the verification there may be other mandatory and optional parameters. Please refer to the Create Process endpoint documentation for details and to the use cases page for specific usage examples.

After creating the process you must:

  • Save the processId;
  • Save the “authorization” token from the response body (required if you’re going to use the provider’s SDK on Step 2).

Information about this process will be kept and can be obtained at any time.

  • Use the “dossierId” and “processId” to Get Process and see all the information currently available inside that process.

When should I create a new process?

At least one process must be created to perform a verification request.
If you want to repeat the verification, use a different provider, use a different identity document, or upload the images you must create a new process with those specifications.
Just remember that all processes in a dossier must belong to the same end user.

Steps D: Upload images

At this point you will need to upload the identity document’s images to the provider. You can either do that by using their SDKs to capture and upload the images (Step D1: Launch provider’s SDK) or you can upload images you already have through the Assure API (Step D2: Upload images).

Step D1: Launch provider’s SDK

To use the provider’s SDK to capture and upload the ID images you must launch the provider’s SDK in your web/mobile app.

For details on how to do this for each provider and SDK, please refer to Third-Party Providers’ SDKs documentation.

You will need to provide the SDK the “authorization” token that you saved from the Create Process response body (Step C: Create Process).

Note: If you are creating a web app and want to use the provider’s SDK but prefer to avoid having to integrate with it yourself, check Step G: Start Web flow for an alternative.

You can always obtain the images after they have been uploaded – just use the Get Image endpoint.

Step D2: Upload images

Attention: If you are using this approach, you must specify the “documentType” when you created the process (Step C: Create Process).

As an alternative to using the provider’s SDK to capture and upload the images, you can simply send the images using the Set Image endpoint of the Assure API. However, the images must have already been captured and not all providers support this approach. Also note that this step is an alternative to the previous one and is not part of the recommended path.

To take this approach, use the Set Images endpoint:

curl -X POST \
  <ENVIRONMENT>/assure/dossiers/<DOSSIER_ID>/processes/<PROCESS_ID> \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
      "front": "data:image/jpeg;base64,/9j/4AAQS",
      "back": "data:image/jpeg;base64,/9j/4AAQS",
      "selfie" : "data:image/jpeg;base64,/9j/4AAQS"
  }'

Make sure to:

  • Use the “dossierId” (<DOSSIER_ID>) and “processId” (<PROCESS_ID>) from the previous steps.
  • Use PNG or JPEG images. Also, they must be sent in dataURL format (you can use websites such as this one to convert them).

You can upload one image at a time or multiple images at once. If you upload the same type of image (“front“, “back“, “selfie“) more than once, only the last one will be kept.

Before proceeding to the next step (Step E: Start verification) you must provide at least the “front” and “selfie” images. The “back” image only needs to be sent if the document has two sides (ex: driver’s license).

You can always obtain the images after they have been uploaded – just use the Get Image endpoint.

Step E: Start verification

After the images were uploaded, you must tell the Assure API to request the provider to perform the verification of the provided data.

To do that, call the Start Verification endpoint:

curl -X POST \
  <ENVIRONMENT>/assure/dossiers/<DOSSIER_ID>/processes/<PROCESS_ID> \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \

Make sure to use the “dossierId” (<DOSSIER_ID>) and “processId” (<PROCESS_ID>) from the previous steps.

Note: Read ID provider does not require that you explicitly start the verification – it will automatically start after the images have been uploaded.
If you are performing an Electronic ID “attended” process, you also do not have to do this step.

Step F: Get Process

After being requested to perform the verification, the provider will asynchronously send a response with the result.

When the response arrives, you will be able to check the full result of the identity verification using the Get Process endpoint:

curl -X GET \
  <ENVIRONMENT>/assure/dossiers/<DOSSIER_ID>/processes/<PROCESS_ID> \
  -H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
  -H 'Accept: application/json' \

You will get all the process and result information in the response body. Please refer to the Get Process service details documentation for more information about the contents of this response.

How do I know that a verification is finished?
You can request to be notified when the final result is available.
You can also just keep checking the information in the process – when the process’s status matches one of the completed process status that means the verification is finished.

Remember that, if you want to be notified when a verification is finished, you must register during Step C: Create Process.

What happens if I Get Process before the verification is finished?
You will get the information about the process that is available at that time.
Some providers supply information even before the verification is finished. For example, Electronic ID will supply information obtained by the OCR as soon as the ID images are uploaded.
The Assure API ensures that all data is added to the process as soon as it is received from the providers, regardless the final result has been received or not.

Step G: Start Web flow

The Assure API provides a service that encapsulates not only the providers’ web SDK’s but also some of the steps of the basic path (Step B: Get Document TypesStep C: Create ProcessStep D1: Launch provider’s SDK and Step E: Start verification).

Available only for Web usage
The Start Web SDK Flow service can only be used when you are using the Assure API in a web environment.

To use this service, call the Start Web SDK Flow endpoint:

curl -X POST \
  <ENVIRONMENT>/assure/dossiers/<DOSSIER_ID>/processes/<PROCESS_ID> \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
      "provider": "onfido",
      "redirectUrl": "https://some-redirect-url.com",
      "notificationUrl": "https://mycallback-url.com",
      "authorizationHeader": "Token xSUNmskaIUGh9hniB7bKJbNOho"
  }'

For more information about the Start Web SDK service an how to use it please refer to the Start Web SDK Flow – Service Details in the API documentation.

Integration details – identity lookup/matching

To perform identity lookup/matching you can follow 2 paths:

  • <Identity verification path> + H > The Assure API will use the identity information in the process to perform a lookup of that identity. The results will be saved in the process.
  • I” – You must provide information about the identity to be looked up. The results will be returned as JSON and will not be associated to any dossier nor process.

(Steps between A and G are the same listed above)

Step H: Get Lookup/Matching (Process)

You can use the Processes.End-user Lookup service to request a lookup/matching of the identity in that process:

curl -X POST \
  <ENVIRONMENT>/assure/dossiers/<DOSSIER_ID>/processes/<PROCESS_ID>/<LIST_TYPE> \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  • Use the “dossierId” and the “processId” of the process .
  • Indicate in which “listType” you want to lookup/match that identity in (ex: “PEP”, Sanctions”, “OFAC“).

Important: This service can only be used in processes with “status = accepted“. This is required because the lookup/matching service needs information about the person’s identity (such as their name and date of birth) and that information is only guaranteed to be correct in processes that have been “accepted”, i.e., in identities that have been verified.

The service will return a “200 OK” if the information was successfully retrieved. After that, you must use the Get Process endpoint again to check the lookup/matching results.

Please check the Lookup/Matching services details in the API documentation for more details about how to use this service.

Step I: Get Lookup/Matching (Assure)

You can use the Assure.Identity Lookup service to request a lookup/matching of any identity:

curl -X POST \
  <ENVIRONMENT>/assurelookup/<LIST_TYPE> \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
      "listType": "PEP",
      "name" : "John Smith",
      "dateOfBirth": "1965-07-13",
      "idNumber": "SE196507135496",
      "country": "SWE",
      "isSoundEx": "false"
  }'

In this case, you don’t need to previously have any dossier nor process, but you must provide information about the person’s identity:

  • Indicate the “name“, “dateOfBirth“, “idNumber“, “country” of the person (only name is mandatory);
  • Indicate if you want use phonetic spelling when searching for that person’s name (“isSoundEx = true“).
  • Indicate in which “listType” you want to lookup/match that identity in (ex: “PEP”, Sanctions”, “OFAC“).

The service response will contain a list of matching results. Note that, since we don’t have an associated dossier nor process, this information will not be kept by the Assure API. If you want to keep it, you must save the info in the response.

Please check the Lookup/Matching services details in the API documentation for more details about how to use this service.

Other endpoints

The table below contains other endpoints that were not referred above but are also very useful:

For getting information about the dossiers/processes.
For deleting information.
For getting information on some 3rd party provider’s services.

Usage recommendations

Always communicate through a server

Your mobile/web app must always talk to your own server and never directly with the Assure API.

Use callbacks

Use the callback notifications to help you know the moment that the verification is complete.

Save useful information and cleanup afterwards

After an identity verification result is obtained, you should save any information that is useful for you on your side (check the “Other Endpoints” section for auxiliary services that help you do that).

If the verification was “accepted“, you can even download a Zip file containing the full result.

Also, when you are finished using a process/dossier (and kept the important information on your side) you should delete the process and/or the dossier.

Important: The information in the Assure API will be deleted after a period of time, regardless you explicitly requested for it to be deleted or not. Please refer to the Privacy and Data Policy for details.

Use cases

Please checkout the Integration Use Cases page for detailed usage and integration scenarios of the Assure API.

Was this helpful?