The Assure API is a RESTful service that businesses can use to perform electronic identity verification (eIDV) of their customers, i.e. to scan and verify identity documents using one or more of the supported eIDV services. It also allows to obtain identity information from eID methods and to match and corroborate the data from these sources.
The purpose of the Assure API is to provide a unique and simple way of integrating these identification services, working both in a browser and native mobile contexts and supporting asynchronous operations.

Privacy and data

The Assure API conforms to the Signicat Assure Privacy Statement

Accessing the API

Client credentials

To access the Assure API you must use your set of credentials provided by Signicat Operations.

If you just want to try out the API, you can use the demo-service credentials available on the Demo Service page.

Note: The demo service is a shared environment that anyone can access. For that reason, DO NOT use or provide any PII data using the demo-service credentials.

OIDC token

After you have the credentials, you must acquire an access token using the OpenID Connect (OIDC) protocol. This is a procedure required to consume the Signicat REST services. For more information on how to do this, please see Accessing Signicat REST Services.

Make sure to add the client.assure.api and client.capture.api scopes to your token request. This is a curl example of an OIDC token request:

curl --location --request POST 'https://preprod.signicat.com/oidc/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <BASE64 ENCODED CLIENTID:CLIENTSECRET>' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=client.assure.api client.capture.api'

 

Key concepts

End-user

This is the person whose identity will be verified. Each end-user must have a dossier containing their personal information.

Dossier

Dossiers are resource objects that contain end-user identity data, e.g. name, date of birth, ID document, etc. This data may be put in the dossier both directly by adding files or data about the end-user, or indirectly by creating processes in the dossier that will later contain identity data about the end-user.

You must create this object with the Assure API. Each end-user should have its own associated dossier.

For more information, see the OpenAPI Specification documentation.

Process

Processes are also resource objects that contain end-user identity data. Like dossiers, they can also have associated files (e.g. ID images). However, additionally to dossiers, they have identity verification result data obtained from the provider that was used to verify the information in the process. You must create this object with the Assure API, inside a dossier. Each process belongs to only one dossier, but a dossier may have multiple processes. You can only use one provider to verify the information on each process.

For more information, see the OpenAPI Specification documentation.

Verification request 

The action of requesting a provider to verify the information inside a process.

Verification result

Information obtained from the provider with the outcome of checking the information inside a process.
This result is normalized by the Assure API and becomes part of the process too.

Supported providers

Being a single point of integration for various identity assurance services, the Assure API integrates with multiples eIDV and eID providers to offer those services.

Identity Document Verification providers (eIDV)

The providers of this service verify an end-user’s identity by scanning and checking the information of an ID document. Some providers also offer other types of verification services, such as facial similarity check and/or liveness check.

Below is a list of eIDV providers currently integrated with the Assure API and the services they provide.

Provider Process type OCR + verification Facial similarity Liveness check Other
Onfido document (tick)
documentSelfie (tick) (tick)
documentVideo (tick) (tick) (tick)
ElectronicID substantial (tick) (tick) (tick)
unattended (tick) (tick) (tick) (tick) (1)
attended (tick) (tick) (tick) (tick) (2)
ReadID (tick) (tick) (3)
Signicat Paper (tick) (tick) (4)

(1) Manual review by an agent.
(2) Live interview with an online agent.
(3) NFC reading of ID document’s chip.
(4) Redaction of ID images.

Read more about how to use the eIDV services in the eIDV Integration Flow section and the Integration Details documentation.

Process types

This table sums up the different types of processes available for each provider:

Provider Notes Process type Description
Onfido Depending on the chosen process type, Onfido requires:
Just images of the identity document
Images of the ID and also an image of the end-user (selfie)
Images of the ID and also a video where the end-user is asked to perform some actions (such as saying numbers out loud or turning their head to the left/right).Important: When using the documentVideo process type and Onfido’s SDKs to capture and upload the ID images, if, for some reason, the video cannot be recorded, a selfie image will be taken instead and the process type will fallback to documentSelfie.
document Performs verification of just the identity document.
documentSelfie Performs verification of the identity document and the provided selfie image of the end-user.
documentVideo Performs verification of the identity document and the live video recorded of the end-user
ElectronicID Regardless of the chosen process type, ElectronicID always records a video of the end-user taking pictures of their identity document and asks the end-user to look/smile to the camera. substantial The verification is performed automatically, i.e., no human agent is involved in the process.
unattended The verification is performed in two steps, first automatically and later that information is reviewed by a human agent. This is done asynchronously.
attended The verification is also performed in two steps but it is done synchronously, i.e. the agent must be online at the time of the verification and a live interview is performed.

Electronic Identity providers (eID)

The Assure API supports end-user authentication through several eID methods such as iDIN, Norwegian BankID and NemID. Please check the ID methods documentation for a full list of the eID providers currently supported by Signicat. Internally to the Assure API, you must use the Connect service from Signicat to access those eID services. Read more about how to use the eID services in the eID flow section.

Integration flows

This topic provides an overview of the flows for integrating with the Assure API and the use of its services. For more detailed information, see Integration Details (under Docs). There you also find integration guides for some of the most common use cases for the Assure API.

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 verification 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 identity document verification 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 Images (usage).

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 when 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 verification, you always get a normalized final result on any process that is “accepted”. For more information about the process results, see Get process (usage).

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’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 more detailed information about this service, see Start Capture Flow (usage). For integration use case examples, see Integration Details (under Docs).

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 the verification process is finished, whether it is successfully or not. You must prepare this redirectUrl to receive parameters since the dossierId, processId and status will be appended to it.

Example of a redirect URL when verification is finished

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, 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 normalized final result for processes that were accepted. For more information about the process results, see Get process (usage).

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:

API REFERENCE

OpenAPI documentation

For detailed reference documentation and testable examples please refer to the OpenAPI documentation (Swagger).
OpenAPI documentation

  Testing with curl

You can use curl to try out the API functionalities. First, you must get an access token and then use this access token when testing the endpoint:

Get access token

curl -u demo service client_id:client_secret -i -X POST \
https://preprod.signicat.com/oidc/token \
-H 'Accept: application/json' \
-d 'grant_type=client_credentials&scope=client.assure.api%20client.capture.api';

After you have run this command, you will receive the access token and can use it for testing (see the next section).

Use access token in endpoints

You can use the retrieved access token as “authorization” in the header to test the endpoints described in the following sections. Here is an example of how you can use the access token in the Create dossier endpoint:

curl -X POST \ https://preprod.signicat.com/assure/dossiers \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \;

DOSSIERS

Dossiers are resource objects that contain end-user identity data, e.g. name, date of birth, ID document, etc. They also contain any processes that are created to verify that end-user’s identity.

    Create dossier

OpenAPI Dossiers/createDossier
Usage details You should create a new dossier for each new end-user to perform an identity verification for that user. A dossier can have more than one process inside and each process can use a different provider.
Usage is required? Yes.
curl curl -X POST \ https://preprod.signicat.com/assure/dossiers \ -H ‘Authorization: Bearer ACCESS_TOKEN’ \ -H ‘Content-Type: application/json’ \;

    Get dossier

OpenAPI Dossiers/getDossier
Usage details You can get a dossier to see a summarized view of all the processes in it.
Usage is required? No.
curl curl -X GET \ https://preprod.signicat.com/assure/dossiers/<DOSSIER-ID> \ -H ‘Accept: application/json’ \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \;

    Delete dossier

OpenAPI Dossiers/redactDossier
Usage details We recommend you use this service to delete the dossier after you have finished the end-user’s identification.
Usage is required? No, but it is recommended.
curl curl -X DELETE \ https://preprod.signicat.com/assure/dossiers/<DOSSIER-ID> \ -H ‘Accept: application/json’ \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \;

    Get all dossiers

OpenAPI Dossiers/getDossiers
Usage details You can use this service to check the last 100 dossiers you have created (and that have not yet been deleted).
Usage is required? No.
curl curl -X GET \ https://preprod.signicat.com/assure/dossiers \ -H ‘Accept: application/json’ \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \;

    Set user data

OpenAPI Dossiers/setUserData
Usage details Use this service to add data about the end-user into the dossier (e.g., data that was introduced by the end-user in a form).
By calling this service, any existing user data in the dossier will be deleted and replaced by the new data.
Usage is required? Yes, if you want to match user data with process result information.
curl curl -X POST \ https://preprod.signicat.com/assure/dossiers/<DOSSIER-ID>/userdata \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \ -H ‘Content-Type: application/json’ \ -d ‘{ “userData”: { “firstName”: “Sal”, “lastName”: “Grosso”, “gender”: “M”, “nationality”: “PRT”, “dateOfBirth”: “1988-08-18”, “personalIdentificationNumber”: “12123456”, “placeOfBirth”: “Aveiro”, “mobile”: “+351939393953”, “email”: “enduser@email.com”, “address”: { “formatted”: “Street of Best streets nº8, \n 3810-88 Aveiro \n PRT”, “streetAddress”: “Street of Best streets nº8”, “houseNumber”: “8”, “locality”: “Aveiro”, “region”: “Beira Litoral”, “postalCode”: “3810-88”, “country”: “PRT” } } }’;

    Get user data

OpenAPI Dossiers/getUserData
Usage details Use this service to get the existing data in the dossier about the end-user. You will also get information about when this data was last updated.
Usage is required? No.
curl curl -X GET \ https://preprod.signicat.com/assure/dossiers/<DOSSIER-ID>/userdata \ -H ‘Accept: application/json’ \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \ -H ‘Content-Type: application/json’ \;

    Update user data

OpenAPI Dossiers/updateUserData
Usage details Use this service to update the data about the end-user in the dossier.
Existing fields will not be deleted, only the provided information will be added to or replaced in the currently existing userData.
Usage is required? No.
curl curl -X PUT \ https://preprod.signicat.com/assure/dossiers/<DOSSIER-ID>/userdata \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \ -H ‘Content-Type: application/json’ \ -d ‘{ “userData”: { “firstName”: “Sal”, “lastName”: “Grosso”, “gender”: “M”, “nationality”: “PRT”, “dateOfBirth”: “1988-08-18”, “personalIdentificationNumber”: “12123456”, “placeOfBirth”: “Aveiro”, “mobile”: “+351939393953”, “email”: “enduser@email.com”, “address”: { “formatted”: “Street of Best streets nº8, \n 3810-88 Aveiro \n PRT”, “streetAddress”: “Street of Best streets nº8”, “houseNumber”: “8”, “locality”: “Aveiro”, “region”: “Beira Litoral”, “postalCode”: “3810-88”, “country”: “PRT” } } }’;

    Delete user data

OpenAPI Dossiers/deleteUserData
Usage details Use this service to delete all data about the end-user from the dossier.
Usage is required? No.
curl curl -X DELETE \ https://preprod.signicat.com/assure/dossiers/<DOSSIER-ID>/userdata \ -H ‘Accept: application/json’ \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \ -H ‘Content-Type:application/json’ \;

    Set files

OpenAPI Dossiers/setFiles
Usage details Use this service to add files to the dossier. For more information, see Files in dossier (usage).
Usage is required? No.
curl curl -X POST \ https://preprod.signicat.com/assure/dossiers/<DOSSIER-ID>/files/ \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \ -H ‘Content-Type: application/json’ \ -d ‘{ “front”: “data:image/png;base64,iVBORw…”, “back”: “data:image/png;base64,iVBORw…”, “selfie”: “data:image/png;base64,iVBORw…”, “processId”: “<PROCESS-ID>” }’;

    Get files

OpenAPI Dossiers/getFile
Usage details Use this service to retrieve files that exist in the dossier. For more information, see Files in dossier (usage).
Usage is required? No
curl curl -X GET \ ‘https://preprod.signicat.com/assure/dossiers/<DOSSIER-ID>/files?depiction=<DEPICTION-TYPE>’ \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \;

    Start Web SDK Flow

OpenAPI Dossiers/createArtifact
Usage details Note: This service is deprecated. You should use the Start Capture Flow (which provides a similar service with added functionality) instead.

For details about this service, see Start Web SDK Flow (usage).

Usage is required? (Not applicable)

  PROCESSES

    Create process

OpenAPI Processes/createProcess
Usage details For details, see Create process (usage).
Usage is required? Yes, for the generic eIDV flow.

No, if you’re using the alternative flow.

curl curl -X POST \ https://preprod.signicat.com/assure/dossiers/<DOSSIER-ID>/processes \ -H ‘Accept: application/json’ \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \ -H ‘Content-Type: application/json’ \ -d ‘{ “provider”: “onfido”, “documentType”: “passport” }’;

    Get process

OpenAPI Processes/getProcess
Usage details Use this service to get all the information about a process (e.g. provider, processType, updatedAt, status) and the verification result (e.g. finalResult).

The data in the response may vary depending on the provider used to perform the verification. For more details, see Get Process (usage).

Usage is required? Yes.
curl curl -X GET \ https://preprod.signicat.com/assure/dossiers/<DOSSIER-ID>/processes/<PROCESS-ID> \ -H ‘Accept: application/json’ \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \;

    Delete process

OpenAPI Processes/redactProcess
Usage details After the verification is finished, we recommend you save all information about it (by using Get process and Get zip) and then use this service to delete the process (and later also Delete dossier if you are finished with that end user’s identity verification).
Usage is required? No, but it is highly recommended.
curl curl -X DELETE \ https://dev01.signicat.com/assure/dossiers/<DOSSIER-ID>/processes/<PROCESS-ID> \ -H ‘Accept:application/json’ \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \;

    Set images

OpenAPI Processes/setImages
Usage details Adds images to a process. You must use this service in the generic eIDV flow but only if you want to upload the images directly to the provider (i.e. not using their SDK to capture and upload the images). Direct upload is only available for some providers (e.g. Onfido, Signicat Paper). For more details, see Images (usage).

Cannot be used after the verification has started.

Usage is required? No, for the eID flow and the alternative eIDV flow.

Yes, for the generic eIDV flow, but only if you will use direct upload of the images.

curl curl -X POST \ https://dev01.signicat.com/assure/dossiers/<DOSSIER-ID>/processes/<PROCESS-ID>/images \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \ -H ‘Content-Type:application/json’ \ -d ‘{ “front”: “data:image/png;base64,iVBORw…”, “back”: “data:image/png;base64,iVBORw…”, “selfie”: “data:image/png;base64,iVBORw…” }’;

    Get images

OpenAPI Processes/getImage
Usage details Returns the images (of the document and end-user) available in the process.

Note: The images were either uploaded to the process directly through the Set Images endpoint or by using the provider’s SDK to capture and upload them. For more details, see Images (usage).

Usage is required? No.
curl curl -X GET \ ‘https://preprod.signicat.com/assure/dossiers/<DOSSIER-ID>/processes/<PROCESS-ID>/images?depiction=<DEPICTION-TYPE>’ \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \;

    Start verification

