Skip to main content

Integration flows

This topic provides an overview of the flows for integrating with the Assure API and the use of its services.

Important

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

eIDV generic flow​

By integrating with the Assure API, you enable an end-user to perform electronic identity verification using their identity document on your web/native mobile app.

The generic flow for integrating this service can be illustrated as follows:

eIDV data flow

eIDV data flow

Step 1: Initial setup​

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.

Use the Create process endpoint to create an identity verification process inside the dossier.

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

The process allows you to request an eIDV provider to perform the verification of an identity document. It is also where all information about the verification result is kept.

Step 2: Upload ID images​

Now that you have a dossier and a process, you must provide images of the identity document and of the end-user.

You can do this either by using the provider's SDK to capture and upload the images or by uploading the images directly using the Assure API.

See also Images.

Step 3: Request verification​

Now that all the necessary information has been provided, you should request the verification.

Can I upload new ID images to the same process?

Every time you upload images to a process, they will replace the previous ones.

However, as soon as you request the verification to be performed, no more images should be uploaded. If you need to change the images or any other data, you should discard the current process and create a new one.

Step 4: Get verification result​

At this point, we must wait for a response from the provider with the final result.

Since this response is obtained asynchronously, you may subscribe to Assure Events to be notified when the result is available. Still, at any time you can see all the available information about an identity document verification by checking the information in the process.

Must I subscribe to Assure Events to get the final result?

You are not required to subscribe to the Assure Events. However, we strongly recommend that you do this, instead of polling Signicat's services.

Polling risk

Using polling instead of subscribing to events, may put your service at risk due to rate limiting of requests.

The final result information is always kept inside the process whether you asked to be notified or not. The event notification only informs you that the verification is finished.

An important feature of the Assure API is that, regardless of the provider you use to perform the identity verification, you always get a normalised final result on any process that is “accepted”. For more information about the process results, see Get process.

eIDV alternative flow (web only)​

If you prefer using the provider's SDK to capture and upload the ID images and you are integrating with the Assure API in a web environment, you can deflect integrating with their SDK and alternatively use the Assure API Capture service.

These services encapsulate the providers' JS SDKs, making it quicker and easier for you to integrate with the Assure API in a web context:

eIDV altnernative data flow

eIDV altnernative data flow

This flow is a simplification of the generic eIDV integration flow. You don't need to create a process (step 1 in the generic flow), integrate with the provider's SDK / upload the images (step 2 in the generic flow) nor request to start the verification (step 3 in the generic flow). All of these steps are encapsulated in the Start capture flow service.

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

Here are the guidelines on how to use this alternative flow:

Step 1: Initial setup​

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.

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.

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"
}

Step 2: Image upload and verification​

Now you must redirect the end-user to the URL you received in the previous step. That will load the provider's JS SDK and allows the end-user to capture/upload the required ID images and perform the verification.

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

Step 3: Get result​

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.

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.

If you do not subscribe on the Assure Events, you can poll the Get process endpoint and wait for the process status to be one of the final possible values, for example accepted, rejected etc. At that point, the response will also contain all the data regarding the verification result.

As in the generic flow, you get a normalised final result for processes that are accepted. For more information about the process results, see the Get process section.

Last updated:
On this page