# 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 guide (step-by-step).
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
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?
No. 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. For an integration use case example, see Integration use cases > Use case 4.
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
provider that will perform the verification and a
redirectUrl, which is where the end-user is redirected when the verification process is finished, whether it is successfully or not. You must prepare this
redirectUrl to receive parameters since the
status will be appended to it.
Example of a redirect URL when verification is finished
Optionally, if you want to be notified when the verification is finished, 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
status of the process are appended to the
# 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
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.
# 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
processId(that will perform the authentication) and a
redirectUrl. You can also optionally send a
notificationUrlto 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
notificationUrlin 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 bout authentication results, see Connect results.