OpenAPI Processes/verifyProcess
Usage details This service can only be called after the ID images are uploaded to the provider (see Images (usage).

After calling this service, the information in the process can no longer be changed. This means that if you need to change something in the process (e.g. upload new images), you must create a new process and start over.

Usage is required? Yes, for the generic eIDV flow.

Exceptions are:

  • If you use Read ID (Read ID automatically does the verification as soon as the data is read from the document)
  • If you perform an Electronic ID “attended” process (the verification will be started by the online support agent)
curl curl -X POST \ https://preprod.signicat.com/assure/dossiers/<DOSSIER-ID>/processes/<PROCESS-ID> \ -H ‘Accept: application/json’ \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \ -H ‘Content-Type: application/json’ \;

    Get video

OpenAPI Processes/getVideo
Usage details Gets the video of the end-user capturing the ID images.

Note: Video will only be available:

  • If the provider/processType uses video, currently only ElectronicID (all process types) and Onfido (documentVideo process type). In these cases, you must always use the provider’s SDK to capture and upload the images.
  • After the end-user has finished capturing and uploading the ID images.
Usage is required? No.
curl curl -X GET \ https://preprod.signicat.com/assure/dossiers/<DOSSIER-ID>/processes/<PROCESS-ID>/video \ -H ‘Accept: application/json’ \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \;

    Download full result

OpenAPI Processes/getZipFile
Usage details Downloads a zip file containing all information obtained during a verification process (e.g. JSON files with the provider’s full response and images of the end-user’s ID document).
For details about the contents of the zip file, see Download full result (usage). Can only be called for processes that were finished, i.e., their status type is completed (e.g. “accepted“/”rejected“/”inconclusive“). As already mentioned, after a verification is complete, you should download all information about the process using this service and then delete the process.
Usage is required? No, but it is recommended.
curl curl -X GET \ https://preprod.signicat.com/assure/dossiers/<DOSSIER-ID>/processes/<PROCESS-ID>/download \ -H ‘Accept: application/json’ \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \;

  ASSURE

    Get document types

OpenAPI Assure/getDocumentTypes
Usage details Returns a list with the type of documents that can be used with each provider.
Note: The provider may support other documents. This list contains only the documents available according to your current contract with that provider.If you use ElectronicID as a provider and the generic eIDV flow, you must call this endpoint at least once to get their internal ID for each document. You must provide that parameter when you integrate with their SDK.
You will not have to do this if you use ElectronicID through the alternative eIDV flow. In this case, that service will take care of it for you.
Usage is required? No, for the eID flow and the alternative eIDV flow

Yes, for the generic eIDV flow, but only for ElectronicID.

curl curl -X GET \ https://preprod.signicat.com/assure/onfido/document-types \ -H ‘Accept: application/json’ \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \;

    Get manual approval URL

OpenAPI Assure/getManualApprovalURL
Usage details Gets the URL where a support agent can manually review the identity document verification request and approve or reject it.
Usage is required? Yes, for Electronic ID.
curl curl -X GET \ https://preprod.signicat.com/assure/onfido/manual-approval \ -H ‘Accept: application/json’ \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \;

  MATCHING

    Perform matching

OpenAPI Matching/match
Usage details You can use this service to corroborate the end-user’s identity. This service matches different sources of information about the end-user.
For more details, see Matching (usage).
Usage is required? No.
curl curl -X POST \ https://dev01.signicat.com/assure/dossiers/<DOSSIER-ID>/match \ -H ‘Accept: application/json’ \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \ -H ‘Content-Type: application/json’ \ -d ‘{ “source”: { “processId”: “a7f11597-19db-4ef0-84d5-268150f5c760”, “dataNode”: “finalResult”, “updatedAt”: “2019-03-04T15:58:17Z” }, “target”: { “processId”: “a7f11597-19db-4ef0-84d5-268150f5c760”, “dataNode”: “finalResult”, “updatedAt”: “2019-03-04T15:58:17Z” } }’;

CAPTURE

    Start Capture Flow

OpenAPI Capture/createArtifact
Usage details If you want to perform eIDV in a web context, we recommend using this service, since it encapsulates all providers’ Web SDKs. This means you do not have to integrate with the provider’s SDK yourself. To know which providers supply a Web (JS) SDK, see Upload ID images.

In addition to containing the provider’s web (JS) SDKs, this service also provides other useful features. For example, you can configure the user interface during the web flow or use two providers to perform an identity verification at the same time. For a full list of features and details on how to use them, please see Start Capture Flow (usage).

Usage is required? No, for the generic eIDV flow.

Yes, for the alternative flow.

curl curl -X POST \ https://preprod.signicat.com/assure/dossiers/<DOSSIER-ID>/capture \ -H ‘Accept: application/json’ \ -H ‘Authorization: Bearer <ACCESS_TOKEN>’ \ -H ‘Content-Type: application/json’ \ -d ‘{ “providers”: [ { “provider”: “onfido”, “processType”: “documentSelfie”, “redact”: [ “firstName” ] } ], “sdk”: “native”, “redirectUrl”: “https://some-redirect-url.com”, “notificationUrl”: “https://mycallback-url.com”, “authorizationHeader”: “Token xSUNmskaIUGh9hniB7bKJbNOho”, “captureParameters”: { “uiProfile”: “darkmode”, “uiLanguage”: “en”, “smsSender”: “Signicat”, “smsMessage”: “To continue please click here: ” } }’;

    Create Capture configuration

OpenAPI Capture/setConfiguration
Usage details Creates a new configuration to be used with the Start Capture Flow service. For more details, see Start Capture flow (usage).
Usage is required? No.

    Get Capture configuration

OpenAPI Capture/getConfiguration
Usage details Gets configuration about a specific capture configuration. For more details, see Start Capture flow (usage).
Usage is required? No.

    Update Capture configuration

OpenAPI Capture/updateConfiguration
Usage details Updates configuration about a specific capture configuration. For more details, see Start Capture flow (usage).
Usage is required? No.
curl curl -X PUT \
https://preprod.signicat.com/assure/capture/configurations/&lt;NEW_CONFIGURATION&gt; \
-H ‘Accept: application/json’ \
-H ‘Authorization: Bearer &lt;ACCESS_TOKEN&gt;’ \
-H ‘Content-Type: application/json’ \
-d ‘{
“fontName”: “Raleway”,
“fontUrl”: “https://fonts.googleapis.com/css?family=Raleway:400,500,600,700&amp;display=swap”,
“primaryColor”: “#5AAFFF”,
“fontColor”: “#000000”,
“buttonsColor”: “#000000”,
“buttonsTextColor”: “#000000”,
“spinnerColor”: “#000000”,
“documentTypes”: [
“identityCard”,
“passport”,
“driversLicense”
],
“documentCountries”: {
“passport”: [
“NLD”,
“GBR”,
“PRT”
],
“identityCard”: [
“NLD”
]
},
“twoSidedPassports”: [
“NLD”,
“PRT”
],
“languages”: [
“nl”,
“pt”,
“en”
],
“translations”: {
“nl”: {
“chooseCountry”: “Selecteer het uitgifteland van het identiteitsbewijs”,
“verifyingOrientationHint”: “Wordt de tekst op beide foto’\”s horizontaalweergegeven zoals in de voorbeelden?”
},
“pt”: {
“chooseCountry”: “Selecione a sua nacionalidade”,
“verifyingOrientationHint”: “O seu documento est&aacute; na mesma orienta&ccedil;&atilde;o que a ilustra&ccedil;&atilde;o em cima?”
}
},
“defaultCountry”: “NOR”,
“allowFileUpload”: [
“mobile”,
“desktop”
],
“allowTakePhoto”: [
“mobile”,
“desktop”
],
“enableOrientationConfirmation”: false,
“autoCapture”: false,
“detectGlare”: false,
“takeSelfie”: false,
“smsDefaultCountry”: “NOR”,
“maxRetries”: 3,
“showModalBeforeRedirect”: true,
“onfidoConfig”: {
“useModal”: “true”
}
}’;

USAGE CONTEXT

  Create process (usage)

This topic describes how to use this service (see also reference descriptions and the OpenAPI documentation).

This service creates a new process in the dossier, using a given provider. You will use this service in most flows unless you integrate through the eIDV alternative flow for the web.

Request (Create process)

The request can accept several parameters. However, which parameters to use depends on the provider and type of process. The table below breaks down the requests and shows in which scenarios you should use each parameter.

The icons in the table mean:

(warning)Mandatory usage with this provider

(tick) : Required with this provider, but only in some scenarios.

(info) : Optional usage with this provider

Request parameter Onfido ElectronicID ReadID Signicat Paper Connect Details
provider * (warning) (warning) (warning) (warning) (warning) This parameter is always mandatory in all scenarios.
processType (info) (info) Optional for Onfido and ElectronicID to determine the process type performed by that provider. For more information, see available process types. If omitted, defaults to “documentSelfie” for Onfido and “unattended” for ElectronicID.
documentType (tick) (warning) Mandatory for Signicat Paper.
Required for Onfido if the images will be uploaded via Assure API, i.e., using the Set Images endpoint.
documentCountry (warning) Mandatory for Signicat Paper.
redact (info) Optional for Signicat Paper to indicate which fields should be redacted from the ID images. For more information, see Redaction (usage).
firstName ((tick)) Although not mandatory, it must be used with Onfido if the images will be uploaded via Assure API, i.e., using the Set Images endpoint., and data comparison is enabled in the Onfido settings.
Required if lastName was sent.
lastName ((tick)) Although not mandatory, it must be used with Onfido if the images will be uploaded via Assure API, i.e. using the Set Images endpoint, and data comparison is enabled in the Onfido settings.
Required if firstName was sent.
notificationUrl (info) (info) (info) (info) (info) You can use this if you want to receive a callback notification when the process is finished.
authorizationHeader ((info)) ((info)) ((info)) ((info)) ((info)) You can only use this if “notificationUrl” is set, but it is still optional in that case.
redirectUrl (warning) Mandatory for all Connect processes. Indicates the URL where the end-user is redirected after they have finished authenticating (either successfully or not).
processParameters
referrer (tick) Required for Onfido processes where the images are uploaded via JS (Web) SDK. The URL of the web page where the Web SDK is used.
mobileAppId (tick) Required for Onfido processes where the images will be uploaded via iOS/Android (mobile) SDK. This is a unique ID of the mobile app that will integrate with the provider’s iOS/Android SDK. This is either a bundle ID for iOS or application ID for Android.
loginHint (info) Optional for Connect processes. For more information, see the integration details and integration use cases.
uiLocales (info) Optional for Connect processes. For more information, see the integration details and integration use cases.
uiProfile (info) Optional for Connect processes. For more information, see the integration details and integration use cases.

After you have created the process, you cannot change the information you sent in its request. This means if you need to change any of the information sent in its parameters, you must create a new process. Alternatively, you can delete the old process.

  Get process (usage)

This topic describes how to use this service (see also the reference descriptions and the Open API documentation)

This service is useful since its response provides plenty of information, for example:

The service also provides the most common result information like first name, last name and date of birth.

This section details all the information that can be retrieved for a process, depending on the variables provider, processType and status.

This section does not detail the results for each documentType/documentCountry since that list is too broad and also continuously changing. If you need details about specific cases, please contact Signicat Support.

Response structure of Get process

The information in the Get process response message depends on the used provider and the time of the flow you call this service. Time points can be as soon as the process is created, after the images are uploaded, or after a verification is finished.

The structure of the obtained JSON in the response changes over time and is divided into three main areas:

  1. Process information
  2. Provider-specific information
  3. Final result

1. Process information

This message area contains general information about the process, e.g. its internal unique ID, the identity verification provider that is used for performing the verification and the dates the process is created and last updated.

This information is generated as soon as the process is created.

Response example of Get process as soon as the process was created

{
    "provider": "onfido",
    "status": "pending",
    "processId": "4e48363a-37cb-4cff-8f91-afc9e52271fc",
    "createdAt": "2019-09-19T22:10:56Z",
    "updatedAt": "2019-09-19T22:10:56Z"
}
Field Description Field type
processId The process’ unique identifier string
provider The provider used in the identity verification. enum: Provider
createdAt The Process’ created date. Date: Normalized values
updatedAt The Process’s updated date. Date: Normalized values
status The current state of the process. Indicates whether the identity verification process is complete or not and, in case it is, what is the outcome, e.g. accepted, rejected, inconclusive.
For details on how each final status is mapped for each provider’s final result, please see provider-specific information.
enum: Process status
2. Provider-specific information

The Get Process response message contains a providerSpecific area with information about the verification process.

The contents depend on the information each provider share and it is filled in gradually as the provider share this information. For example, some providers start sharing information as soon as the identity document is uploaded, others share information when the verification is complete.

The information in this area is composed of one or more JSON elements containing information about the results of the identity document verification. The number and name of these elements are specific for each provider:

Provider JSON elements in the Get process response
Onfido
  • facialSimilarity
  • documentVerification

For details, see Onfido results.

ElectronicID
  • ocr
  • manualApproval

For details, see Electronic ID results.

ReadID
  • session

For details, see ReadID results.

Signicat Paper
  • verification
  • features
  • mrz
  • mrzChecksum
  • mrzVerification
  • mrzFeatureMatching

For details, see Paper results.

Connect
  • idtoken
  • userInfo
  • error

For details, see Connect results.

3. Normalized final result

After a verification is finished and if the result is accepted, the Assure API generates a finalResult element and adds it to the Get process response.

This element contains a fixed summary of provider collated information. The available fields depend on the information obtained from the provider. For example, the final result of a process with “provider”:”onfido” and “processType”:”document” will never contain information about similarityScore or livenessDetected, since an Onfido process only verifies the ID document and will not have that type of information available.

Example of finalResult element in a Get process response

"finalResult": {
    "firstName": "MARIA PAULA",
    "lastName": "SMITH JONES",
    "dateOfExpiry": "2024-03-02",
    "gender": "F",
    "nationality": "PRT",
    "documentType": "passport",
    "documentNumber": "CA412356",
    "issuingCountry": "PRT",
    "dateOfBirth": "1970-09-19",
    "similarityScore": "high",
    "livenessDetected": "true",
    "personalIdentificationNumber": "FANTASYBANK1234567890"
  }

Field descriptions:

Field Description Field type
firstName The end-user’s given name. String
lastName The end-user’s surname. String
dateOfExpiry The document’s date of expiry. Date: Normalized values
dateOfBirth The end-user’s date of birth. Date: Normalized values
gender The end-user’s gender. enum: Gender
nationality The end-user’s nationality. String: Normalized values
documentType The document type. enum: Document type
documentNumber The document number. String
issuingCountry The issuing country of the document. String: Normalized values
similarityScore The similarity level between the end-user’s face and the photo in the ID. enum: Similarity Score
livenessDetected Liveness detected during the process. Boolean
personalIdentificationNumber The official personal identification number scheme used in a country. String

In processes using Signicat Connect, the values of the fields in the final result are not normalized. However, Connect gives you the advantage of using any eID method through the Assure API.

Results by provider

This section provides detailed information and examples of the results for each provider. It also includes explanations of the final status in the process and how to interpret the information in the response.

Onfido results
Final status mapping

Onfido always performs a verification of the document (documentVerification). Depending on the process type you choose, it can also perform a facial similarity verification between the picture/video of the end-user and the photo in the ID document (facialSimilarity).

Based on Onfido’s results, the Assure API returns a final status for that process:

Onfido result Assure API’s
process final status
documentVerification facialSimilarity (1)
The ID is valid The faces match accepted
The ID is not valid (any) rejected
The ID is valid but suspicious (any) inconclusive
(any) At least one of the facialSimilarity verifications failed inconclusive

(1) If the process typeis documentSelfie or documentVideo, the final status depends on the result of both facialSimilarity and documentVerification. If the process type is document only, the final status depends exclusively on the result of documentVerification.

This table details each final status case:

Process final status

Description (1)

Onfido results

facialSimilarity

documentVerification

result

status

result

subResult

accepted All underlying verifications have passed. This means there are no indications the document is fraudulent. clear complete clear clear
inconclusive At least one of the facialSimilarity verifications failed. Reasons for this can be:

  • imageIntegrity: The quality and integrity of the uploaded files were not sufficient to perform a face comparison.
    • face_detected: A single face of good enough quality is not found in both the document image and the live photo/video.
    • source_integrity: The live photo/video is not trustworthy, i.e. may have been digitally tampered, from a fake webcam, or from other dubious sources.
  • faceComparison: The face in the document does not match the face in the live photo/video.
  • visualAuthenticity
    • spoofing_detection: The person in the live photo/video is not real (a spoof).
    • liveness_detected (video only): The numbers and/or head movements were not correctly executed.
consider (any) (any) (any)
The document is suspected to be fraudulent. Reasons for that can be:

  • dataValidation: One or more algorithmically validatable elements are incorrect:
    • date_of_birth
    • expiry_date
    • mrz
    • gender
    • document_numbers
  • visualAuthenticity: One or more visual (non-textual) elements are incorrect:
    • original_document_present: A photo of a printed photo or a photo of a digital screen (may be configured to map to caution).
    • digital_tampering: Name was altered, for example.
    • picture_face_integrity: The pictures of the person identified on the document show signs of tampering or alteration. In most cases, this will focus on the primary picture. It may also apply to the secondary and tertiary pictures when documents contain them.
    • security_features: Security features expected on the document are missing or wrong.
    • template: The document doesn’t match the expected template for the document type and country.
    • fonts: Fonts in the document don’t match the expected ones.
  • dataConsistency: Asserts whether data represented in multiple places in the document is consistent, for example, between MRZ lines and OCR extracted text on passports.
    • date_of_expiry
    • document_type
    • gender
    • date_of_birth
    • nationality
    • issuing_country
    • document_numbers
    • first_name
    • last_name
  • compromisedDocument: Document is found in Onfido’s database.
  • policeRecord: Document is recorded as lost, stolen or compromised.
clear/consider complete consider suspected
Other underlying verifications failed but they don’t necessarily point to a fraudulent document:

  • imageIntegrity: The document has not sufficient quality to verify:
    • colour_picture: The image of the document is not in colour (may be configured to map to rejected)
    • conclusive_document_quality: The document image has not good enough quality to perform a fraud inspection (for example, parts of the document are not visible).
  • dataComparison(if enabled): One or more elements provided by the end-user did not match the information in the document:
    • first_name
    • last_name
    • gender
    • date_of_birth
  • dataValidationAsserts whether the algorithmically validatable elements are correct:
    • document_expiration: The document has expired.
  • visualAuthenticity: One or more visual (non-textual) elements are incorrect:
    • face_detection: No face is detected in the document.
clear/consider complete consider caution
rejected The verification cannot be processed further. Reasons for this may be:

  • imageIntegrity: The document has not sufficient quality to verify:
    • supported_document: The document isn’t supported by Onfido
    • image_quality: The document image quality is too low for processing.
  • ageComparison: The age of the end-user is too low:
    • minimum_accepted_age: The standard threshold is 16 years (can be configured to another minimum value).
clear/consider complete consider rejected
canceled The verification was canceled (by the user). withdrawn

(1) In the Get process response, you get the results for Onfido’s breakdown listing (e.g. “visualAuthenticity”) in the provider-specific area, but information about the sub-breakdowns (e.g. “supported_document”) is only returned in the provider’s raw JSON result, which is available in a zip file obtained from the Download full result service.

Accepted process (Onfido)

This is an example of a Get process response for an Onfido process that was accepted:

{
    "provider": "onfido",
    "status": "accepted",
    "processId": "4e48363a-37cb-4cff-8f91-afc9e52271fc",
    "createdAt": "2019-09-19T22:10:56Z",
    "updatedAt": "2019-09-19T22:11:23Z",
    "finalResult": {
        "firstName": "TIAGO",
        "lastName": "FERREIRA SILVA",
        "dateOfExpiry": "2020-07-08",
        "gender": "M",
        "nationality": "PRT",
        "documentType": "identityCard",
        "documentNumber": "12233669 4 ZY4",
        "issuingCountry": "PRT",
        "dateOfBirth": "1983-08-12",
        "similarityScore": "high"
    },
    "providerSpecific": {
        "facialSimilarity": {
            "result": "clear",
            "imageIntegrity": "clear",
            "faceComparison": "clear",
            "visualAuthenticity": "clear",
            "similarityScore": "high"
        },
        "documentVerification": {
            "lastName": "FERREIRA SILVA",
            "dateOfExpiry": "2020-07-08",
            "subResult": "clear",
            "dataConsistency": "clear",
            "gender": "M",
            "documentType": "identityCard",
            "documentNumber": "12233669 4 ZY4",
            "dateOfBirth": "1983-08-12",
            "ageValidation": "clear",
            "policeRecord": "clear",
            "dataValidation": "clear",
            "result": "clear",
            "firstName": "TIAGO",
            "imageIntegrity": "clear",
            "nationality": "PRT",
            "issuingCountry": "PRT",
            "dataComparison": "clear",
            "visualAuthenticity": "clear",
            "compromisedDocument": "clear",
            "mrzLine1": "I<PRT122336694<ZY42<<<<<<<<<<<",
            "mrzLine2": "8302304F21207081PRT<<<<<<<<<<<6"
        }
    }
}

Field descriptions of an accepted Get process response (Onfido):

Element Name Field Name Description Field type
processId,
provider,
createdAt,
updatedAt,
status
For more details, see Process information.
finalResult For more details, see Final result.
facialSimilarity

Contains information about the facial similarity report.

result The result field indicates the overall result of a report. String :
Onfido result 
imageIntegrity Asserts whether the quality of the uploaded files and the content contained within them are sufficient to do a face comparison. String
faceComparison Asserts whether the face in the document matches the face in the live photo or live video. String
visualAuthenticity Asserts whether the person in the live photo or live video is real (not a spoof) and live (only done for live videos). String
similarityScore Indicates how similar the two faces are. If the face matching algorithm fails to detect a face, the score property will not be present. The score only measures how similar the faces are, and does not assess the nature of the photo or video. If tampering (such as photos of printed photos or photos of digital screens) is detected, the end-user is rejected regardless of the Facial Similarity score. enum: Similarity score 
documentVerification

Contains information about the document report.

lastName This property provides the last names in the document. String
dateOfExpiry Document’s date of expiry. Date : Normalized values
subResult Indicates a more detailed result for Document reports. enum : Onfido Sub-Result 
dataConsistency Asserts whether data represented in multiple places on the document is consistent, for example, between MRZ lines and OCR extracted text on passports.

The available values are clear and consider.

String
gender The end-user’s gender. enum : Gender 
documentType Document type verification. enum : Document type 
documentNumber Document identification number.
dateOfBirth End-user’s date of birth. Date : Normalized values
ageValidation Asserts whether the age, calculated from the date of birth, is greater than or equal to the minimum acceptable age set at the account level. The standard threshold is 16 years old but you can get Signicat to change this.

The available values are clear and consider.

String
dataValidation Asserts whether algorithmic validated elements are correct. For example, MRZ lines and document numbers.

The available values are clear and consider.

String
policeRecord Asserts whether the document has been identified as lost, stolen or otherwise compromised.

The available values are clear and consider.

String
result The result field indicates the overall result of a report. String
firstName This property provides the first names on the document, including any initials and middle names. String
imageIntegrity Asserts whether the document was of sufficient quality to verify.

The available values are clear and consider.

String
nationality End-user’s nationality. String : Normalized values
issuingCountry The issuing country of the document. String : Normalized values
dataComparison Note: Data comparison is disabled by default. For more details, see Onfido data comparison.

Asserts whether data in the document is consistent with the data provided when creating the process.

The available values are clear and consider.

String
visualAuthenticity Asserts whether visual (non-textual) elements are correct given the type of document.

The available values are clear and consider.

String
compromisedDocument Asserts whether the image of the document is found in our internal database of compromised documents.

The available values are clear and consider.

String
mrzLine1 Document’s mrz line 1. String
mrzLine2 Document’s mrz line 2. String
Rejected process (Onfido)

This is an example of a Get process response for an Onfido process that was rejected:

{
    "provider": "onfido",
    "status": "rejected",
    "processId": "88d490a0-7184-4aba-804d-4dac400f5660",
    "createdAt": "2019-09-23T15:43:37Z",
    "updatedAt": "2019-09-23T15:46:30Z",
    "providerSpecific": {
        "facialSimilarity": {
            "result": "consider",
            "similarityScore": "medium"
        },
        "documentVerification": {
            "result": "consider",
            "subResult": "rejected",
            "documentType": "unknown"
        }
    }
}

As you can see, a rejected result does not contain a finalResult element. Also, the provider-specific elements are few since there will probably be little data obtained from the document.

For details about each element, see Onfido Accepted.

Inconclusive process (Onfido)

This is an example of a Get process response for an Onfido process that was inconclusive:

{
    "provider": "onfido",
    "status": "inconclusive",
    "processId": "85210241-4e70-4451-8ea3-7cd3c4d8843a",
    "createdAt": "2019-09-23T10:05:53Z",
    "updatedAt": "2019-09-23T10:09:49Z",
    "providerSpecific": {
        "facialSimilarity": {
            "result": "consider",
            "similarityScore": "high"
        },
        "documentVerification": {
            "lastName": "SPECIMEN",
            "dateOfExpiry": "2024-11-01",
            "subResult": "suspected",
            "gender": "F",
            "documentType": "passport",
            "documentNumber": "00000000",
            "dateOfBirth": "1975-05-31",
            "result": "consider",
            "firstName": "LAERKE OEYVOR AASE",
            "nationality": "NOR",
            "issuingCountry": "NOR",
            "mrzLine1": "PVNORSPECIMEN<<LAERKE<OEYVOR<AASE<<<<<<<<<<<",
            "mrzLine2": "00000000<0NOR7505319F24110154197505311234586"
        }
    }
}

An inconclusive result does not contain a finalResult element but contains some data obtained from the document.

For details about each element, see Onfido Accepted.

ElectronicID Results
Final status mapping

ElectronicID only returns information about whether the verification was accepted or rejected. Assure API simply maps those values directly to the process’ final status.

Reasons for the process to be rejected is part of the response. For more details, see Rejected process.

Accepted process (ElectronicID)

This is an example of a Get process response for an ElectronicID process that was accepted:

{
    "provider": "eid",
    "status": "accepted",
    "processId": "d4233fba-9b7a-4400-9022-cd16b108ccc0",
    "createdAt": "2019-09-19T15:37:57Z",
    "updatedAt": "2019-09-19T15:40:09Z",
    "providerSpecific": {
        "ocr": {
            "lastName": "SANTOS HENDES",
            "dateOfExpiry": "2020-02-08",
            "healthNumber": "366355550",
            "gender": "F",
            "documentType": "identityCard",
            "socialSecurityNumber": "11926318740",
            "documentNumber": "122336694ZY4",
            "taxNumber": "200693803",
            "dateOfBirth": "1973-02-10",
            "similarityScore": "high",
            "firstName": "CAROLINA",
            "nationality": "PRT",
            "issuingCountry": "PRT",
            "personalIdentificationNumber": "12233669"
        },
        "manualApproval": {
            "duration": "12",
            "firstName": "CAROLINA",
            "lastName": "SANTOS MENDES",
            "dateOfExpiry": "2020-07-08",
            "gender": "F",
            "nationality": "PRT",
            "documentNumber": "12233669",
            "issuingCountry": "PRT",
            "rAuthorityId": "11a56f16-6f19-4282-8f2d-3749b86471d5",
            "dateOfBirth": "1973-08-10"
        }
    },
    "finalResult": {
        "firstName": "CAROLINA",
        "lastName": "SANTOS MENDES",
        "dateOfExpiry": "2020-07-08",
        "gender": "F",
        "nationality": "PRT",
        "documentType": "identityCard",
        "documentNumber": "122336694ZY4",
        "issuingCountry": "PRT",
        "dateOfBirth": "1973-08-10",
        "similarityScore": "high"
    }
}

Field descriptions of an accepted Get process response (ElectronicID)):

