Skip to main content

Integration steps

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.

Subscribe to Assure Events​

It is recommended to subscribe to Assure Events to be notified when the result is available (either successfully or not). For more information, see Assure Events.

Save useful information and clean up afterwards​

After an identity verification 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.

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

Deletion

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 for details.

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

Assure flowchart

Assure flowchart

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.

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 endpoint to create a placeholder for all of your end-user's data:

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 in the next requests.

Ensure you use one dossier per end-user.
View the dossier contents

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 endpoint to create an identity verification process inside the dossier.

Ensure you use the dossierId from the "Create dossier" response.

  • Set the provider with the alias of the provider you want to perform the verification.
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": "<PROVIDER>",
     "documentType": "passport",
     "authorizationHeader": "Token xSUNmskaIUGh9hn5B7bKJbNOho"
   }'

If you use the Assure API to upload the images, you must also indicate the documentType (see Step B: Get document types above).

Depending on the provider you use to perform the verification, there may be other mandatory and optional parameters. For details, see the API Reference > Create Process.

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 (see Step F: Create 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.
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.

Web application

If you are creating a web application, you can use 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 endpoint.

Step D2: Upload images​

As an alternative to using the provider's SDK to capture and upload the images (D1), you can upload the images directly to the process using the Set Image endpoint.

Before using this approach, be aware of the following:
  • This step is not part of the recommended path.
  • The images must already have been captured and not all providers support this approach.
  • You must have previously specified documentType when you created the process (see Step C: Create process).

Here is a "Set image" request example:

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. See also the Images page.

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 (E), 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: driving licence).

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

Step E: Start verification​

After the end-user has finished the identity verification process and the data from that process is uploaded, you must request the Assure API to perform verification of the provided data.

To do this, call the Start verification endpoint. No parameters are necessary.

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 "Create dossier" and "Create process" responses.

"Start verification" can be optional

The "Start verification" 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.

Step F: Get process​

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

When the verification result is ready, you can call the Get process endpoint to see the detailed result information:

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?

It is recommended to subscribe to Assure Events to be notified when the result is available (either successfully or not). For more information, see Assure Events.

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, Signicat VideoID 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)​

Use the Start Capture flow service to create an identity verification process in a web context. From the end-user's perspective, this service helps them capture and upload ID images.

Recommendations
  • Recommended for web: This service encapsulates the providers' web SDKs. This means you do not have to integrate directly with those SDKs since they are already integrated into this service. Also, integrating with the Assure API using the Capture service (eIDV alternative flow) is simpler than integrating using the provider SDKs directly (eIDV generic flow).

  • Supported devices: You can use this service with all the providers that run in a web environment (currently Signicat VideoID, Signicat PictureID, Signicat Paper and Onfido).
Capture in iframe

For security reasons, Capture will only successfully load inside <iframe>, <frame>, <object> or <embed> on domains in an allowlist. If you plan to use Capture inside one of these elements, please request your domain to be allowed by creating a support ticket in the Signicat Dashboard. Other domains will be blocked by Signicat's CSP (content security policy).

In the Start capture flow request, ensure you:

  • Use the dossierId from the "Create dossier" response.
  • Specify the redirectUrl to redirect the user to the required page after the verification is finished.

In the the "Start Capture Flow" response you will get a URL. You should now redirect the end-user to this URL so they can start their identity verification.

Example URL:

{
    "url": "https://assure-demo.sandbox.signicat.com/capture/#/artifact=67fylnrx975e2jvbk8d410vknfnz122lllhclumxuvo6z5man2"
}

After the end-user has finished capturing and uploading the ID images, they are redirected to the redirectUrl (defined in the request). When the redirect happens, this URL is appended with information about the dossierId, the processId and the process' status.

Example URL:

https://myredirecturl.com/?dossierId=c03e66c7-8230-4020-a084-5a34a925d5fe&processId=8a303665-c94a-47c1-be8d-5df65f64a0ad&status=processing

The next step is to retrieve the identity verification results by using the Get process endpoint.

Last updated:
On this page