Developer Pages

# Integration steps

Page contents

This page provides a step-by-step guide for integrating with Signicat’s Assure API to verify the identity of a person using an ID document (eIDV).

These integration steps are common for all providers. For more provider-specific information, see the specific provider pages.

# General 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 get notified when the verification is finished (either successfully or not). For more information, see the Callback section.

# Save useful information and clean up afterwards

After an identity proofing result is obtained, save any information that is useful for you on your side (check the Service details 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 (opens new window).

Also, when you are finished using a process/dossier (and kept the important information on your side), 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 Signicat Identity Verification privacy statement (opens new window) for details.

The following flow chart presents all possible paths to integrate with the Assure API.

Assure flowchart, click-to-zoom

Here are some 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 Javascript 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 Provider-specific integrations.

# Step A: Create dossier

Use the Create dossier (opens new window) 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 (opens new window) 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 (opens new window) 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 (opens new window) 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.
  • Set the provider with the alias of the provider you want to perform the verification.

If you use the Assure API to upload the images (opens new window), you must also indicate:

If you want to later receive a notification that the verification is finished (either successfully or not), 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 authorisation 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. For details, see the OpenAPI documentation > Create Process (opens new window).

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 (see Step D2: Upload images below).

Information about the process is kept and can be obtained at any time:

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 (see Step D1: Launch provider’s SDK) or you can upload images you already have through the Assure API Upload image (see 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 (see Step C: Create process).

For details on how to integrate with each provider’s SDK, see the Provider-specific pages.

TIP

If you are creating a web app, see the "Start capture flow" alternative (Step G). 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 (opens new window) 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 (opens new window) 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 (see Step C: Create process).

To upload images directly to the process, use the Set images (opens new window) 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:

  • Use the dossierId and processId from the previous steps.
  • Use PNG or JPEG images. They must be sent in dataURL format (opens new window). For details regarding images please check this section on the API reference documentation.

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 (see below), 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 licence).

You can always get the images after they have been uploaded by using the Get image (opens new window) 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 (opens new window) 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 and processId from the previous steps.

Note: This step can be optional for some providers/process types, 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 proofing using the Get process (opens new window) 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. See Response structure for more information about the contents of this response.

How do I know that a verification is finished? You can request to be notified (opens new window) when the final result is available. For more details, see Callbacks. You can also know that a process is finished when the process’ status matches one of the final process statuses.

Tip: If you want to be notified when a verification is finished (either successfully or not), you must register this during the Create process step (C).

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 IDentification 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 (web only)

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 (see Step B: Get document types, Step C: Create process, Step D1: Launch provider’s SDK and Step E: Start verification).

  • From the response, you get a URL that you use to redirect the end-user.

  • There, the end-user is asked to verify their identity using their ID document.

  • After they do that, they are redirected to redirectURL, where the dossierId, processId and status are appended. You may also add a notificationURL and get a callback.

  • Then you can proceed to the Get Process step.

For more service details see the Start capture flow section.

Last updated: 08/09/2023 10:49 UTC

← Get process →