Element Name Field Name Description Field type
processId,
provider,
createdAt,
updatedAt,
status
For more details, see Process information.
finalResult For more details, see Final result.
ocr

Contains information obtained from the document by OCR analysis.

lastName Last name(s) String
dateOfExpiry Document expiry date Date: Normalized values
healthNumber Health number String
gender Gender enum: Gender 
documentType Type of document that was provided (e.g. a Norwegian passport) enum: Document type 
socialSecurityNumber Social security number String
documentNumber Document number String
taxNumber Tax number String
dateOfBirth Date of birth Date: Normalized values
similarityScore The similarity score between the photo in the document and the selfie image. Enum: Similarity score 
firstName First name(s) String
nationality Nationality String: Normalized values
issuingCountry The country that issued the document String: Normalized values
personalIdentificationNumber Personal identification number String
manualApproval

Contains information obtained
after a support agent has manually approved
the identity request. The fields
here are similar to the ones in ocr
but may have been improved.

 

 

 

 

 

 

 

 

 

duration How long the manual approval process took (number of seconds). Integer
firstName First name(s). String
lastName Last name(s). String
dateOfExpiry Document expiration date. Date: Normalized values
gender Gender Enum: Gender
nationality Nationality String: Normalized values
documentNumber Document number String
issuingCountry The country that issued the document String: Normalized values
rAuthorityId The id of the Registration Authority Application String
dateOfBirth Date of birth Date: Normalized values
Rejected process (ElectronicID)

This is an example of a Get process response for an ElectronicID process that was rejected:

{
    "provider": "eid",
    "status": "rejected",
    "processId": "52b7f782-ce2b-4436-94b9-0d264e327dd8",
    "createdAt": "2019-09-19T15:42:20Z",
    "updatedAt": "2019-09-19T15:44:56Z",
    "providerSpecific": {
        "ocr": {
            "lastName": "SILVA PEREIRA",
            "dateOfExpiry": "2019-09-29",
            "gender": "F",
            "documentType": "passport",
            "documentNumber": "N543765",
            "dateOfBirth": "1968-09-19",
            "similarityScore": "high",
            "firstName": "MARIA PAULA",
            "nationality": "PRT",
            "issuingCountry": "PRT",
            "personalIdentificationNumber": "12228340"
        },
        "manualApproval": {
            "reason1": "Document security features are not identified"
        }
    }
}

In this case, you will obtain a list of reasons why the verification was rejected, inside the manualApproval element.

Inconclusive process (Electronic ID)

ElectronicID processes do not have any inconclusivestatus.

ReadID results
Assure API’s process final status
ReaId ID information
accepted All verification status verdicts (CS, DS, EACCA and HT) are ” PRESENT_SUCCEEDED”
rejected A least one verification status verdict (CS, DS, EACCA and HT) is not ” PRESENT_SUCCEEDED”
Final status mapping (ReadID)

ReadID’s response returns information about access control of the chip, BAC, EACTA, PACE, and about the verification status, CS, DS, EACCA, HT (for descriptions of these fields, see Accepted result).

The Assure API uses the information in the verification status verdict fields to map the process’ final status:

Accepted process (ReadID)

This is an example of a Get process response for a ReadID process that was accepted:

{
    "provider": "readid",
    "status": "accepted",
    "processId": "178ddc29-3d0f-4706-ab70-0a597585e69a",
    "createdAt": "2019-10-08T13:17:12Z",
    "updatedAt": "2019-10-08T13:17:40Z",
    "finalResult": {
        "documentType": "passport",
        "firstName": "TIAGO MANUEL",
        "lastName": "PEREIRA MENDES",
        "gender": "M",
        "nationality": "PRT",
        "dateOfBirth": "1988-05-23",
        "documentNumber": "CB033930",
        "dateOfExpiry": "2024-08-26",
        "issuingCountry": "PRT"
    },
    "providerSpecific": {
        "session": {
                "documentType": "passport",
                "firstName": "TIAGO MANUEL",
                "lastName": "PEREIRA MENDES",
                "gender": "M",
                "nationality": "PRT",
                "dateOfBirth": "1988-05-23",
                "documentNumber": "CB033930",
                "dateOfExpiry": "2024-08-26",
                "issuingCountry": "PRT",
                "documentCode": "P",
                "mrzString": "P<PRTPEREIRA<MENDES<<TIAGO<MANUEL<<<<<<<<<<<CB033930<7PRT8703259M240726713438070<<<<<<44",
                "sessionDocumentType": "ICAO_MRTD",
                "BAC": "PRESENT_SUCCEEDED",
                "BACReason": "SUCCEEDED",
                "EACTA": "UNKNOWN",
                "EACCAReason": "PRESENT_SUCCEEDED",
                "PACE": "UNKNOWN",
                "PACEReason": "UNKNOWN",
                "CS": "PRESENT_SUCCEEDED",
                "CSReason": "FOUND_A_CHAIN_SUCCEEDED",
                "DS": "PRESENT_SUCCEEDED",
                "DSReason": "SIGNATURE_CHECKED",
                "EACCA": "SUCCEEDED",
                "HT": "PRESENT_SUCCEEDED",
                "HTReason": "ALL_HASHES_MATCH"
        }
    }
}

Field descriptions of an accepted Get process response for ReadID:

Element Name Field Name Description Field type
processId,
provider,
createdAt,
updatedAt,
status
For more details, see Process information.
finalResult For more details, see Final result.
session documentType The type of document provided. enum: Document type
firstName First name(s) of the document holder. String
lastName Surname(s) of the document holder. String
gender Gender of the document holder. enum: Paper checksum
nationality The nationality of the document holder. Note: This is not necessarily the same as the country that issued the document. String: Normalized values
dateOfBirth Date of birth of the document holder. Date: Normalized values
documentNumber The document’s number. String
dateOfExpiry The document’s expiry date Date: Normalized values
issuingCountry The document’s issuing country. String
documentCode Document code indicating the document type. ‘P’ for a passport, ‘I’ for an Identity Document. String
mrzString The MRZ information in the document. String
sessionDocumentType EU_EDL (European driver’s licence) or “ICAO_MRTD” (machine-readable travel document). String
BAC Active authentication/access control verdict enum: ReadID Enum for Access Control Verdict
BACReason Reason for the BAC verdict. enum: ReadID Enum for Access Control Reason
EACTA Active authentication/access control verdict enum: ReadID Enum for Access Control Verdict
PACE Active authentication/access control verdict enum: ReadID Enum for Access Control Verdict
PACEReason Reason for the PACE verdict. enum: ReadID Enum for Access Control Reason
CS Country Signer (CS) verdict. enum: ReadID Enum for the Verification Status Verdict
CSReason Reason for the CS verdict. enum: ReadID Enum for the Verification Status Reason
DS Document Signer (DS) verdict enum: ReadID Enum for the Verification Status Verdict
DSReason Reason for the CS verdict. enum: ReadID Enum for the Verification Status Reason
EACCA EAC-CA verdict. enum: ReadID Enum for the Verification Status Verdict
EACCAReason Reason for the EAC-CA verdict. enum: ReadID Enum for the Verification Status Reason
HT Hashtable (HT) verification verdict. enum: ReadID Enum for the Verification Status Verdict
HTReason Reason for the HT verdict. enum: ReadID Enum for the Verification Status Reason
Rejected process (ReadID)

This is an example of a Get process response for a ReadID process that was rejected:

{
    "provider": "readid",
    "status": "rejected",
    "processId": "6eed6478-9035-4b7a-a48a-cc24040c442d",
    "createdAt": "2019-10-08T13:16:31Z",
    "updatedAt": "2019-10-08T13:17:00Z",
    "providerSpecific": {
        "session": {
            "documentType": "passport",
            "firstName": "TIAGO MANUEL",
            "lastName": "PEREIRA MENDES",
            "gender": "M",
            "nationality": "PRT",
            "dateOfBirth": "1988-05-23",
            "documentNumber": "V122659",
            "dateOfExpiry": "2013-06-08",
            "issuingCountry": "PRT",
            "documentCode": "P",
            "mrzString": "P<PRTPEREIRA<MENDES<<TIAGO<MANUEL<<<<<<<<<<<V122659<<4PRT8703559M1306085BI13438070<<<<16",
            "sessionDocumentType": "ICAO_MRTD",
            "BAC": "PRESENT_SUCCEEDED",
            "BACReason": "SUCCEEDED",
            "EACTA": "UNKNOWN",
            "EACCAReason": "PRESENT_SUCCEEDED",
            "PACE": "UNKNOWN",
            "PACEReason": "UNKNOWN",
            "CS": "PRESENT_FAILED",
            "CSReason": "CERTIFICATE_EXPIRED",
            "DS": "PRESENT_SUCCEEDED",
            "DSReason": "SIGNATURE_CHECKED",
            "EACCA": "SUCCEEDED",
            "HT": "PRESENT_SUCCEEDED",
            "HTReason": "ALL_HASHES_MATCH"
        }
    }
}
Inconclusive process (ReadID)

