Identity verification

Assure API integration details

1545 views December 3, 2019 May 25, 2020 1

This page provides details about how to integrate with Signicat’s Assure API:

Other recommended reading (outside this page):

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.

Integration details for identity document verification (eIDV)

The API reference documentation provides an overview of the flows for performing identity document verification. This page provides possible alternative ways to do that and detailed integration information for 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.

Recommended paths

Full control and flexibility

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 is used to capture and upload the images, it is more likely you will obtain a better quality of the final result.

No frontend

An alternative path is A > B > C > D2 > E > F. The advantage is that you do not have 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.

Easy integration using hosted WebSDK

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

For more information about specific paths, see the Integration use cases page.

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 in 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 in 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 must 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

Note: If you use this approach, you must specify the “documentType” when you set up 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.

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?