Integrating With the Assure API Using the Electronic ID Web SDK

On this page, you will find all the necessary instructions to start using the Assure API in a web browser environment, using Electronic ID as an identity verification provider.

The steps below assume that you already know your client_id and client_secret and also have the access token (further referred to as <OIDC_ACCESS_TOKEN>) that is required for calling each endpoint.

It is also assumed that you have access to the Assure API at some <ENVIRONMENT> (e.g. https://beta.signicat.com).

Tips for using Swagger

You can use the Swagger docs to try out the API.

Make sure to choose the correct server environment before requesting the access token:

Use your client_id and client_secret and make sure the client.assure.api scope is selected, then click “Authorize”:

Integration Details

To use Electronic ID’s Web SDK, you can integrate with it directly.

As an alternative, the Assure API provides an endpoint that allows you to use the provider’s JS (Web) SDK seamlessly to capture and upload the ID images. This way, you can still use the provider’s SDK without having to integrate with it — you will just integrate with the Assure API.

Below are the step-by-step details for both of these options.

Option 1: Integrating with both the Assure API and Electronic ID’s Web SDK

Step 1.1: Create a dossier

Use the Create Dossier 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.

Step 1.2: Get document types

Before proceeding to the next step, you must know which type of ID document the end-user will provide to validate their identity (you will need that information in Step 1.3).

To find out which types of identity documents are supported by Electronic ID for each country, use the Get Document Types endpoint:

curl -X GET \
  <ENVIRONMENT>/assure/eid/document-types \
  -H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <>' \
Step 1.3: Create a process, using Electronic ID as the identity verification provider

Use the Create Process endpoint to create a new process:

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": "eid",
  "documentType": "passport"
}'

Make sure to:

Save the processId and the authorization from the response body to use in the next steps.

Step 1.4: Launch the Electronic ID Web SDK

Redirect the end-user to an endpoint in your application where you present an HTML page which contains the web SDK. You will need to use the authorization token from step 1.3 when starting the web videoid handler, and you’ll need to write the code to handle the scenarios when the user has completed the process, or in case of an error.

In your web server application, launch the Electronic ID Web SDK.

You must use the authorization token from step 1.3 when launching the web client (<AUTHORIZATION_TOKEN>).

Note: the web client requires HTTPS to function due to browser restrictions.

<!doctype html>
<html>
<head>
    <style>
        body, html, #video { margin: 0; padding: 0; height: 100%; }
    </style>
    <script src="https://etrust-sandbox.electronicid.eu/v2/js/videoid.js"></script>
</head>
<body>
 
    <div id="video">
    </div>
 
    <script>
        var videoId = EID.videoId('#video', {
            lang: "en",
        });
 
        videoId.on("completed",
            function (video) {
                videoId.turnOff();
                document.location.href = 'https://myserver.com/complete'
            });
 
        videoId.on("failed",
            function (error) {
                console.log(error);
                alert("VideoId Failed");
            });
 
        videoId.turnOn();
 
        /*
            138 = Norwegian passport
            For a full list of the idType for each type of
            document, please refer to the document-types
            endpoint in the Assure API
        */
        videoId.start({
            authorization: "<AUTHORIZATION_TOKEN>",
            idType: "138"
        });
 
    </script>
</body>
</html>

The end-user will now be prompted to supply the necessary identity information, such as images from the front and back of the ID document and selfie image.

Step 1.5: Start verification

When the end-user is done collecting the images, you must tell the Assure API to start verifying all of the provided data.

To do that, you must call the Start Verification endpoint of the Assure API.

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' \
  -d '{
  "notificationUrl": "https://mycallback-url.com",
  "authorizationHeader": "Token xSUh9hniB7bKJbNOhoasddasd"
}'

Make sure to use the dossierId (<DOSSIER_ID>) and processId (<PROCESS_ID>) from the previous steps.

You can provide a notificationUrl (and an authorizationHeader if needed — setting this value will add an Authorization header to the request that is sent to the notificationUrl). These fields are not mandatory, but they are required if you want to receive a notification when the verification has finished (step 1.8).

Step 1.6: Get manual approval URL

Electronic ID requires that the information is manually verified and approved before returning a final result about the verification.

Use the Get Manual Approval endpoint to get the URL to use on the next step:

curl -X GET \
 <ENVIRONMENT>/assure/eid/manual-approval \
 -H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
 -H 'Accept: application/json' \
Step 1.7: Do the manual approval

Access the URL obtained on the previous step and click “I’m ready to start working”:

You will be prompted to accept a verification request, after which you will be able to perform the manual approval of all the information about the end-user.

Step 1.8: Get the verification results

After you receive the callback notification (in the URL you provided in step 1.5), you must use the Get Process endpoint to check the full result of the identity verification:

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. Please refer to the Process Details documentation for more information about the contents of this response.

Note that you can call this endpoint at any time. However, the final result will only be available after the notification has been sent.

Option 2: Integrating only with the Assure API

Step 2.1: Create a dossier

Use the Create Dossier 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.

Step 2.2: Initiate the Web SDK flow via the Assure API

Use the Start Web SDK flow endpoint to initiate a Web flow using Electronic ID’s Web SDK:

curl -X POST \
  <ENVIRONMENT>/assure/dossiers/<DOSSIER_ID>/web \
  -H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "provider": "eid",
  "redirectUrl": "https://some-redirect-url.com",
  "notificationUrl": "https://mycallback-url.com",
  "authorizationHeader": "Token xSUh9hniB7bKJbNOhoasddasd",
  "language": "nb"
}'

Save the url from the response body to use on the next step.

Step 2.3: Launch the Electronic ID Web SDK

Redirect the end-user to the URL obtained in the previous step, opening an HTML page containing the web SDK.

Note that the URL will only be available for a single usage.

In this page, the user will be prompted by the provider’s SDK to capture and upload the images of their ID document.

In the end, the user will be redirected to the given URL.

Final Steps: Manual Approval and Get Result

Perform steps 1.6 to 1.8 in Option 1 to get the manual approval URL, perform the manual approval and get the final result.