ReadID processes have no inconclusive status.

Signicat Paper results
Final status mapping
Assure API’s

process final status

Signicat Paper result Description
status verificationStatus verificationType
accepted COMPLETED true MRZ_ONLY or MRZ_AND_FEATURES It was possible to read the document and verify the information.
inconclusive COMPLETED true FEATURES_ONLY It was possible to read the document but could not verify the information (there is no MRZ to use for verification).
rejected COMPLETED false It was possible to read the document but an error was found or at least one verification failed. List of errors is returned in the response.
FAILED
canceled MISSING The verification was canceled.
Accepted process (Signicat Paper)

This is an example of a Get process response for a Signicat Paper process that was accepted:

{
    "processId": "processId",
    "provider": "signicatpaper",
    "status": "accepted",
    "createdAt": "createdAt",
    "updatedAt": "updatedAt",
    "finalResult": {
        "firstName": "Tiago Miguel",
        "lastName": "Carvalho Ribeiro",
        "dateOfExpiry": "2020-10-15",
        "gender": "M",
        "nationality": "PRT",
        "documentType": "passport",
        "documentNumber": "N909555",
        "issuingCountry": "PRT",
        "dateOfBirth": "1974-11-08"
    },
    "providerSpecific": {
        "verification": {
            "type": "MRZ_FEATURE_COMPARISON",
            "status": "true"
        },
        "features": {
            "firstName": "Tiago Miguel",
            "lastName": "Carvalho Ribeiro",
            "dateOfExpiry": "2020-10-15",
            "issuingAuthority": "SEF SERV ESTR E FR0NTE1RAS",
            "gender": "M",
            "documentNumber": "N909555",
            "dateOfBirth": "1974-11-08",
            "personalNumber": "12883777",
            "dateOfIssue": "2015-10-15"
        },
        "mrz": {
            "firstName": "Tiago Miguel",
            "lastName": "Carvalho Ribeiro",
            "dateOfExpiry": "2020-10-15",
            "nationality": "PRT",
            "gender": "M",
            "documentType": "passport",
            "issuingCountry": "PRT",
            "documentNumber": "N909555",
            "dateOfBirth": "1974-11-08",
            "personalNumber": "12083777"
        },
        "mrzChecksum": {
            "dateOfExpiry": "VALID",
            "documentNumber": "VALID",
            "dateOfBirth": "VALID",
            "personalNumber": "VALID"
        },
        "mrzVerification": {
            "dateOfExpiry": "VALID",
            "documentType": "VALID",
            "issuingCountry": "VALID",
            "dateOfBirth": "VALID"
        },
        "mrzFeatureMatching": {
            "dateOfExpiry": "FULL_MATCH",
            "lastName": "FULL_MATCH",
            "issuingAuthority": "FOUND",
            "firstName": "FULL_MATCH",
            "documentNumber": "FULL_MATCH",
            "dateOfBirth": "FULL_MATCH",
            "driving_permits": "MISSING",
            "personalNumber": "LEVENSHTEIN1",
            "dateOfIssue": "VALID"
        }
    }
}

Field descriptions of an accepted Get process response for Signicat Paper:

Element name Element description Field name Description Field type
providerSpecific -> verification type The type of verification. Enum: Paper Types of Verification
Status The status of the verification.

If “true”, the verification was successful, if “false” at least one error was detected.

Boolean
providerSpecific -> features Contains information that was retrieved from the fields that were obtained directly from the document. firstName The person’s first name(s). String
lastName The person’s last name(s). String
dateOfExpiry The date until which the document is valid. Date: Normalized values
issuingAuthority The name of the authority that issued the document. String
gender The person’s gender. enum: Paper checksum
documentNumber The document’s number. String
dateOfBirth The person’s date of birth. Date: Normalized values
personalNumber The personal ID number in the document. String
dateOfIssue The issue date of the document. Date: Normalized values
providerSpecific -> mrz Contains the info that was retrieved from MRZ reading the document. firstName The person’s first name(s). String
lastName The person’s last name(s). String
dateOfExpiry The date until which the document is valid. Date: Normalized values
nationality The person’s nationality. String: Normalized values
gender The person’s gender. enum: Paper checksum
documentType The type of document (e.g. passport, identity card, driver’s license). enum: Paper checksum
issuingCountry The country that issued the document. String: Normalized values
documentNumber The document’s number. String
dateOfBirth The person’s date of birth. Date: Normalized values
personalNumber The personal id number in the document. String
providerSpecific -> mrzChecksum Contains information about the quality of some of the “feature” fields that were extracted from the document. dateOfExpiry The validation of date of expiry. Enum: Paper checksum
documentNumber The validation of the document’s number.
issuingCountry The validation of the country that issued.
dateOfBirth The validation of a person’s date of birth.
providerSpecific -> mrzVerification Contains information about evaluations done on some of the extracted fields in MRZ. dateOfExpiry The expiry date of the document. “VALID” if the date is in the future, “INVALID” otherwise.
documentType The type of document (e.g. passport, identity card, driver’s license). “VALID” if the type of document is valid, “INVALID” otherwise.
issuingCountry The country that issued the document. “VALID” if the value is an ISO 3166-1 alpha-3 country code, “INVALID” otherwise.
dateOfBirth The person’s date of birth. “VALID” if the date is in the past, “INVALID” otherwise.
providerSpecific -> mrzFeatureMatching Provides matching results from comparing the values of the “expected features” in “mrz” and “fields” dateOfExpiry The expiry date of the document. Enum: Paper feature matching
lastName The person’s last name(s).
issuingAuthority The name of the authority that issued the document.
firstName The person’s first name(s).
documentNumber The document’s number.
dateOfBirth The person’s date of birth.
drivingPermits The person’s driving permits.
personalNumber The personal ID number in the document.
dateOfIssue The issue date of the document.
providerSpecific > redactionResult Provides information about the redaction results.

Notes:

  • This information only exists if “redact” is sent in the request body. For more details, see Redaction (usage).
  • The redaction results do not have any impact on the process’ final status. The process status indicates the success of the verification and redaction is a parallel feature.
fullRedaction true: All fields that were requested to be redacted were found (thus, were successfully redacted).

false: At least one of the fields that were requested to be redacted was not found (thus could not be redacted).

Boolean
partialRedaction true: At least one of the fields that were requested to be redacted were found (thus, were redacted). Check the value of “fullRedaction” to see if they all were redacted or not.

false: None of the fields requested to be redacted were found (thus no field could be redacted).

Boolean
Rejected process (Signicat Paper)

This is an example of a Get process response for a Signicat Paper process that was rejected:

{
    "processId": "processId",
    "provider": "signicatpaper",
    "status": "rejected",
    "createdAt": "createdAt",
    "updatedAt": "updatedAt",
    "finalResult": {
        "firstName": "Willeke Liselotte",
        "lastName": "De Bruijn",
        "dateOfExpiry": "2016-10-20",
        "gender": "F",
        "nationality": "NLD",
        "documentType": "passport",
        "documentNumber": "XY1101P52",
        "issuingCountry": "NLD",
        "dateOfBirth": "1965-03-10"
    },
    "providerSpecific": {
        "verification": {
            "type": "MRZ_ONLY",
            "status": "false"
        },
        "mrz": {
            "firstName": "Willeke Liselotte",
            "lastName": "De Bruijn",
            "dateOfExpiry": "2016-10-20",
            "nationality": "NLD",
            "gender": "F",
            "documentType": "passport",
            "issuingCountry": "NLD",
            "documentNumber": "XY1101P52",
            "dateOfBirth": "1965-03-10",
            "personalNumber": "999999990"
        },
        "mrzChecksum": {
            "dateOfExpiry": "VALID",
            "documentNumber": "VALID",
            "dateOfBirth": "VALID",
            "personalNumber": "VALID"
        },
        "mrzVerification": {
            "dateOfExpiry": "INVALID",
            "documentType": "VALID",
            "issuingCountry": "VALID",
            "dateOfBirth": "VALID"
        },
        "errors": ["Invalid date_of_expiry: NOT in the future, value 2016-10-20"]
    }
}
Inconclusive process (Signicat Paper)

This is an example of a Get process response for a Signicat Paper process that was inconclusive:

{
    "processId": "processId",
    "provider": "signicatpaper",
    "status": "inconclusive",
    "createdAt": "createdAt",
    "updatedAt": "updatedAt",
    "providerSpecific": {
        "verification": {
            "type": "FEATURES_ONLY",
            "status": "true"
        },
        "features": {
            "firstName": "Elisabeth",
            "lastName": "Ul5Und",
            "issuingAuthority": "STATENS VEGVESEN",
            "gender": "UNEXPECTED_VALUE",
            "documentNumber": "47 00 006492 4",
            "dateOfBirth": "1979-06-28",
            "personalNumber": "280679 32635",
            "dateOfIssue": "2000-08-23"
        },
        "featuresVerification": {
            "dateOfExpiry": "MISSING",
            "lastName": "FOUND",
            "issuingAuthority": "FOUND",
            "firstName": "FOUND",
            "documentNumber": "FOUND",
            "dateOfBirth": "VALID",
            "drivingPermits": "FOUND",
            "personalNumber": "FOUND",
            "dateOfIssue": "VALID"
        }
    }
}
Connect results

Connect results contain the following elements in the providerSpecific area:

  • idToken: Token issued as a result of the end-user authentication. It is always returned in JWT format (encrypted or not, depending on the contract agreement).
  • userInfo: User information that can be accessed after the authentication is successful. It can be returned in JSON or JWT format (encrypted or not, depending on the contract agreement).
  • error: Displayed only if an error occurred. Information about any problem that may have happened during the authentication process. Always returned in JSON format.

Notes about finalResult in Connect processes:
The Connect provider’s finalResult does not follow the same rules for normalization as with other providers.

Since Connect allows use any eID method, this means that the Assure API never knows which ID method is used in each ‘connect’ process, thus it will not be able to normalize the values obtained.

Note: If userInfo comes encrypted, there will be no finalResult in the Get Process response, even if the authentication was successful:

userInfo format* finalResult
JSON Yes
JWT not encrypted Yes
JWT encrypted No

* As contractually agreed.
Examples of userInfo:

  • JWT format:
"userInfo":"eyJraWQiOiJhbnkub2lkYy50ZXN0Lmp3ay52LjEiLCJhbGciOiJSUzI1NiJ9.eyJjb25zdW1lci5iaW4iOiJGQU5UQVNZQkFOSzEyMzQ1Njc4OTAiLCJzdWIiOiJGS2lqRnNFS1h6NTliWHVyd2FmdXl3UEVjbmF4YzZSMCIsImFkZHJlc3MiOnsiY291bnRyeSI6IkRFIiwicG9zdGFsX2NvZGUiOiIwMDAwQUEifSwiY29uc3VtZXIuaW5pdGlhbHMiOiJWSiIsImdlbmRlciI6IjEiLCJpZGluLnJhYm8uY29uc3VtZXIuYmluIjoiRkFOVEFTWUJBTksxMjM0NTY3ODkwIiwic2lnbmljYXQubmF0aW9uYWxfaWQiOiJGQU5UQVNZQkFOSzEyMzQ1Njc4OTAiLCJjb25zdW1lci5wcmVmZXJyZWRsYXN0bmFtZXByZWZpeCI6ImRlIiwiY29uc3VtZXIucGFydG5lcmxhc3RuYW1lIjoiSmFuc2VuIiwiZ2l2ZW5fbmFtZSI6IlZKIiwiY29uc3VtZXIubGVnYWxsYXN0bmFtZXByZWZpeCI6ImRlIiwiY29uc3VtZXIucHJlZmVycmVkbGFzdG5hbWUiOiJWcmllcy1KYW5zZW4iLCJpZGluLmNvbnN1bWVyLmxlZ2FsbGFzdG5hbWVwcmVmaXgiOiJkZSIsImZhbWlseV9uYW1lIjoiVnJpZXMifQ.Xp6fPz2UprQE21Y1Mbms4LkmydDy4caQUitZsB-2aytBTBNVaLO78U7MqszLCUaIE4fL0MHNmd7-eigDc_TOWQBqAYz_SVhXKMDw9tj1GYdp52T2kqytW86c6YaeQ20rGKxIR4e9jOOJj0N4lEwTMc67FAO9Lhy8r5EfJDnPt0mBhPhbUvYxII42tm0M12-3qBIHkdAhuyv-wv0RH9AymgZfRNWNnfJSPcj_9a9YpE692SZCz8U24IIQy6tSWh40fN40yfy_2Sc6M4sWi2Cs-UAvk0wifW5bpAjOwnj0bkoeTvqiljxch0LQKLNWVKWoxhICeHzuKKlA_bZyoXMGjA"
  • JSON format:
{
    "userInfo": {
        "consumer.bin": "FANTASYBANK1234567890",
        "sub": "FKijFsEKXz59bXurwafuywPEcnaxc6R0",
        "consumer.initials": "VJ",
        "gender": "1",
        "idin.rabo.consumer.bin": "FANTASYBANK1234567890",
        "signicat.national_id": "FANTASYBANK1234567890",
        "consumer.preferredlastnameprefix": "de",
        "consumer.partnerlastname": "Jansen",
        "given_name": "VJ",
        "test1": "country",
        "test2": "0000AA",
        "consumer.legallastnameprefix": "de",
        "consumer.preferredlastname": "Vries-Jansen",
        "idin.consumer.legallastnameprefix": "de",
        "family_name": "Vries"
    }
}
Final status mapping (Connect)

The status of the Connect processes is mapped directly from the result of the authentication:

Process final status
Description
accepted The end-user’s authentication was successful.
rejected The end-user’s authentication failed.
canceled The authentication was canceled by the end-user.
Accepted process (Connect)

This is an example of a Get process response for a Connect process that was accepted. Here, the iDIN method is used as an example.

JSON format:

In this example, finalResult contains only a few fields. The used authentication method (in this case, iDIN), provides only the first name, last name, gender and personal number. Thus, that is the only information that the Assure API can add to finalResult.

This is an example of an accepted Get process response for Connect:

{
    "processId": "44ab57ca-3d5e-458d-8b0c-e9a1a08e9cd9",
    "provider": "connect:idin",
    "status": "accepted",
    "createdAt": "2020-01-21T15:25:30Z",
    "updatedAt": "2020-01-21T15:26:08Z",
    "finalResult": {
        "firstName": "VJ",
        "lastName": "Vries",
        "gender": "1",
        "personalIdentificationNumber": "FANTASYBANK1234567890"
    },
    "providerSpecific": {
        "idToken": "eyJraWQiOiJhbnkub2lkYy50ZXN0Lmp3ay52LjEiLCJhbGciOiJSUzI1NiJ9.eyJhY3IiOiJ1cm46c2lnbmljYXQ6b2lkYzptZXRob2Q6aWRpbiIsImF1ZCI6ImNsaWVudC5hc3N1cmUuY29ubmVjdC5kZWxlZ2F0ZSIsInN1YiI6IkZLaWpGc0VLWHo1OWJYdXJ3YWZ1eXdQRWNuYXhjNlIwIiwibmJmIjoxNTc5NjIwMzY4LCJhbXIiOiJ1cm46a3NpOm5hbWVzOlNBTUw6Mi4wOmFjOmlESU4iLCJhdXRoX3RpbWUiOjE1Nzk2MjAzNjYsImlzcyI6Imh0dHBzOlwvXC9kZXYwMS5zaWduaWNhdC5jb21cL29pZGMiLCJleHAiOjE1Nzk2MjM5NjgsIm5vbmNlIjoiZjQwZGVlNjEtMmUwNy00YmE4LTgxZjAtYTJiMTViZTcxZjBjIiwiaWF0IjoxNTc5NjIwMzY4fQ.qCCyhOp16OMDPNOrAz-JbcuI5VRoGNnaGzD19GQAnBbqniFXCQakyLSbbZsjsXa0uxU0uEzpcOC131TP85cyIxQLH01Gw2kdZ9QN3YZyGQt6ZRk5wNczKi2OOD9tpB0nYKg9tglTcRylGwyXSkTba6YJ_jg_NvU_FkIx_5LIQtyI96AC3ValpZbv3KNnwttpR4L8IIRg3LcAYOVaIrm4aF_dgCctYJSEQlN3Kf0AuWr6drvbMFqhfKavWaC9rjuzNunFrf-msk4kYhsyiZ7dhUNLSUp-wIp-3ffeAjsErRjmMF5ss2lalMF9MriB36ZybqWCj5LYb4jYyPcDLBaUlA",
        "userInfo": {
            "consumer.bin": "FANTASYBANK1234567890",
            "sub": "FKijFsEKXz59bXurwafuywPEcnaxc6R0",
            "consumer.initials": "VJ",
            "gender": "1",
            "idin.rabo.consumer.bin": "FANTASYBANK1234567890",
            "signicat.national_id": "FANTASYBANK1234567890",
            "consumer.preferredlastnameprefix": "de",
            "consumer.partnerlastname": "Jansen",
            "given_name": "VJ",
            "consumer.legallastnameprefix": "de",
            "consumer.preferredlastname": "Vries-Jansen",
            "idin.consumer.legallastnameprefix": "de",
            "family_name": "Vries"
        }
    }
}

