Integration flows

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

Note: 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 proofing using their identity document on your web/native mobile app.

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

Step 1: Initial setup

You must set up the necessary resources, i.e. create a dossier and then create a process inside that dossier.

The dossier is where all the information about the end-user is kept. 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. For details about which options are available for each provider, see Upload ID 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 request to be notified when the result is available. Note: You must define this while creating the process in step 1. 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 register callback notifications to get the final result?

You are not required to subscribe to the callback notifications (opens new window). However, we strongly recommend that you use callbacks, instead of polling Signicat's services.

WARNING

Using polling instead of callbacks 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 callback 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 proofing, 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 (see step 2 above) 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’s Start Capture Flow 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:

This flow is a simplification of the generic eIDV integration flow. You don’t need to create a process (step 1 of generic flow), integrate with the provider’s SDK / upload the images (step 2 of generic flow) nor request to start the verification (step 3 of generic flow).

All of these steps are encapsulated in the Start Capture Flow service. For information about how to use this service, see Start Capture Flow.

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

Step 1: Initial setup

As in any flow, you must create a dossier to contain the information about the end-user.

After you have the dossier, you just have to call the Start Capture Flow endpoint, giving it the dossierId, the provider that will perform the verification and a redirectUrl, which is where the end-user is redirected when they have finished capturing and uploading the ID images. You must prepare this redirectUrl to receive parameters since the dossierId, processId and status will be appended to it.

Example of a redirect URL

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

Optionally, if you want to be notified when the verification is finished, either successfully or not, you can send a notificationUrl in the request.

In this service’s response, you will find a URL that you need in the next step.

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 is finished performing the verification, they are redirected to the redirectUrl indicated in the Start Capture Flow request. The dossierId, processId and status of the process are appended to the redirectUrl.

Step 3: Get result

You know the verification is finished when you get a notification in the notificationUrl you indicated in the Start Capture Flow request). The callback notification will contain the dossierId, processId and status of the process. You can use that information to call the Get process endpoint and get all the data regarding the verification result.

If you did not register to be notified when the verification is finished, you can poll the Get process endpoint and wait for the process status to be one of the final possible values (e.g. accepted, rejected). 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 were accepted. For more information about the process results, see Get process.

eID flow

By integrating with the Assure API you enable an end-user to authenticate using their preferred eID provider.

The flow can be illustrated as follows:

This integration flow is very similar to the eIDV alternative flow with the following differences:

• In step 1, you must call the Create process endpoint (instead of the Start Capture Flow endpoint), but you will send the similar parameters, i.e. the dossierId, the processId (that will perform the authentication) and a redirectUrl. You can also optionally send a notificationUrl to be notified when the user is finished.
• In step 2, the end-user is redirected to a web view where they will authenticate with the chosen eID method.
• Step 3 is a synchronous solution. When the end-user is redirected to the redirectUrl, it means that the authentication is finished. Nevertheless, if you added a notificationUrl in the Create process request, you will get a callback notification there too.
• Unlike the result of the eIDV processes, the final result of a Connect process will not be normalised. For more information about authentication results, see Connect results.