Identity verification

Assure API integration details

2779 views December 3, 2019 November 13, 2020 1

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

For details about how to use the Assure API, see the Assure API documentation. Tip: The steps below (A-G) contain direct links to the relevant API documentation.

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 details about all the possible ways to do that.

The following image 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. Only this path allows you to integrate with any provider in any environment. Also, since 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 to use with some providers, currently Onfido and Signicat Paper. Since the ID images are not captured using the provider’s SDK, the verification result may suffer.

Easy integration using hosted JS SDK

Another alternative path is A > G > F. This path uses the Assure API’s Start Capture Flow service which encapsulates the providers’ JS SDKs. This means the images are captured using the provider’s SDK, which may lead to a better quality of the final result.

Note: You can only use this path when integrating for a web environment.

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

Step details

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 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 endoint 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 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 the process is 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.
You must create a new process if you want to:

  • Repeat the verification.
  • Use a different provider.
  • Use a different identity document.
  • Upload the images.

Note: All processes in a dossier must belong to the same end-user.

Step 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 and provide the SDK “authorization” token that you saved from the Create process response body (Step C: Create process).

For details on how to integrate with each provider’s SDK, please contact Signicat Support.

Tip: If you are creating a web app, see the Step G: Start Capture flow alternative. This service encapsulates the providers’ JS SDKs, meaning you only need to integrate with the Assure API.

You can always obtain the images after they have been uploaded by using the Get image endpoint.

Step D2: Upload images

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 already have been captured and not all providers support this approach.

Note: This step is an alternative to the previous one and is not part of the recommended path.

Tip: If you use this approach, you must have previously specified “documentType” when you created the process (during Step C: Create process).

To upload images directly to the process, use the Set images endpoint:

curl -X POST \
  <ENVIRONMENT>/assure/dossiers/<DOSSIER_ID>/processes/<PROCESS_ID>/images \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
  -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:

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 is 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 get the images after they have been uploaded by using 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: This step can be optional for some providers/processTypes, for example:
  • The 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, it is not required.
Step F: Get process

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

When the response arrives, you can 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 know that a process is finished when the process’ status matches one of the final process statuses (e.g. “accepted”, “rejected” “inconclusive”).

Tip: 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 that is available at that time.
Some providers supply information even before the verification is finished. For example, Electronic ID supplies 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 Capture 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).

For more information about the Start Capture flow service and now to use it, see the Start Capture flow Usage  section in the API documentation.

Available only for web usage

The Start web SDK flow service can only be used when you use 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"
  }'

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.

What do you want to do ?

New mail

What do you want to do ?

New mail

Was this helpful?