JWT not encrypted format:

In this example, the user information is in JWT format but it is not encrypted. This allows the Assure API to get the information from there (by decoding the JWT) and fill the final result.

{
    "processId": "b7634e9e-7416-4ea2-bd6d-40a42c954f0d",
    "provider": "connect:idin",
    "status": "accepted",
    "createdAt": "2020-01-21T16:12:33Z",
    "updatedAt": "2020-01-21T16:13:01Z",
    "finalResult": {
        "firstName": "VJ",
        "lastName": "Vries",
        "gender": "1",
        "personalIdentificationNumber": "FANTASYBANK1234567890"
    },
    "providerSpecific": {
        "idToken": "eyJraWQiOiJhbnkub2lkYy1lbmNyeXB0aW9uLnRlc3QuandrLnYuMyIsImN0eSI6IkpXVCIsImVuYyI6IkExMjhDQkMtSFMyNTYiLCJhbGciOiJSU0EtT0FFUCJ9.cl5eO0QH92ZjBWwgGOF_OTSNe4rC1vCD_-JfIUgBWNaIHljWm2IXBYw_BVVPDIwpDz6o9Z1iYfALB0Bahce1ffzcCFlaukT-7HM-F2h8iHktAnWeg2ynLH9PB5ACRZNDoM-9ADZ63_tIcgs2hiX_pQELbiDD-OJ63cKOuZbwQQmaZe9YeEH2aXvRR3ELC61g7QyYuico3HTfyCA1WxpmPNIceQWdm-KFMCiyJCPgoMxyW5nzN1VQrORPBKjnKfdqyoC8v9-8NcckUCURNbdul2s9dSyPmDM14Xc23LM6xSjqVh0bGvgOzrldGgq7EBNbxEP48g3BZviiBCs2cQU_vw.88iqzXAJiJH-8dpdw3QzZA.QoVKRhH1ocJCRDT-P3WS1ILrIp_lPzzba8xh41BxKev525DXrivhEhbppRUNU1YdW_1Xhk2eN41s_-5AE1p3oOKCmt5ckct5QyxqiuZaU056L7dWbv1aa3vPFiEnrTHt191FFwYLcKAz-o6S5xwJXYh8NucxXGd_MvyVKc9Oy9-Dm7ZXhlsBBGpseIQcYxMfaGxrtiCnOHrYj36WC6F25Ma0sr99tSej-83GIhSIk4jihjaTFxdlxdnpducV6hRxsZaXTwWGsmH74ryq2QjEqdGScZuu6qSkfoiABoUSVnPryE09P3SUIbHw8lJM304ZpJ5z2mHWRKbQvp2RGackfTMMmdNex64w-XqY0wVMj20A3FlnKxtuXHMm1KrtopTX3gMicRCX-VxU1hJZmzfriGMaXCWOonYevf1LYFlCgzUk2zQ5Cb2q9MY6Re11aWAu70DmO7TBXUKfR9Od6Yxx3JZH9Q32UzUbBe2J41YjbHxXSLsrihxNx71vVfkxfngf7NILrvafrOcC1bRpyv6LncKsr7qdzoQmz5bLtJF7tAb7zE4z5rndv0eOxE7UUTzbD6wBwQ_bBB-qmUciWQYujGgnqiB1k4lxsNSBUGFpq_YbQOftn-X-kxOC-UdlxaKNUu_GGriOLG-Q21aYLkigakh9gWa8pOKc2UVGQSGTDmONE_n-u-PCjSNE69U5_wnTA9MKka9taS5XANcwuQumLvT7BmJEEBjdyveFrn8HIz_0mn_B1fyzBa28m1MrFgU2WhtVN6ilsBVz9mhLQYqzKvO2V63bLFB7cHvdeFtbh9JBp2DdOpHXWbwXSFfoDKM877kZ_SKV71ZJP7-y2sGxgWZsg8CZUvHud-APhAqUjZJ4a9FAq80gIvH9APSMJE2SdvwzmOk5NaQUD5alqtnY49s-1nP8xKHspZ49irs1X9Avf52N3iNb2_GRLtGdWyuGoP640COcptup94oJ-0bJlcKj7C_kZzTswPSjpBS-5cyMFGqsgSEOn1KRZSCGUtCkYmG_KhSfcsbfHhs_WngP_j_7gnACKueTiQqD0XLBGKp7baj7DN2oNu-oEMfXBUDJGsXr1BGF3z2yCLUUPOgbV7PPnYOOQ12hi8KY3UJ6DbQ.TZZZyQIRNEDDpCu6kb_1FA",
        "userInfo": "eyJraWQiOiJhbnkub2lkYy50ZXN0Lmp3ay52LjEiLCJhbGciOiJSUzI1NiJ9.eyJjb25zdW1lci5iaW4iOiJGQU5UQVNZQkFOSzEyMzQ1Njc4OTAiLCJzdWIiOiJGS2lqRnNFS1h6NTliWHVyd2FmdXl3UEVjbmF4YzZSMCIsImFkZHJlc3MiOnsiY291bnRyeSI6IkRFIiwicG9zdGFsX2NvZGUiOiIwMDAwQUEifSwiY29uc3VtZXIuaW5pdGlhbHMiOiJWSiIsImdlbmRlciI6IjEiLCJpZGluLnJhYm8uY29uc3VtZXIuYmluIjoiRkFOVEFTWUJBTksxMjM0NTY3ODkwIiwic2lnbmljYXQubmF0aW9uYWxfaWQiOiJGQU5UQVNZQkFOSzEyMzQ1Njc4OTAiLCJjb25zdW1lci5wcmVmZXJyZWRsYXN0bmFtZXByZWZpeCI6ImRlIiwiY29uc3VtZXIucGFydG5lcmxhc3RuYW1lIjoiSmFuc2VuIiwiZ2l2ZW5fbmFtZSI6IlZKIiwiY29uc3VtZXIubGVnYWxsYXN0bmFtZXByZWZpeCI6ImRlIiwiY29uc3VtZXIucHJlZmVycmVkbGFzdG5hbWUiOiJWcmllcy1KYW5zZW4iLCJpZGluLmNvbnN1bWVyLmxlZ2FsbGFzdG5hbWVwcmVmaXgiOiJkZSIsImZhbWlseV9uYW1lIjoiVnJpZXMifQ.Xp6fPz2UprQE21Y1Mbms4LkmydDy4caQUitZsB-2aytBTBNVaLO78U7MqszLCUaIE4fL0MHNmd7-eigDc_TOWQBqAYz_SVhXKMDw9tj1GYdp52T2kqytW86c6YaeQ20rGKxIR4e9jOOJj0N4lEwTMc67FAO9Lhy8r5EfJDnPt0mBhPhbUvYxII42tm0M12-3qBIHkdAhuyv-wv0RH9AymgZfRNWNnfJSPcj_9a9YpE692SZCz8U24IIQy6tSWh40fN40yfy_2Sc6M4sWi2Cs-UAvk0wifW5bpAjOwnj0bkoeTvqiljxch0LQKLNWVKWoxhICeHzuKKlA_bZyoXMGjA"
  }
}

JWT encrypted format:

Since the user information is in JWT encrypted format, the Assure API is not able to decode it. Thus, there is no finalResult in the response in this example:

{
    "processId": "b7634e9e-7416-4ea2-bd6d-40a42c954f0d",
    "provider": "connect:idin",
    "status": "accepted",
    "createdAt": "2020-01-21T16:12:33Z",
    "updatedAt": "2020-01-21T16:13:01Z",
    "providerSpecific": {
        "idToken": "eyJraWQiOiJhbnkub2lkYy1lbmNyeXB0aW9uLnRlc3QuandrLnYuMyIsImN0eSI6IkpXVCIsImVuYyI6IkExMjhDQkMtSFMyNTYiLCJhbGciOiJSU0EtT0FFUCJ9.cl5eO0QH92ZjBWwgGOF_OTSNe4rC1vCD_-JfIUgBWNaIHljWm2IXBYw_BVVPDIwpDz6o9Z1iYfALB0Bahce1ffzcCFlaukT-7HM-F2h8iHktAnWeg2ynLH9PB5ACRZNDoM-9ADZ63_tIcgs2hiX_pQELbiDD-OJ63cKOuZbwQQmaZe9YeEH2aXvRR3ELC61g7QyYuico3HTfyCA1WxpmPNIceQWdm-KFMCiyJCPgoMxyW5nzN1VQrORPBKjnKfdqyoC8v9-8NcckUCURNbdul2s9dSyPmDM14Xc23LM6xSjqVh0bGvgOzrldGgq7EBNbxEP48g3BZviiBCs2cQU_vw.88iqzXAJiJH-8dpdw3QzZA.QoVKRhH1ocJCRDT-P3WS1ILrIp_lPzzba8xh41BxKev525DXrivhEhbppRUNU1YdW_1Xhk2eN41s_-5AE1p3oOKCmt5ckct5QyxqiuZaU056L7dWbv1aa3vPFiEnrTHt191FFwYLcKAz-o6S5xwJXYh8NucxXGd_MvyVKc9Oy9-Dm7ZXhlsBBGpseIQcYxMfaGxrtiCnOHrYj36WC6F25Ma0sr99tSej-83GIhSIk4jihjaTFxdlxdnpducV6hRxsZaXTwWGsmH74ryq2QjEqdGScZuu6qSkfoiABoUSVnPryE09P3SUIbHw8lJM304ZpJ5z2mHWRKbQvp2RGackfTMMmdNex64w-XqY0wVMj20A3FlnKxtuXHMm1KrtopTX3gMicRCX-VxU1hJZmzfriGMaXCWOonYevf1LYFlCgzUk2zQ5Cb2q9MY6Re11aWAu70DmO7TBXUKfR9Od6Yxx3JZH9Q32UzUbBe2J41YjbHxXSLsrihxNx71vVfkxfngf7NILrvafrOcC1bRpyv6LncKsr7qdzoQmz5bLtJF7tAb7zE4z5rndv0eOxE7UUTzbD6wBwQ_bBB-qmUciWQYujGgnqiB1k4lxsNSBUGFpq_YbQOftn-X-kxOC-UdlxaKNUu_GGriOLG-Q21aYLkigakh9gWa8pOKc2UVGQSGTDmONE_n-u-PCjSNE69U5_wnTA9MKka9taS5XANcwuQumLvT7BmJEEBjdyveFrn8HIz_0mn_B1fyzBa28m1MrFgU2WhtVN6ilsBVz9mhLQYqzKvO2V63bLFB7cHvdeFtbh9JBp2DdOpHXWbwXSFfoDKM877kZ_SKV71ZJP7-y2sGxgWZsg8CZUvHud-APhAqUjZJ4a9FAq80gIvH9APSMJE2SdvwzmOk5NaQUD5alqtnY49s-1nP8xKHspZ49irs1X9Avf52N3iNb2_GRLtGdWyuGoP640COcptup94oJ-0bJlcKj7C_kZzTswPSjpBS-5cyMFGqsgSEOn1KRZSCGUtCkYmG_KhSfcsbfHhs_WngP_j_7gnACKueTiQqD0XLBGKp7baj7DN2oNu-oEMfXBUDJGsXr1BGF3z2yCLUUPOgbV7PPnYOOQ12hi8KY3UJ6DbQ.TZZZyQIRNEDDpCu6kb_1FA",
        "userInfo": "eyJraWQiOiJhbnkub2lkYy50ZXN0Lmp3ay52LjEiLCJhbGciOiJSUzI1NiJ9.eyJjb25zdW1lci5iaW4iOiJGQU5UQVNZQkFOSzEyMzQ1Njc4OTAiLCJzdWIiOiJGS2lqRnNFS1h6NTliWHVyd2FmdXl3UEVjbmF4YzZSMCIsImFkZHJlc3MiOnsiY291bnRyeSI6IkRFIiwicG9zdGFsX2NvZGUiOiIwMDAwQUEifSwiY29uc3VtZXIuaW5pdGlhbHMiOiJWSiIsImdlbmRlciI6IjEiLCJpZGluLnJhYm8uY29uc3VtZXIuYmluIjoiRkFOVEFTWUJBTksxMjM0NTY3ODkwIiwic2lnbmljYXQubmF0aW9uYWxfaWQiOiJGQU5UQVNZQkFOSzEyMzQ1Njc4OTAiLCJjb25zdW1lci5wcmVmZXJyZWRsYXN0bmFtZXByZWZpeCI6ImRlIiwiY29uc3VtZXIucGFydG5lcmxhc3RuYW1lIjoiSmFuc2VuIiwiZ2l2ZW5fbmFtZSI6IlZKIiwiY29uc3VtZXIubGVnYWxsYXN0bmFtZXByZWZpeCI6ImRlIiwiY29uc3VtZXIucHJlZmVycmVkbGFzdG5hbWUiOiJWcmllcy1KYW5zZW4iLCJpZGluLmNvbnN1bWVyLmxlZ2FsbGFzdG5hbWVwcmVmaXgiOiJkZSIsImZhbWlseV9uYW1lIjoiVnJpZXMifQ.Xp6fPz2UprQE21Y1Mbms4LkmydDy4caQUitZsB-2aytBTBNVaLO78U7MqszLCUaIE4fL0MHNmd7-eigDc_TOWQBqAYz_SVhXKMDw9tj1GYdp52T2kqytW86c6YaeQ20rGKxIR4e9jOOJj0N4lEwTMc67FAO9Lhy8r5EfJDnPt0mBhPhbUvYxII42tm0M12-3qBIHkdAhuyv-wv0RH9AymgZfRNWNnfJSPcj_9a9YpE692SZCz8U24IIQy6tSWh40fN40yfy_2Sc6M4sWi2Cs-UAvk0wifW5bpAjOwnj0bkoeTvqiljxch0LQKLNWVKWoxhICeHzuKKlA_bZyoXMGjA"
   }
}
Rejected process (Connect)

This is an example of a Get process response for a Connect process that was rejected:

{
    "processId": "1ad420ff-7b71-4322-8917-64fec28fe118",
    "provider": "connect:idin",
    "status": "rejected",
    "createdAt": "2020-01-21T16:37:21Z",
    "updatedAt": "2020-01-21T16:37:53Z",
    "providerSpecific": {
        "error": {
            "errorDescription": "The Resource Owner did not complete the login. urn:signicat:error:internal:Expired; ",
            "error": "access_denied"
        }
    }
}
Inconclusive process (Connect)

Connect processes do not have any inconclusive status.

Canceled process (Connect)

This is an example of a Get process response for a Connect process that was canceled:

{
    "processId": "ab5739a7-92ad-429d-a6d9-7cb233b2865c",
    "provider": "connect:idin",
    "status": "canceled",
    "createdAt": "2020-01-28T12:24:58Z",
    "updatedAt": "2020-01-28T12:25:32Z",
    "providerSpecific": {
        "error": {
            "errorDescription": "The Resource Owner did not complete the login. urn:signicat:error:usercancel; The process was aborted by the end user",
            "error": "access_denied"
        }
    }
}

  Files in dossier (usage)

This topic describes how to use the files in the dossiers (see also reference descriptions and the OpenAPI documentation).

It is possible to keep some of the files relative to the end-user directly in the dossier, as opposed to having them only inside the process.

A dossier can keep these types of files:

The supported formats for these files are the same as for the images in the process. For details, see Images (usage) section.

By using this feature you can:

Add files directly to the dossier

You can save images directly in the dossier the same way as you do in a process: You call the Dossier/Set Images endpoint with the images in a dataURL format. You can set all the images at once or one at a time.

Example:

curl --location --request POST 'https://preprod.signicat.com/assure/dossiers/e6137ef5-6470-4e17-897d-9ccde03dc9eb/files' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "front": "data:image/jpeg;base64,/9j/4AAQSkZJR...",
  "back": "data:image/jpeg;base64,/9j/4AAQSkZJR...",
  "selfie": "data:image/jpeg;base64,/9j/4AAQSkZJR..."
}'

Use files from the dossier in a process

If you request to startVerification on a process that has no images, the Assure API checks if the dossier contains any images and tries to use them to send to the provider in that process.

Note: This only works for providers that allow uploading the images directly through the Assure API.

Copy the files from a process into the dossier

If you have image files inside a process, you can copy them into the dossier: You call the Dossier/Set Images endpoint and give it the ID of the process from which you want to copy the images from.

Example:

curl --location --request POST 'https://preprod.signicat.com/assure/dossiers/e6137ef5-6470-4e17-897d-9ccde03dc9eb/files' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "processId": "b3f0c899-a0a1-4a69-a0eb-7aa64aaf9bd0"
}'

  Start Web SDK Flow (usage)

Note: This service is deprecated. Please use the Start Capture Flow service instead.

This topic describes how to use this service to capture and upload ID images (see also reference descriptions and the OpenAPI documentation).

This service allows you to use Onfido’s and ElectronicID’s (JS) Web SDKs without integrating directly with them. Although Signicat Paper is part of the list of providers that supply a Web (JS) SDK, it is not available in the Start Web SDK Flow service.

By calling this service, it will:

Request

When you call this service, you provide similar information as in the Create process service:

You must also provide some specific information to this service:

Response

In the response, you get a URL address. This URL redirects the end-user so they can capture and upload the ID images.
Note: This URL is valid for 3 minutes and can be accessed only once.

RedirectURL

After the end-user has finished capturing and uploading the ID images, they are redirected to the redirectURL you indicated in the request. This redirectURL contains information about the dossierId, the processId and the flow’s status.

Example of a redirectURL after the WebSDK flow is finished:

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

At this point, Assure API starts the verification automatically. Afterwards, you can use the dossierId and processId in the Get process service to obtain information about the verification result. If you sent a notificationURL in the service request, you get a callback notification when the process is finished. The callback also contains dossierId and processId. For more details, see Callbacks (usage).

  Start Capture Flow (usage)

This topic describes how to use this service to perform eIDV in a web context (see also the reference descriptions and the Open API documentation). From the end-user’s perspective, this service helps them capture and upload ID images.

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 this service is simpler than integrating using the SDKs directly.

You can use this service with all the providers that run in a web environment (currently Onfido, ElectronicID and Signicat Paper).

Overview

When you call the Start Capture Flow service, it will:

Request parameters

When you call the Start Capture Flow service, you must provide similar information as in the Create process service:

(1) This service request accepts an array of “providers”. This is because you can use this service with one or with two providers at the same time.
(2) Parameters specific to the providers must be sent inside that “provider” node. See request example below.

You must also provide some information specifically required by this service:

Optionally, there are other parameters you can use:

Example of a basic Start Capture Flow request

This example uses Signicat Paper as provider:

{
    "providers": [
            {
                "provider": "onfido",
                "processType": "documentSelfie"
            }],
    "redirectUrl": "https://my-website.com/"
}
Response

In the response, you get a URL address:

https://preprod.signicat.com/capture/#/artifact=1wk4s36hr9p9ywsg8wqxqrfpxf7c3yg1yj2uk9lzh555y2o02u

Send the end-user to this URL. This is where the JS SDK of the provider is loaded and the end-user can capture and upload the ID images. For more info on the available SDKs please refer to the “Using the SDKs available in the capture service” section.

Usage details

After the end-user has finished capturing and uploading the ID images, they are redirected to the redirectURL (the one you indicated in the request). When the redirect happens, this redirectURL is appended with information about the dossierId, the processId and the process’s status:

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

At this point, the Assure API requests the provider to start performing the verification. When the verifiation is done, you can use the dossierId and processId in the Get Process service to obtain information about the verification result.

If you sent a notificationURL in the service request, you will get a callback notification as soon as the verification is done, i.e., the process reached a final status (e.g. “accepted, “rejected“, “inconclusive“, “canceled“). That callback will also contain the same dossierId and processId you got in the redirectUrl. For more details about how to use callback notifications, see Callbacks (usage).

Using the SDKs available in the capture service

The capture service embeds the Onfido and ElectronicID providers’ JS SDKs. It also includes a Signicat “capture” SDK that is used with the Signicat Paper provider but can also be used with some of the other providers as long as the provider and processType combination allow direct upload of images through the Assure API.

The table below indicates which SDKs are available to be used with each provider and, for each, which is the default value if “sdk” is not explicitly set in the request body:

provider ‘native’ SDK ‘capture’ SDK
Signicat Paper (default)
Onfido document or documentSelfie (default)
Onfido documentVideo (default)
ElectronicID (default)

If the capture request contains two providers, the default SDK will always be the default of the provider that is not Signicat Paper.

Using two providers in the capture flow

You can use the Start Capture Flow service using Signicat Paper and any of the other third-party providers.

The most common use cases for this feature is to combine the services of the third-party providers with features available only through the Signicat Paper provider, such as:

How to use two providers

In the request body, indicate the provider you want to use to perform the identity verification (e.g. “onfido”) and also the “signicatpaper” provider:

{
    "providers": [
        {
            "provider": "onfido"
        },
        {
            "provider": "signicatpaper"
        }
    ],
    "redirectUrl": "https://my-website.com/"
}

You can define any other parameters for each provider, as in any other Create Process / Start Capture Flow request. In the example above we use the default values for both.

As usual, redirect the end-user to the URL you get in the response so that they can capture images and perform the verification.

After the end-user has finished the verification, the Assure API creates two processes in the dossier – one for each provider. For that reason, when using two providers, the redirectURL is appended only with dossierId and status (and no processId):

https://myredirecturl.com/?dossierId=c03e66c7-8230-4020-a084-5a34a925d5fe&status=processing

 Capture configurations (uiProfile)

The Start Capture Flow service may receive a parameter named uiProfile. This uiProfile must be created using the Capture/Create configuration  endpoint and you can later get or update that configuration.

The sections below detail the configurations available per provider/SDK:

Capture SDK configurations

The configurations items in this section will only be used when the capture SDK is being used, i.e., when the value of the “sdk” parameter in the Start Capture Flow request is “capture”.

 

Field
Description
Type
Default
Example / Possible values
pageTitle The title to be displayed in the browser tab. This field also affects Onfido and EID. String “Signicat Capture”
favicon An image, provided in the format of Data URI or link, indicating the favicon to be displayed in the browser tab. This field also affects Onfido and EID. String (signicat icon)
fontName The name of the font to be used in the UI. This field also affects Onfido and EID. String null Example: “Raleway
fontUrl The URL to the CSS file with the font-face. This field also affects Onfido and EID. String null Example: “https://fonts.googleapis.com/css?family=Raleway:400,500,600,700&display=swap
primaryColor The HEX or RGB code for the primary color. This field also affects Onfido and EID. String “#5AAFFF” HEX: “#5AAFFF”
RGB: “rgb(90, 175, 255)”
fontColor The HEX or RGB code for the general font color. This field also affects Onfido and EID. String “#000000” HEX: “#000000”
RGB: “rgb(0, 0, 0)”
buttonsColor The HEX or RGB code for the buttons background color. If not set, it will default to the primaryColor. This field also affects Onfido and EID. String null
buttonsHoverColor The HEX or RGB code for the buttons background color when hovered. If not set, it will default to the primaryColor. This field also affects Onfido and EID.
buttonsTextColor The HEX or RGB code for the color of the text inside the buttons. If not set, it will default to the white. This field also affects Onfido and EID. String white
spinnerColor The HEX or RGB code for the color of the loading spinner. If not set, will default to the primaryColor. This field also affects Onfido and EID. String null
customCss Custom CSS do be loaded in the app. This should be a string containing CSS code. This field also affects Onfido and EID. String null “body { background-color: green; } .someClass { background-color: red; }”
documentTypes Filters the list of document types that the end-user will be able to choose from.

If not set or set to “null” all the document types supported by the provider will be displayed.

This field also affects EID.

Array null Possible values depend on the provider. Please use the Get Document Types service  to know which document types are supported by a specific provider.

Example: [ “identityCard”, “passport”, “driversLicense”]

documentCountries Filters the list of countries that the end-user will be able to choose from. This list can be specified per type of document (see “documentTypes“).

If not set or set to “null” all the countries supported by the provider will be displayed.

It receives an object where the keys refer to the document type and the value can either be an array of country codes or the string “univ” if you want to support all the countries in the world for that specific document type (“univ” is currently supported only for documents of type passport).

This field also affects Onfido and EID.

Object null Example where all passports will be accepted but only id cards from Denmark and Sweden:
“{ “passport”: “univ”, “identityCard”: [ “DNK”, “SWE” ] }”
twoSidedPassports List of countries where the backside of the passport should be captured too.

It receives either an array of country codes or a string “all” (to ask for the backside of all passports) or “null” (to not ask for the backside of any passports).

Array or string (“all”) null Example: [ “NLD”, “SWE” ]
languages List of languages for the end-user to choose from. By default, capture shows the user interface in “en” and no other options. The following options can be enabled but translations must be provided. This field also affects EID.

For available translated languages, see the Translations section.

Array [ “en” ] Example: [ “en”, “pt” ]
translations Custom translations for each supported language to override the default translations from the capture SDK.

See the Translations section for details. This field also affects EID.

Object null For value descriptions, see the Translations section.

Example: { “en”: { “genericErrorTitle”: “Something went wrong”, “genericErrorDescription”: “Your session has expired.” } }

defaultCountry Helps the UI decide which country to select by default when multiple options are available. For example: To pre-select the phone country code in the mobile handover screen or to set the default country in the list of countries of the document selection screen.

This field also affects Onfido and EID.

String “NOR”
allowFileUpload Enable/disable the file upload option. Boolean true
allowTakePhoto Enable/disable the take photo option for mobile and desktop Array [ “mobile”, “desktop” ]
enableOrientationConfirmation Enable/disable the orientation confirmation step at the end of the file upload flow. Boolean false
autoCapture Enable/disable the auto-capture feature on the camera flow. Boolean false
detectGlare Enable/disable glare detection on the camera flow. Boolean false
takeSelfie Enable/disable the selfie step at the end of the capture flow (both camera and file upload).

Usage example: You want to use two providers with Onfido documentSelfie but still want to use the “capture” SDK.

Boolean false
smsDefaultCountry Country prefix to be pre-selected on the mobile handover pop up phone number input. This field also affects EID. String “NOR”
maxRetries The maximum number of retries after the verification fails, e.g. since the document could not be read, is not valid, or any other reason that may cause verification to fail. Number 0
showModalBeforeRedirect If true, the app shows the success/error modal before redirecting to the redirectUrl. If false, it redirects immediately. Boolean true
mobileHandoverTimeout Number of minutes before the mobile handover loading page times out and cancels the process. This field also affects EID. Number 0
onfidoConfig This field is for custom configurations of Onfido, i.e. if you use the ‘onfido’ provider and the ‘native’ SDK in the capture request. Object { “steps”: [ “document”, “face”, “complete” ] } For value descriptions, see Onfido SDK configurations.
Translations

This section describes possible values in the translations field (listed in the above table). This field allows you to configure new values for all strings available in the capture SDK for a given language.

Note: This feature is only available to be used with the languages currently supported by capture:

Capture will only override the values of the “translations” strings you specify in the configuration, meaning all other strings will remain untouched.

These are the text fields that you can provide a translation for:

Screens translation fields

"identityVerification": "Identity Verification",
"chooseDocumentType": "Choose the document you wish to verify",
"chooseCountry": "Select your nationality below",
"searchCountries": "Search countries",
"searchPrefix": "Search indicatives",
"uploadPicture": "Upload an image",
"retakePhoto": "Re-take photo",
"chooseFile": "Choose file",
"reuploadFile": "Re-upload file",
"confirm": "Confirm",
"cancel": "Cancel",
"genericErrorTitle": "Something went wrong",
"genericErrorDescription": "Your session has expired.",
"cancelDialogTitle": "Cancel",
"cancelDialogDescription": "Are you sure you want to exit the process?",
"cancelDialogNoButton": "No, I do not want to exit",
"cancelDialogYesButton": "Yes, I want to exit",
"cancellingDialogTitle": "Cancelling",
"cancellingDialogDescription": "We are cancelling your process, you will be redirected back automatically",
"successDialogTitle": "Success",
"successDialogDescription": "Your pictures were successfully uploaded. You will be redirected back automatically",
"verifyingOrientationHint": "Is the provided identity paper orientation displaying as shown in the illustration above?",
"confirmVerifyOrientation": "Yes they are in the correct orientation",
"denyVerifyOrientation": "No I need to rotate the images",
"cameraPermissionDenied": "We were unable to access your camera",
"frontPhotoInfo": "Place the <u>front</u> of your document roughly inside the frame below",
"backPhotoInfo": "Place the <u>back</u> of your document roughly inside the frame below",
"selfieInfo": "Align your face in the center of the circle below",
"glareWarning": "There's too much glare",
"takePhoto": "Take photo",
"scanningTitle": "Scanning",
"scanningSubtitle": "That's great, just stay in that position",
"confirmPhotoTitle": "Is the photo clear?",
"confirmPhotoSubtitle": "Make sure the photo is clear without any glare or blur",
"confirmPhotoYesButton": "Yes, use this one",
"confirmPhotoNoButton": "Retake photo",
"frontImageTab": "Front side",
"backImageTab": "Back side",
"selfieTab": "Selfie",
"retryDialogTitle": "Something went wrong",
"retryDialogDescription": "Please try again",
"retryDialogButton": "Try again",
"mobileHandoverTitle": "To verify your identity we need to verify your document",
"mobileHandoverDescription": "Please choose if you want to take pictures with your phone or if you want to provide pictures from this device",
"mobileHandoverUsePhoneButton": "Use phone (recommended)",
"mobileHandoverUseDesktopButton": "Continue on this device",
"mobileHandoverPopUpTitle": "Enter your phone number",
"mobileHandoverPopUpDescription": "We will send you an SMS link. Please open the link on your phone and continue. Do not close this window; the process continues on this device afterwards.",
"mobileHandoverPopUpButton": "Send SMS link",
"mobileHandoverPopUpWaitingTitle": "Link successfully sent to",
"mobileHandoverPopUpWaitingDescriptionLine1": "Please open the link and take a picture of your identity paper with your phone.",
"mobileHandoverPopUpWaitingDescriptionLine2": "Do not close this window.",
"mobileHandoverPopUpWaitingLoadingText": "Waiting for pictures",
"mobileHandoverPopUpWaitingResendLink": "Resend SMS link",
"mobileHandoverSuccessPageTitleLine1": "Identity document checked",
"mobileHandoverSuccessPageTitleLine2": "Continue on the device where you started the process.",
"mobileHandoverSuccessPageDescription": "You can now close this window",
"mobileHandoverErrorPageTitleLine1": "Something went wrong",
"mobileHandoverErrorPageTitleLine2": "There was a problem checking your identity document.",
"mobileHandoverErrorPageDescription": "You can now close this window" 

Document types translation fields

"passport": "Passport",
"identityCard": "Identity Card",
"driversLicense": "Drivers License",
"residencePermit": "Residence Permit",
"panCard": "Pan Card",
"passportCard": "Passport Card",
"voterId": "Voter Id",
"stateId": "State Id",
"visa": "Visa",
"workPermit": "Work Permit",
"postalIdentityCard": "Postal Identity Card",
"professionalQualificationCard": "Professional Qualification Card",
"asylumRegistrationCard": "Asylum Registration Card",
"nationalHealthInsuranceCard": "National Health Insurance Card",
"socialSecurityCard": "Social Security Card",
"aadharCard": "Aadhar Card"

Country translation fields

"countryAFG": "Afghanistan",
"countryALA": "Åland Islands",
"countryALB": "Albania",
"countryDZA": "Algeria",
"countryASM": "American Samoa",
"countryAND": "Andorra",
"countryAGO": "Angola",
"countryAIA": "Anguilla",
"countryATA": "Antarctica",
"countryATG": "Antigua and Barbuda",
"countryARG": "Argentina",
"countryARM": "Armenia",
"countryABW": "Aruba",
"countryAUS": "Australia",
"countryAUT": "Austria",
"countryAZE": "Azerbaijan",
"countryBHS": "Bahamas",
"countryBHR": "Bahrain",
"countryBGD": "Bangladesh",
"countryBRB": "Barbados",
"countryBLR": "Belarus",
"countryBEL": "Belgium",
"countryBLZ": "Belize",
"countryBEN": "Benin",
"countryBMU": "Bermuda",
"countryBTN": "Bhutan",
"countryBOL": "Bolivia",
"countryBES": "Bonaire, Sint Eustatius and Saba",
"countryBIH": "Bosnia and Herzegovina",
"countryBWA": "Botswana",
"countryBVT": "Bouvet Island",
"countryBRA": "Brazil",
"countryIOT": "British Indian Ocean Territory",
"countryBRN": "Brunei Darussalam",
"countryBGR": "Bulgaria",
"countryBFA": "Burkina Faso",
"countryBDI": "Burundi",
"countryCPV": "Cabo Verde",
"countryKHM": "Cambodia",
"countryCMR": "Cameroon",
"countryCAN": "Canada",
"countryCYM": "Cayman Islands",
"countryCAF": "Central African Republic",
"countryTCD": "Chad",
"countryCHL": "Chile",
"countryCHN": "China",
"countryCXR": "Christmas Island",
"countryCCK": "Cocos (Keeling) Islands",
"countryCOL": "Colombia",
"countryCOM": "Comoros",
"countryCOD": "Democratic Republic of the Congo",
"countryCOG": "Congo",
"countryCOK": "Cook Islands",
"countryCRI": "Costa Rica",
"countryHRV": "Croatia",
"countryCUB": "Cuba",
"countryCUW": "Curaçao",
"countryCYP": "Cyprus",
"countryCZE": "Czechia",
"countryCIV": "Côte d Ivoire",
"countryDNK": "Denmark",
"countryDJI": "Djibouti",
"countryDMA": "Dominica",
"countryDOM": "Dominican Republic",
"countryECU": "Ecuador",
"countryEGY": "Egypt",
"countrySLV": "El Salvador",
"countryGNQ": "Equatorial Guinea",
"countryERI": "Eritrea",
"countryEST": "Estonia",
"countrySWZ": "Eswatini",
"countryETH": "Ethiopia",
"countryFLK": "Falkland Islands",
"countryFRO": "Faroe Islands",
"countryFJI": "Fiji",
"countryFIN": "Finland",
"countryFRA": "France",
"countryGUF": "French Guiana",
"countryPYF": "French Polynesia",
"countryATF": "French Southern Territories",
"countryGAB": "Gabon",
"countryGMB": "Gambia",
"countryGEO": "Georgia",
"countryDEU": "Germany",
"countryGHA": "Ghana",
"countryGIB": "Gibraltar",
"countryGRC": "Greece",
"countryGRL": "Greenland",
"countryGRD": "Grenada",
"countryGLP": "Guadeloupe",
"countryGUM": "Guam",
"countryGTM": "Guatemala",
"countryGGY": "Guernsey",
"countryGIN": "Guinea",
"countryGNB": "Guinea-Bissau",
"countryGUY": "Guyana",
"countryHTI": "Haiti",
"countryHMD": "Heard Island and McDonald Islands",
"countryVAT": "Holy See",
"countryHND": "Honduras",
"countryHKG": "Hong Kong",
"countryHUN": "Hungary",
"countryISL": "Iceland",
"countryIND": "India",
"countryIDN": "Indonesia",
"countryIRN": "Iran",
"countryIRQ": "Iraq",
"countryIRL": "Ireland",
"countryIMN": "Isle of Man",
"countryISR": "Israel",
"countryITA": "Italy",
"countryJAM": "Jamaica",
"countryJPN": "Japan",
"countryJEY": "Jersey",
"countryJOR": "Jordan",
"countryKAZ": "Kazakhstan",
"countryKEN": "Kenya",
"countryKIR": "Kiribati",
"countryPRK": "Korea",
"countryKOR": "Korea",
"countryKWT": "Kuwait",
"countryKGZ": "Kyrgyzstan",
"countryLAO": "Lao",
"countryLVA": "Latvia",
"countryLBN": "Lebanon",
"countryLSO": "Lesotho",
"countryLBR": "Liberia",
"countryLBY": "Libya",
"countryLIE": "Liechtenstein",
"countryLTU": "Lithuania",
"countryLUX": "Luxembourg",
"countryMAC": "Macao",
"countryMDG": "Madagascar",
"countryMWI": "Malawi",
"countryMYS": "Malaysia",
"countryMDV": "Maldives",
"countryMLI": "Mali",
"countryMLT": "Malta",
"countryMHL": "Marshall Islands",
"countryMTQ": "Martinique",
"countryMRT": "Mauritania",
"countryMUS": "Mauritius",
"countryMYT": "Mayotte",
"countryMEX": "Mexico",
"countryFSM": "Micronesia",
"countryMDA": "Moldova",
"countryMCO": "Monaco",
"countryMNG": "Mongolia",
"countryMNE": "Montenegro",
"countryMSR": "Montserrat",
"countryMAR": "Morocco",
"countryMOZ": "Mozambique",
"countryMMR": "Myanmar",
"countryNAM": "Namibia",
"countryNRU": "Nauru",
"countryNPL": "Nepal",
"countryNLD": "Netherlands",
"countryNCL": "New Caledonia",
"countryNZL": "New Zealand",
"countryNIC": "Nicaragua",
"countryNER": "Niger",
"countryNGA": "Nigeria",
"countryNIU": "Niue",
"countryNFK": "Norfolk Island",
"countryMNP": "Northern Mariana Islands",
"countryNOR": "Norway",
"countryOMN": "Oman",
"countryPAK": "Pakistan",
"countryPLW": "Palau",
"countryPSE": "Palestine",
"countryPAN": "Panama",
"countryPNG": "Papua New Guinea",
"countryPRY": "Paraguay",
"countryPER": "Peru",
"countryPHL": "Philippines",
"countryPCN": "Pitcairn",
"countryPOL": "Poland",
"countryPRT": "Portugal",
"countryPRI": "Puerto Rico",
"countryQAT": "Qatar",
"countryMKD": "Republic of North Macedonia",
"countryROU": "Romania",
"countryRUS": "Russian Federation",
"countryRWA": "Rwanda",
"countryREU": "Réunion",
"countryBLM": "Saint Barthélemy",
"countrySHN": "Saint Helena, Ascension and Tristan da Cunha",
"countryKNA": "Saint Kitts and Nevis",
"countryLCA": "Saint Lucia",
"countryMAF": "Saint Martin",
"countrySPM": "Saint Pierre and Miquelon",
"countryVCT": "Saint Vincent and the Grenadines",
"countryWSM": "Samoa",
"countrySMR": "San Marino",
"countrySTP": "Sao Tome and Principe",
"countrySAU": "Saudi Arabia",
"countrySEN": "Senegal",
"countrySRB": "Serbia",
"countrySYC": "Seychelles",
"countrySLE": "Sierra Leone",
"countrySGP": "Singapore",
"countrySXM": "Sint Maarten",
"countrySVK": "Slovakia",
"countrySVN": "Slovenia",
"countrySLB": "Solomon Islands",
"countrySOM": "Somalia",
"countryZAF": "South Africa",
"countrySGS": "South Georgia and the South Sandwich Islands",
"countrySSD": "South Sudan",
"countryESP": "Spain",
"countryLKA": "Sri Lanka",
"countrySDN": "Sudan",
"countrySUR": "Suriname",
"countrySJM": "Svalbard and Jan Mayen",
"countrySWE": "Sweden",
"countryCHE": "Switzerland",
"countrySYR": "Syrian Arab Republic",
"countryTWN": "Taiwan",
"countryTJK": "Tajikistan",
"countryTZA": "Tanzania",
"countryTHA": "Thailand",
"countryTLS": "Timor-Leste",
"countryTGO": "Togo",
"countryTKL": "Tokelau",
"countryTON": "Tonga",
"countryTTO": "Trinidad and Tobago",
"countryTUN": "Tunisia",
"countryTUR": "Turkey",
"countryTKM": "Turkmenistan",
"countryTCA": "Turks and Caicos Islands",
"countryTUV": "Tuvalu",
"countryUGA": "Uganda",
"countryUKR": "Ukraine",
"countryARE": "United Arab Emirates",
"countryGBR": "United Kingdom",
"countryUMI": "United States Minor Outlying Islands",
"countryUSA": "United States of America",
"countryURY": "Uruguay",
"countryUZB": "Uzbekistan",
"countryVUT": "Vanuatu",
"countryVEN": "Venezuela",
"countryVNM": "Viet Nam",
"countryVGB": "Virgin Islands (British)",
"countryVIR": "Virgin Islands (U.S)",
"countryWLF": "Wallis and Futuna",
"countryESH": "Western Sahara",
"countryYEM": "Yemen",
"countryZMB": "Zambia",
"countryZWE": "Zimbabwe"
Onfido SDK configurations

This section describes the values of the configuration field onfidoConfig (listed in the above table).

The configuration items in this section will only be used when the Onfido native SDK is being used, i.e., when the value of the “sdk” parameter in the Start Capture Flow request is “native” and the “provider” is “onfido”.

Field
Description
Type
Default
Example / Possible values
customHtml Custom HTML code (in the form of a string) to replace the HTML of the app. String null “<div class=”custom-header-element”></div><div id=”onfido-mount”></div>”
customBackgroundImage An image, provided in the format of Data URI or link, indicating the image to be displayed as background under the Onfido SDK. String null
customHeaderLogo An image, provided in the format of Data URI or link, indicating the logo image that will be displayed in the top left corner of the page. String null
ElectronicID SDK configurations

Configuration of the ElectronicID Web (JS) SDK is not yet available through the capture configurations.

  Images (usage)

This topic describes how to upload image files and also lists the image requirements (see also reference descriptions and the OpenAPI documentation).

Images are an important part of an eIDV flow. End-users must provide images of their ID document and, in some cases, also provide/capture selfie images of themselves.

The way these images are sent to the provider may vary but those images are always kept as part of the process. The next sections provide detail on how to use images in identity verification processes.

Upload ID images

This table summarizes the available approaches for each provider:

eIDV provider Direct upload using Assure API Use provider’s SDK to capture and upload images
Web SDK iOS SDK Android SDK
Onfido

Available only for “document” and “documentSelfie” process types.

Electronic ID
ReadID
Signicat Paper

 

Why aren’t all options available for all providers?

Each provider has specific requirements for how the images are captured. This means that some providers accept methods that others don’t. For example, ElectronicID requires that a video is recorded during image capturing, and ReadID requires that images are captured by an NFC capable device.

Still, the Assure API integrates with all available options for each provider.

Why should I use the provider’s SDK to upload the images?

The providers’ SDKs help and guide the end-user with capturing the images. This improves the image quality and, by consequence, the quality of the final result.

Tip: For this reason, we highly encourage using the provider’s SDK for uploading the ID images.

Using direct upload

To directly upload images through the Assure API you must use the Set images service. Check the section below for details on how to use that service.

Using provider’s SDK

To use the provider’s SDK you can either use the eIDV alternative flow services (if you are in a web context) or you must integrate with the provider’s SDK. For more information on how to do this, see Integration details.

Image requirements

Regardless the images are uploaded directly to the provider or captured using their SDK, each provider has requirements and guidelines for the ID images:

Provider Supported image formats (for direct upload) Image size (for direct upload) Details regarding images
Onfido JPEG

PNG

Between 32KB and 10MB
  • Image quality too low for fraud assessment: After an Onfido verification, if the response contains “image_quality”: { “result”: “consider”} ‘, it means that the document can be processed, but the image quality is too low to make fraud assessment. However, it does not indicate any sign of potential fraudulence.
  • Onfido does not accept black and white documents. A warning (‘Rejected’) flag may be returned for ‘colour image’.
  • Sending ID images in PDF files is also supported by Onfido’s SDK’s, although with some disadvantages:
    • The verification response time is longer since sending images in pdf files always triggers a manual review by an Onfido expert.
    • Processes with images sent in PDF file always have a “consider” final status.
ElectronicID N/A N/A
  • ElectronicID does their own capture of the images, i.e. you cannot upload them directly to them.
  • During the ID verification process:
    • The document must be in a horizontal position, not turned.
    • The document data must be legible and the security elements must be visible (photo, chip …) and present good quality in the image.
    • The document must be fully visible in the image. It does not need to be framed, but it should be the only thing visible in the image, to ensure better results.
    • A meaningful error message specifying the required size is returned if the image does not meet the requirements.
Signicat Paper JPEG

PNG

  • Max 9MB per image. It is less if more than one image is sent.
  • Max request size, including images and JSON, is 10MB.
  • Max 32512*32512 pixels
    Recommended resolution: 300 dpi
If you use Signicat Paper as a Connect method these requirements apply.
ReadID N/A N/A
  • ReadID does their own capture of the images, i.e. you cannot upload them directly to them.
  • To learn more about the images you can obtain after ReadID has performed the verification, please see ReadID’s web site.

 

  Download full result (usage)

This topic describes how to use this service to retrieve all data from the provider (see also the reference descriptions and the Open API documentation)

This service allows retrieving all the data from a process as it was obtained from the provider. No cleanup or normalization is done for this data.
The service can only be performed on processes that have been completed.

The table below specifies the files that are expected as a result of calling this service. Note: The files may differ from provider to provider.
The “data files” contain the raw information about the verification/authentication process, as obtained directly from the providers.
The media files can be:

  • front: The image that was uploaded with the front of the identity document.
  • back: The image that was uploaded with the back of the identity document.
  • selfie: The image that was uploaded with the selfie of the end-user.
  • portrait: Image containing the photo in the identity document.
  • video: The video captured during the identification process.
Provider Data files Media files (0)
front back selfie portrait video
Onfido
  • document_verification.json
Contains all information about the document report.
  • front.jpeg/png/pdf
  • back.jpeg/png/pdf (2)
  • selfie.jpeg/png/pdf (1)
– (3)
  • video.mp4(4)
  • facial_similarity.json(1)
Contains all information about the facial similarity report.
ElectronicID
  • ocr.json
Contains all information about the OCR capture and automatic verification performed by EID.
  • front.jpeg
  • back.jpeg (2)
  • selfie.jpeg
  • portrait.jpeg
  • video.mp4(5)
  • manual_approval.json(3)
Contains all information about the manual verification performed by the support agent.
Signicat Paper
  • analysis_result.json
Contains all information about:

  • The text fields that were obtained from the document.
  • The data that was retrieved from MRZ reading the document.
  • The data for the verification of the fields and MRZ elements.
  • front.jpeg/png
  • back.jpeg/png(2)
– (6) – (3) – (7)
ReadID
  • readid_session.json
Contains all information about contents you can retrieve from Electronic Machine Readable Travel Documents (eMRTD):

  • nfcSesssion: The raw data of an eMRTD and the low-level details of the verification of an eMRTD.
  • documentContent: The interpreted data of an eMRTD, e.g. name, gender, date of birth etc. It also contains references to the face images stored in the document.
  • ocrSession: The MRZ that was OCR’ed and also a photo of the MRZ that was OCR’ed.
  • vizSession (Alpha): References to the photo of the vizual inspection zone of the eMRTD.
  • consolidatedIdentityData: This combines the best-interpreted data from multiple sources. Note: Please do not use this unless told otherwise. This part is extended by some versions of the ReadID server.
  • front.jpeg
– (8) – (6)
  • portrait.jpeg
– (7)
Connect
  • token_response.json
Contains the token response used to obtain the user information. In this token, you find the Access Token, an ID Token, and optionally a Refresh Token. – (9)
  • user_info.json/.txt
Contains information about the end-user, obtained from the ID method used in the request. The user information can be configured to be obtained either in JSON or JWT format. When the user information is in JWT format, the file has a “.txt” extension. If the information is in JSON format the file has a “.json” extension.

(0) The image file extensions vary depending on the provider and on the format that was used when the images were captured/uploaded.
(1) Only if processType is “documentSelfie” or “documentVideo”.
(2) Only if the ID document has a backside.
(3) This provider does not extract the photo from the ID.
(4) Only if processType is “documentVideo”.
(5) Only if processType is “unattended” or “attended”.
(6) This provider does not use selfies.
(7) This provider does not capture videos.
(8) This provider does not support documents with a backside.
(9) This provider does not use media files.

  Matching (usage)

This topic describes how you can use the following features to corroborate data from different sources:

Process/userData matching service

This section describes how to use the Perform matching service (see also the Open API documentation).

You can use this service to compare information in two data nodes of a dossier. These nodes can be:

Tip: Please contact Signicat if you need other matching services than the ones described in this section.

Notes:

  • All data nodes must exist inside the same dossier.
  • To have a finalResult, the process must have been “accepted”.

The fields that are matched from each data node are the following:

Field Matching algorithm
firstName String matching
lastName String matching
dateOfBirth Date matching

This table provides information on the algorithm used for matching each of these fields and also how the values are normalized before matching is performed:

Type of matching Normalization Rules for matching Examples
String matching
  • Values are normalized into uppercase.
  • Diacritics are removed.
String compare:

  • Exact match:

True if all characters match, false otherwise

  • Partial match:

True

    • If it is composed of multiple names and at least one is an exact match

or

    • The similarity ratio is above 90% of characters

False: None of the above

See example below
Date matching Values are normalized into “yyyyMMdd” format before matching is performed. String compare of normalized form.
Exact match if all numeric digits are equal.
Partial match for similarity ratio above 90%.
See example below.

Examples on string matching:

source target Exact match Partial match
Ana Ana true true
ana Ana true true
ANA Ana true true
Ana Maria Ana false true
Anita Ana false true
Maria Ana false false

Examples on date matching:

source target Exact match Partial match
1985-10-20 19851020 true true
1985-10-20 19851022 false true
1985-10-20 19990520 false false

Match the front and the back of a document

Note: It is only possible to use this feature if the following conditions apply:

For example, you can match the front and the back of a Dutch passport by checking the personal number (aka BSN) that exists both on the MRZ and on the opposite side of the document.

Here is an example of the personal number shown in the MRZ area on the front:

Here is an example of the same personal number shown on the back as a text field:

Here is how to use this feature:

In the generic flow

  1. Create a new process with “signicatpaper” as a provider.
  2. Upload the images directly to that process.
  3. Start verification.
  4. When the verification is finished, use the Get process service to obtain information about the result.
  5. In the paper specific fields of that result, check the mrzFeatureMatching element and look for the field that you know exists in both the MRZ and on the opposite side of the document. In the example above, it would be the personalIdentificationNumber field.
  6. Make sure the value of that field is FULL_MATCH. This means the value of the field in the MRZ is exactly the same as the value of the text field on the other side, i.e. it belongs to the same document.

In the alternative flow

  1. Start Capture Flow with “signicatpaper” as a provider.
  2. After the end-user has captured the images and the verification is finished, use the Get process service to obtain information about the result.
  3. The next steps are the same as step 5 and 6 above in the generic flow.

If you want to use this feature but you do not use Signicat Paper to perform the eIDV (i.e. you are using one of the third-party providers), you can still use this as follows:

  • In the generic flow, use the images from that provider’s process to create a new process using Signicat Paper and follow the steps indicated above.
  • In the alternative flow, use the two-provider feature of the Start Capture SDK Flow service.

Onfido data comparison

The Onfido provider allows asserting whether the data in the document is consistent with the data provided by the end-user. The following fields can be used for comparison:

  • firstName
  • lastName

The Onfido comparison system uses a Levenshtein-like fuzzy matching for these fields. The purpose of this inexact matching is to avoid unnecessary failures if the names are mathematically close enough.

This option is switched off by default and can be enabled if needed (please contact Signicat to do so). Note: If this option is enabled, you must always provide a firstName and lastName when creating a process. For example, you can ask the end-user to provide this data in a form. Otherwise, you will only obtain inconclusive results.

How to Use
  1. Ask Signicat to enable this option in your service.
  2. In the Create process request, make sure to always send the firstName and lastName parameters. See example below.
    curl --location --request POST 'https://preprod.signicat.com/assure/dossiers/<dossierId>/processes' \
    --header 'Authorization: Bearer <token>' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "provider": "onfido",
        "firstName": "John",
        "lastName": "Doe"
    }'​
  3. In the process result, you will see a dataComparison field that indicates if the data matched (“clear”) or not (“consider”).

  Redaction (usage)

This topic describes how to use the redaction feature to hide parts of the ID images. The feature is currently available only in Signicat Paper processes.

The Assure API’s redaction feature allows masking parts of the images of the ID document that is used during a verification process. This is useful, for example, to comply with privacy laws in some countries.

If you enable redaction in a process, the images you can get after the process is completed are returned redacted. This means the indicated fields will be covered with a black square.
Note: The images in the dossier remain untouched since redaction is applied only to the images in the process.

Request

Whenever you want to use redaction you must send the “redact” parameter in the request body and indicate which fields you want to be masked in the image. To know the full list of fields that can be redacted, see the OpenAPI documentation.

In the eIDV generic flow (Signicat Paper provider only)

If you integrate with the Assure API using the generic eIDV flow, you set the redaction field in the Create process request body.

Request example 1

This is a Create process request where the personalIdentificationNumber is redacted from the ID image (in this case, a Dutch passport):

{
  "provider": "signicatpaper",
  "documentType": "passport",
  "documentCountry": "NLD",
  "redact": ["personalIdentificationNumber"]
}
In the eIDV alternative flow

If you integrate with the Assure API using the alternative eIDV flow, you set the redaction field in the Start Capture Flow request body.

Request example 2: Start Capture Flow request where the gender and document number should be redacted from the ID image (in this case, a Dutch ID card):

{
    "providers": [
            {
                "provider": "signicatpaper",
                "redact": ["documentNumber", "gender"]
            }],
    "redirectUrl": "https://your-redirect-url.com"
}

Response

As usual, when the verification is completed you can use the Get process request to get information about the process and also the Get images service to retrieve the ID images used to perform the verification.

In the Get process response, you get redactionResult with information about the redaction. Example:

"redactionResult": {
    "fullRedaction": true,
    "partialRedaction": true
}

fullRedaction indicates if all fields were successfully redacted (“true”) or if at least one of them failed to be redacted (“false”). This usually happens if the indicated field was not found in the document.

partialRedaction indicates if at least one field was successfully redacted (“true”) or if none of the indicated fields was redacted (“false”).

Example of a Get process result with successful redaction:

{
    "status": "accepted",
    "processId": "e1cb7081-4187-413b-8677-7264de8eee18",
    "provider": "signicatpaper",
    "providerSpecific": {
        "verification": {
            "type": "MRZ_FEATURE_COMPARISON",
            "status": "true"
        },
        "features": {
            "firstName": "Willeke Liselotte",
            "lastName": "De Bruijn",
            "dateOfExpiry": "2024-03-09",
            "issuingAuthority": "Burg, van Stad en Dorp",
            "gender": "F",
            "documentNumber": "SPECI2014",
            "dateOfBirth": "1965-03-10",
            "personalIdentificationNumber": "999999990",
            "dateOfIssue": "2014-03-09"
        },
        "mrz": {
            "firstName": "Willeke Liselotte",
            "lastName": "De Bruijn",
            "dateOfExpiry": "2024-03-09",
            "nationality": "NLD",
            "gender": "F",
            "documentType": "identityCard",
            "issuingCountry": "NLD",
            "documentNumber": "SPECI2014",
            "dateOfBirth": "1965-03-10",
            "personalIdentificationNumber": "999999990"
        },
        "mrzChecksum": {
            "dateOfExpiry": "VALID",
            "documentNumber": "VALID",
            "dateOfBirth": "VALID",
            "personalIdentificationNumber": "VALID"
        },
        "mrzVerification": {
            "dateOfExpiry": "VALID",
            "documentType": "VALID",
            "issuingCountry": "VALID",
            "dateOfBirth": "VALID"
        },
        "mrzFeatureMatching": {
            "dateOfExpiry": "FULL_MATCH",
            "lastName": "FULL_MATCH",
            "issuingAuthority": "FOUND",
            "firstName": "FULL_MATCH",
            "documentNumber": "FULL_MATCH",
            "drivingPermits": "MISSING",
            "dateOfBirth": "FULL_MATCH",
            "personalIdentificationNumber": "FULL_MATCH",
            "dateOfIssue": "VALID"
        },
        "redactionResult": {
            "isPartialRedaction": "true",
            "isFullRedaction": "true"
        }
    },
    "finalResult": {
        "firstName": "Willeke Liselotte",
        "lastName": "De Bruijn",
        "dateOfExpiry": "2024-03-09",
        "gender": "F",
        "nationality": "NLD",
        "documentType": "identityCard",
        "documentNumber": "SPECI2014",
        "issuingCountry": "NLD",
        "dateOfBirth": "1965-03-10",
        "personalIdentificationNumber": "999999990"
    },
    "createdAt": "2020-07-13T16:20:58Z",
    "updatedAt": "2020-07-13T16:21:08Z"
}

After the redaction is successful (isFullRedaction=true), you can use the Get images service to retrieve the redacted images.

 

Request example 1: Images where personalIdentificationNumber is redacted in a Dutch passport

Front:

Back:

 

Request example 2: Images where gender and documentNumber are redacted in a Dutch passport

Front:

Back:

  Callbacks (usage)

This topic describes how to receive callback notifications from the Assure API.

You can request to be notified from the Assure API when a process is completed. To do that, you must provide your server’s URL (notificationUrl) and an authorizationHeader (if needed) in the Create process request body or in the Start Capture Flow request body.

Important: To receive these notifications, Signicat must whitelist your server’s URL. To do this, please contact Signicat Support. If you are just testing, consider using https://labs.signicat.com/proxy instead of going through the whitelisting process.

When the process verification is done, the Assure API will POST a request to your notificationUrl with the process ID, its status and the ID of the dossier it belongs to. Here is an example:

{
    "dossierId":"54a1ad5f-74dd-47ba-b992-1cb2b4636341",
    "processId":"3065980b-f26b-4ec2-8987-7833b7781dae",
    "status":"accepted"
}

Field descriptions:

Field name Description Field type
dossierId The unique ID of the dossier to which the process belongs to. string
processId The unique ID of the process. string
status The final status of the process. Enum

After getting this notification, your notificationUrl must respond with a “200 OK” as soon as possible(and no longer than three seconds). For that reason it is important that the endpoint receiving the notification does not perform lengthy processing that can delay its response time.

Note: Callback notifications may or may not be re-sent if they fail – that will depend on wether the provider you are using to perform the verification tries to send the notification again or not (more info will come on this).

Finally, at this point you can get the updated process information by using the Get process service with the dossierId and processId from the callback.

  Normalization values (usage)

This topic describes how Assure API normalizes values.

All elements in responses you get from the Assure API are normalized, i.e., they will all follow the same format, depending on the type of data they represent.

Field Format
Dates (e.g. dateOfBirth, dateOfExpiry, etc) YYYY-MM-dd
createdAt

updatedAt

ISO 8601 UTC date: yyyy-MM-dd’T’HH:mm:ss.SSSZ
issuingCountry

nationality

ISO 3166 Alpha 3 country codes.
E.g. “PRT”, “NOR”.

  Enums (usage)

This topic provides lists of enums the Assure API uses in requests/responses.

Provider

Name Value
Onfido onfido
Electronic-Id eid
ReadID readid
Signicat Paper signicatpaper
Connect connect:<idmethod>

Replace <idmethod> with the id method name from Signicat

Document type

To check the available values please use the Get document types service.

Process type

Value Provider Description
document onfido The verification is only done on the provided identity document.
documentSelfie onfido The verification is done on the identity document and the photo of the end-user. The photo allows assessing whether the holder of the identity document is the same person as the one on the document (facial similarity). The photo must be taken at the time of the request.
documentVideo onfido The verification is done on the identity document and also a video-call while the end-user does some requested actions (e.g. “Look over your left shoulder”). The video allows assessing whether the holder of the identity document is the same person as the one on the video-call (facial similarity). It also detects liveness information.
attended eid This requires that the verification is performed online by a support agent. The agent requests the end-user to show their ID and will immediately accept/reject the request.
unattended eid This is the default value. It means there is no need for a support agent to be online, i.e. the verification is done as usual (the ID images are uploaded, the request for the verification to start is sent) but the support agent will review the process offline (and the result will be returned asynchronously).
substantial eid This is the same as unattended but no support agent will review the request, i.e. only OCR of the document and automatic facial comparison and liveness detection are done. The Get process response will not contain the manualApproval element.

Process status

Status type

Status value Description
Not final pending The process is created but the verification has not yet started.
processing The verification of the data in the process has started but is not yet finished.
Final Completed accepted The verification is finished and accepted (i.e, the data is valid).
rejected The verification is finished and rejected (i.e, the data is not valid).
inconclusive The verification is finished but inconclusive (i.e., the data might not be valid).
Not completed canceled The verification was not finished because it was canceled by the end-user.

For details on how the status is mapped for each provider, see Get process responses.

Depiction type

Value Description Format
selfie Selfie image of the end-user. Images must be in jpg/png format and must be sent using dataURL scheme. You can use websites such as Base64 to convert the images into dataURL.
front Front of the document.
back Back of the document.
portrait Portrait image retrieved from the ID document (not returned by Onfido)

Language

Value Description
da Danish
de German
en English
es Spanish
fi Finnish
pt Portuguese
nb Norwegian
sv Swedish

Gender

Value Description
F female
M male

Similarity score

This value indicates the probability of the person in the selfie being the same as the person on the document image:

Value Description
verylow Very unlikely.
low Probably not.
medium Probably.
high Very likely.

Onfido Result value

Value Description
clear If all underlying verifications pass, the overall result will be clear.
consider If the report has returned information that needs to be evaluated, the overall result will be considered.
unidentified This is returned if the applicant fails an identity check.

Onfido Sub-Result value

Value Description
clear If all underlying verifications pass, the overall sub result will be clear.
rejected If the report has returned information where the check cannot be processed any further (poor quality image or an unsupported document).
suspected If the document that is analysed is suspected to be fraudulent.
consider If any other underlying verifications fail but they don’t necessarily point to a fraudulent document (such as the name provided by the applicant doesn’t match the one on the document).

ReadID Verification Status Verdict value

Value Description
NOT_PRESENT Not present
PRESENT_FAILED Present and verification not OK. Check ReasonCode for details.
PRESENT_NOT_CHECKED Present, but not checked.
PRESENT_SUCCEEDED Present and verification OK.
UNKNOWN  Unknown

ReadID Access Control Verdict value

Value Description
UNKNOWN Unknown
NOT_PRESENT The document does not have access control.
PRESENT_NOT_PERFORMED Access control present but not performed/skipped.
PRESENT_FAILED The document supports access control but performing access control failed.
PRESENT_SUCCEEDED The document supports access control and the client successfully authorized.

ReadID Verification Status Reason Code value

Value Description
ALL_HASHES_MATCH All hashes match
CERTIFICATE_EXPIRED Certificate expired
COULD_NOT_BUILD_CHAIN_FAILURE Could not build a chain to a trust anchor.
FOUND_A_CHAIN_SUCCEEDED Found a chain to a trust anchor.
HASH_MISMATCH_FAILURE Hash mismatch.
NO_CSCA_TRUST_ANCHORS_FOUND_FAILURE No CSCA trust anchors found.
NO_VERIFIER No verifier installed.
NON_MATCH_ALERT Non-match alert.
NOT_SUPPORTED Not supported.
PRESENCE_DETECTED Verification information is present but not verified.
READ_ERROR_CONFIGURATION_FAILURE A read error while reading verification configuration from the document.
READ_ERROR_SOD_FAILURE A read error occurred while reading the Security Object.
SIGNATURE_CHECKED Signature checked.
SIGNATURE_FAILURE Signature check failed.
STORED_HASH_NOT_FOUND_FAILURE Stored hash not found.
SUCCEEDED Verification succeeded.
UNEXPECTED_EXCEPTION_FAILURE An unexpected exception occurred while verifying.
UNKNOWN Unknown.
UNSUPPORTED_DIGEST_ALGORITHM_FAILURE The verification requires a digest algorithm not supported by the verifier.
UNSUPPORTED_KEY_TYPE_FAILURE The verification info in the document requires a key type that is not supported by the client.
UNSUPPORTED_SIGNATURE_ALGORITHM_FAILURE The verification requires a signature algorithm not supported by the verifier READ_ERROR_CONFIGURATION_FAILURE

ReadID Access Control Reason Code value

Value Description
UNKNOWN Unknown reason.
SUCCEEDED The document has access control and the client successfully authenticated.
PRESENCE_DETECTED The document has access control but the client did not authenticate yet.
NOT_SUPPORTED The document does not support access control.
UNEXPECTED_EXCEPTION_FAILURE An unexpected exception occurred while performing the access control.
UNSUPPORTED_KEY_TYPE_FAILURE The key type required by the document’s access control feature is not supported.
READ_ERROR_CONFIG_FAILURE Read error while trying to read the access control configuration.
USING_ALTERNATIVE_CONTROL Using an alternative access control method, e.g. PACE instead of BAC.
INSUFFICIENT_CREDENTIALS Insufficient credentials to access the document.

Paper Feature Matching value

Value Description
FULL_MATCH For both the <date_field> and <text_field>The value in “fields” matches completely the value in “mrz”.
LEVENSHTEIN1

LEVENSHTEIN2

LEVENSHTEIN3

LEVENSHTEIN4

For both the <date_field> and <text_field>

The value in “fields” differs from the value in the MRZ from 1 to 4 characters

VALID For <date_fields> only

The difference is greater than LEVENSHTEIN4 but the value in “field” is still a valid date.

PARSED For <date_fields> only.

The difference is greater than LEVENSHTEIN4 but the value in “field” is not a valid date.

FOUND <text_field>

The value was found in “field” but it differs more than 5 degrees from the value in “mrz”.

MISSING The value was not found in “fields”.

Paper Checksum value

Value Description
VALID The value in “field” is a valid date.
PARSED The value in “field” is not a valid date.
FOUND The value was found in “field” but it cannot be parsed as a date (meaning it will also not be a valid date).
MISSING The value was not found in “fields”.

Paper Types of Verification value

Verification type Documents that can
MRZ_FEATURE_COMPARISON Retrieved the information from both the MRZ and the text fields from the document and will analyse and match their values.
MRZ_ONLY Retrieved and analysed only the information from the MRZ area (used with “passport” documents only).
FEATURES_ONLY Retrieved and analysed only the information from the text fields (used with documents that do not have MRZ and only have text fields).

Frequently Asked Questions (FAQ)

Does the Assure API assume that scanned images of an identity document already exist?

No. All providers supply a way to help the end-user capture and upload the images themselves (see Uploading ID images).

Is the end-user required to capture and upload the images during the process?

No, but that will depend on the provider. Most providers require doing that (and that is the approach we highly encourage).
However, Onfido provides an alternative for uploading the images via API. In this case, the end-user may use images he already has of the identity document.

Am I required to integrate with the provider’s SDK? 

No. You can either upload the images directly using the Assure API (check the answer on the previous question) or, if you’re integrating in a web environment, you can also use the Assure API’s Web SDK Flow service.

If need an answer you can’t find here, please contact us.