The Assure API is a RESTful service that can be used to scan and verify identity documents using one more of the supported identity document verification providers and screening end-users against PEP/Sanctions/OFAC lists using the supported lookup service providers.
The purpose of the Assure API is to provide a unique and simple way of integration for those services, that works in both browser and native mobile contexts and supports asynchronous operations.

Supported providers

The tables below list all the third party providers currently integrated in the Assure API.

For details about using each of the providers, please refer to the Providers Details section of the Integration Details documentation.

Identity document verification providers

List of third-party providers to perform identity document verification:

Third-party provider
Onfido
Electronic Identification (eID)
ReadID

Identity lookup/matching providers

List of third-party providers to look up/match a person’s identity against PEP/Sanctions/OFAC lists.

Third party provider
Trapets

Privacy and Data

The Assure API conforms to the Signicat Assure Privacy Statement.

Accessing the API

In order to consume Signicat REST services, a caller must first acquire an access token using the OpenID Connect (OIDC) protocol.

For more information, please refer to the documentation on Accessing Signicat REST Services.

Key Concepts

End User

The person whose identity will be verified.

Service Provider

The entity who will integrate with the Assure API.

Verification request 

The action of requesting one of the third-party providers for verifying information about the end user.

Result

Information about the outcome of the verification request.
This result is normalized by the Assure API and is part of a process. For more info about the result please refer to this section.

Process

resource of the Assure API.
A container for all the information associated to a verification request. Must be created by the service provider using the Assure API.

Dossier

resource of the Assure API.
A container for all the information regarding all processes. Must be created by the service provider using the Assure API.

Using the Assure API

The next sections will provide an overview of the basic flows for using the Assure API.

If you are looking for more detailed information, please go to the Integration Details documentation. There you will find all of the possible scenarios as well all the details you need to know for integrating with the Assure API. You will also find integration guides for some of the most common use cases for using the Assure API.

Identity document verification

The most basic flow for performing an identity document verification is as follows:

Note: Use a server to communicate with the Assure API.
Your mobile/web app must always talk to your own server and never directly with the Assure API.

Step 1: Initial Setup

The first thing you have to do is set up the necessary resources, so you must create a Dossier and then create a Process inside that dossier. The dossier is where all the information about the end user will be kept. The process is what will allow 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 will be kept.

Step 2: Upload ID images

Now that you have a dossier and a process, you need to provide images of the identity document and of the end user in order to be able to proceed with the verification.

This can be done either by using the provider’s SDK to capture and upload the images or by uploading the images directly using the Assure API.

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

The providers’ SDKs help and guide the end user throughout the process of capturing the images.This improves the quality of those images and, by consequence, the quality of the final result.

For this reason, we highly encourage this approach for uploading the ID images.

The table below summarizes which approaches are supported by each identity document verification provider:

Direct upload using Assure API Use provider’s SDK to capture and upload images
Web SDK(1) iOS SDK Android SDK
Onfido
Electronic ID
ReadID

(1)Also available through the Assure API. Check the “Alternate Flow Using the Assure API’s Embedded Web SDK Service” section below.

Why aren’t all options available for all providers?

Each provider has specific requirements on the images on how they are captured. This means that some providers will accept methods that others will not. For example, Electronic ID requires that a video is recorded during the capturing of the images, and ReadID requires that images are captured by a NFC capable device.

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

Step 3: Request verification 

Now that all the necessary information has been provided, you can request for the verification to be performed.

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.

Because this response is obtained asynchronously, you may request to be notified when the result is available (note that this must be defined when creating the process in step 1).
Still, at any time you can see all the information available about an identity document verification by checking the information in the process.

Am I required to register for callback notifications in order to get the final result?

No. The final result information will always be kept by inside the process regardless you asked to be notified or not. The callback notification will only inform you that the verification is finished.

Alternate Flow Using the Assure API’s Embedded Web SDK Service

If you are integrating with the Assure API in a Web environment you can avoid having to integrate with the provider’s Web SDK to capture and upload the ID images – you can use the Web SDK Flow, a service provided by the Assure API.

The Web SDK Flow service provides an extra layer of abstraction, making it quicker and easier to integrate with the Assure API in a Web environment:

Just as in the basic flow, you will first need to create a dossier. The main difference is that now you don’t need to create a process, integrate with the provider’s SDK to capture and upload the images nor request to start the verification – you will just need to Start Web SDK Flow.

For more information on this alternative flow, please check the Integration Details documentation.

Identity lookup/matching

There are two ways to perform a lookup/matching of a person’s identity in PEP/Sanctions/OFAC lists:

Option 1: Providing information about the identity

If you need to perform a lookup/matching of any identity you can just use the general lookup/matching service of the Assure API.

In this case you must provide information about the identity, such as their name, date of birth or ID number.

Option 2: Using an approved identity

If you have already performed an identity document verification process over an end user and their identity has been approved (i.e., the process’s final status is “accepted“), you can immediately request a lookup/matching on that process.

The identity information in the process will be sent to the lookup/matching provider and the process will be updated the the lookup/matching results. To see the results you just need to check the information in the process. And, because this verification is synchronous, you don’t need to wait for any notification.

 

For detailed information about implementing each of these options please refer to the Integration details documentation.

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.

Swagger documentation

The Assure API Swagger Documentation contains detailed reference documentation on the API and examples.

You can also use it for testing the API. To do that, make sure to choose the correct server environment before requesting the access token:

Use your client_id and client_secret (check the Accessing the API section if you need more information) and make sure the “client.assure.api” scope is selected, then click “Authorize”:

API reference

List of Endpoints

Resource Endpoint
DOSSIERS Create Dossier
DOSSIERS Get Dossier
DOSSIERS Delete Dossier
DOSSIERS Get All Dossier
DOSSIERS Start Web SDK flow
PROCESSES Create Process
PROCESSES Get Process
PROCESSES Delete Process
PROCESSES Set Image
PROCESSES Get Image
PROCESSES Start Verification
PROCESSES Get Video
PROCESSES Get Full Result
PROCESSES End-user Lookup
ASSURE Get Document types
ASSURE Get Manual Approval URL
ASSURE Identity Lookup

DOSSIERS

A dossier will contain all information regarding an end-user and the identity verification processes performed for that user.

    Create Dossier

Swagger 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 be from different providers.
Usage is required? Yes.

    Get Dossier

Swagger Dossiers.getDossier
Usage details You can get a dossier to see a summarized view of all the processes in it.
Usage is required? No.

    Delete dossier

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

    Get all dossiers

Swagger Dossiers.getDossiers
Usage details You can use this service to check all dossiers that you have created so far and have not yet been deleted.
Usage is required? No.

    Start Web SDK Flow

Swagger Dossiers.createArtifact
Usage details There are many important details about using this service. Please check the Start Web SDK Flow Service Details section for more details.
Usage is required? Not for the basic flow.

Yes for the alternate flow.

PROCESSES

    Create process

Swagger Processes.createProcess
Usage details When you create a process you must decide if you will later want to receive a notification when the verification is complete. In that case, you must set the “notificationUrl” and the “authorizationHeader” in the request body. Please check the Callbacks section for more details.

After you create a process you can no longer change any information in it (only upload images that will be associated to it).

Usage is required? Yes for the basic flow.

Not if you’re using the alternate flow using the Web SDK Flow (that service already calls this endpoint for you).

    Get process

Swagger Processes.getProcess
Usage details This service does more that just getting the basic information about a process (e.g. provider, updatedAt, status) – it must be used in order to get information about the verification result.

Please check the “Get Process Service Details” for detailed information on all the data that will exist in this service’s response.

Usage is required? Yes.

    Delete process

Swagger 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 the Delete Dossier if you are finished with that end user’s identity verification).
Usage is required? It is highly recommended.

    Set image

Swagger Processes.setImages
Usage details Can only be used with the Onfido provider (all other providers require that you use their SDK to capture and upload the images).

Should not be used after the verification has been started.

Usage is required? Yes for the Onfido provider and only if you will use the Assure API to upload the images (if you use their SDK you do not need to call this endpoint).

    Get image

Swagger Processes.getImage
Usage details Will only provide results after the images have been uploaded to the providers (either using their SDK or the Assure API Set Image endpoint).
Usage is required? No.

    Start verification

Swagger Processes.verifyProcess
Usage details This service can only be called after the ID images have been uploaded to the provider.

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 (ex: upload new images) you must create a new process and start over.

Usage is required? Yes. Without calling this endpoint the verification will not start with most providers.

Exceptions are:

  • If you’re using Read ID (Read ID automatically does the verification as soon as the data is read from the document)
  • If you’re using the Web SDK Flow (that service already calls this endpoint for you)
  • If you’re performing an Electronic ID “attended” process (no need to start the verification since it will be done by the online agent)

    Get video

Swagger Processes.getVideo
Usage details Video will only be available for some providers (currently only Electronic ID) and after the images have been uploaded to the provider.
Usage is required? No.

    Get full result

Swagger Processes.getZipFile
Usage details Can only be called if the Process’ status is “accepted”.

As already mentioned, after a verification is complete you should save all of its information (using this service) and then delete the process (and the dossier).

Usage is required? No.

    End-user lookup

Swagger Processes.getLookup
Usage details Can only be called if the Process’ status is “accepted”.

For more details about this service please check the “Lookup/Matching Services Details” section.

Usage is required? If you will be doing Identity Lookup/Matching you will have to use either this service or the Look Up Identity service.

ASSURE

    Get document types

Swagger Assure.getDocumentTypes
Usage details For the Electronic ID provider, one more field (than the ones presented in the swagger docs) will be returned in the response body: “id”. This information is required by Electronic ID when you are using their SDK.
Usage is required? Yes in the basic flow, but only for Electronic ID. In this case, you will have to check this service at least once, so you know their ID for each document.

No for the alternate flow. The Web SDK Flow service will do this work for you.

    Get manual approval URL

Swagger Assure.getManualApprovalURL
Usage details If you are using the Electronic ID provider you will need to call this endpoint at least once so you know the URL the agents must access in order to perform the manual approval of the verification.
Usage is required? Yes for Electronic ID.

    Identity Lookup

Swagger Assure.lookup
Usage details For more details about this service, please check the “Lookup/Matching Services Details” section.
Usage is required? If you will be doing Identity Lookup/Matching you will have to use either this service or the End-user Lookup service.

API reference details

Get process – service details

This is probably the service you will use the most to obtain information. The response will contain lots of different information, depending on the provider you are using and on the part of the flow you are calling this service at (ex: after the process was created, after the images were uploaded, after a verification is finished or even after a lookup is requested).

Response Contents and Structure

Because the Assure API supports asynchronous behavior, the data on a process will be updated as the results sent by the providers are obtained.
This section provides information about that data, what changes will occur and when.

The structure of the JSON obtained in the response of the Get Process service changes overtime and is divided into 3 main areas:

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

Lookup results

The information in the process will also change if the Processes.Lookup End-user service to perform an identity lookup/matching.

Please check the Start Web SDK Flow service details section for more information on this.

The next sections will discuss the Get Process structure only during an identity document verification flow.

1. Process information

The elements in this area contain general information about the process (ex: its internal unique id, the identity verification provider that will/was used for performing the verification, the dates at which the process was created and last updated at).

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

Example of Get Process response 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 to be used to perform 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 identity verification process enum : Process status
2. Provider-specific information

The elements in this area will depend on the information shared by the providers about the verification process.

Also, while some providers will start sharing information as soon as the identity document is uploaded, other will only share information when the verification is complete.

The provider-specific information 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, as according to the table below:

Provider JSON elements in Get Process response
Onfido
  • facialSimilarity
  • documentVerification

(See Onfido results for more details)

Electronic ID
  • ocr
  • manualApproval

(See Electronic ID results for more details)

ReadID
  • session

(See ReadID results for more details)

Trapets
  • pep
  • sanctions
  • ofac

(see Trapets results for more details)

Onfido Results

Accepted Process

Onfido JSON for Accepted process:

Example of Get Process response of an Accepted Onfido process

{
    "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"
    },
    "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"
    }
}
Element Name Field Name Description Field type
processId,
provider,
createdAt,
updatedAt,
status
Check the Process information section.
finalResult Check the Final result section
facialSimilarity

Contains information about facial similarity report.

result The result field indicates the overall result of a report. String :
Onfido Result Enum
imageIntegrity Asserts whether the quality of the uploaded files and the content contained within them were sufficient to perform 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 make an assessment of the nature of the photo or video. If tampering (such as photos of printed photos or photos of digital screens) is detected the applicant will be rejected regardless of the Facial Similarity score. enum: Similarity Score Enum
documentVerification

Contains information about the document report.

lastName This property provided the last names on the document. String
dateOfExpiry Document’s date of expiry Date : Normalized values
subResult The sub_result field indicates a more detailed result for Document reports. enum : Onfido Sub-Result Enum
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 applicant’s gender. enum : Gender Enum
documentType Document type verification. enum : Document Type Enum
documentNumber Document identification number.
dateOfBirth Applicant’s date of birth Date : Normalized values
ageValidation Asserts whether the age calculated from the document’s date of birth data point is greater than or equal to the minimum accepted age set at account level. The standard threshold is 16 years old but you can request for this to be changed (you must contact Signicat).

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 name 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 Applicant’s nationality. String : Normalized values
issuingCountry The issuing country of the document. String : Normalized values
dataComparison Note: Data comparison is not enabled by default. If you want to enable data comparison, please contact Signicat.

Asserts whether data on the document is consistent with data provided when creating an applicant.

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 has been 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 JSON for Rejected process:

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

As you can see, a “rejected” result will not contain a finalResult element. Also, the Onfido-specific elements will be reduced since there will probably be little data obtained from the document.

Please check the Onfido Accepted section for details on each element.

Inconclusive Process

Onfido JSON for Inconclusive process:

 {
    "provider": "onfido",
    "status": "inconclusive",
    "processId": "85210241-4e70-4451-8ea3-7cd3c4d8843a",
    "createdAt": "2019-09-23T10:05:53Z",
    "updatedAt": "2019-09-23T10:09:49Z",
    "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 will also not contain a finalResult element, but it will contain some data obtained from the document.

Please check the Onfido Accepted section for details on each element.

Electronic ID Results

Accepted Process

Electronic ID JSON for Accepted process:

 {
    "provider": "eid",
    "status": "accepted",
    "processId": "d4233fba-9b7a-4400-9022-cd16b108ccc0",
    "createdAt": "2019-09-19T15:37:57Z",
    "updatedAt": "2019-09-19T15:40:09Z",
    "ocr": {
        "lastName": "SANTOS HENDES",
        "dateOfExpiry": "2020-02-08",
        "healthNumber": "366355550",
        "gender": "F",
        "documentType": "identityCard",
        "socialSecurityNumber": "11876398740",
        "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"
    }
}
Element Name Field Name Description Field type
processId,
provider,
createdAt,
updatedAt,
status
Check the Process information section.
finalResult Check Final result section.
ocr

(Contains information obtained from the document by OCR analysis)

lastName Last names. String
dateOfExpiry Document expiration date Date: Normalized values
healthNumber Health Number String
gender Gender enum: Gender Enum
documentType Type of document that was provided (ex: a Norwegian passport) enum: Document Type Enum
socialSecurityNumber Social security number String
documentNumber Document number String
taxNumber Tax number String
dateOfBirth Date of birth Date: Normalized values
similarityScore Similarity score between the photo in the document and selfie image Enum: Similarity Score Enum
firstName First names 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 an 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 Enum
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

Electronic ID JSON for Rejected process:

 {
    "provider": "eid",
    "status": "rejected",
    "processId": "52b7f782-ce2b-4436-94b9-0d264e327dd8",
    "createdAt": "2019-09-19T15:42:20Z",
    "updatedAt": "2019-09-19T15:44:56Z",
    "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

For Electronic ID, the “Inconclusive” status cannot be obtained.

ReadID Results

Accepted Process

ReadID JSON for Accepted process:

{
    "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 MIGUEL",
        "lastName": "PEREIRA MENDES",
        "gender": "M",
        "nationality": "PRT",
        "dateOfBirth": "1988-05-23",
        "documentNumber": "CB011930",
        "dateOfExpiry": "2024-08-26",
        "issuingCountry": "PRT"
    },
    "session": {
        "documentType": "passport",
        "firstName": "TIAGO MIGUEL",
        "lastName": "FERREIRA MENDES",
        "gender": "M",
        "nationality": "PRT",
        "dateOfBirth": "1988-05-23",
        "documentNumber": "CB022930",
        "dateOfExpiry": "2024-08-26",
        "issuingCountry": "PRT",
        "documentCode": "P",
        "mrzString": "P<PRTFERREIRA<MENDES<<TIAGO<MIGUEL<<<<<<<<<<<CB011930<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"
    }
}
Element Name Field Name Description Field type
processId,
provider,
createdAt,
updatedAt,
status
Check the Process information section.
finalResult Check Final result section.
session

 

 

 

 

 

 

 

 

 

 

 

documentType The type of document provided. enum: Document Type Enum
firstName First name(s). String
lastName Surname(s) String
gender Gender enum: Gender Enum
nationality The nationality of the document holder. Note that this is not necessarily the same as the country that issued the document. String: Normalized values
dateOfBirth Date of birth. Date: Normalized values
documentNumber The document’s number String
dateOfExpiry The document’s expiration date Date: Normalized values
issuingCountry The document’s issuing country String
documentCode Document code indicating the type of document. ‘P’ for a passport, ‘I’ for an Identity Document. String
mrzString The MRZ string String
sessionDocumentType “EU_EDL” (european drivers licence) or “ICAO_MRTD” (machine-readable travel document). String
BAC Active authentication verdict enum: ReadID Enum
BACReason Enum indicating the reason for the Active Authentication verification verdict. enum: ReadID Enum
EACTA Active authentication verdict enum: ReadID Enum
PACE Active authentication verdict enum: ReadID Enum
PACEReason Enum indicating the reason for the Active Authentication verification verdict. enum: ReadID Enum
CS Country Signer verdict. enum: ReadID Enum
CSReason Enum indicating the reason for the verification status of the Country Signer. enum: ReadID Enum
DS Document Signer verdict enum: ReadID Enum
DSReason Enum indicating the reason for the verification status of the Document Signer enum: ReadID Enum
EACCA EAC-CA verdict enum: ReadID Enum
EACCAReason Enum indicating the reason for the verification status of the EAC-CA enum: ReadID Enum
HT Hashtable verification verdict enum: ReadID Enum
HTReason Enum indicating the reason for the verification status of the table of hashes over the data groups enum: ReadID Enum

Rejected Process

ReadID JSON for Rejected process:

{
    "provider": "readid",
    "status": "rejected",
    "processId": "6eed6478-9035-4b7a-a48a-cc24040c442d",
    "createdAt": "2019-10-08T13:16:31Z",
    "updatedAt": "2019-10-08T13:17:00Z",
    "session": {
        "documentType": "passport",
        "firstName": "TIAGO MIGUEL",
        "lastName": "FERREIRA MENDES",
        "gender": "M",
        "nationality": "PRT",
        "dateOfBirth": "1988-05-23",
        "documentNumber": "V122659",
        "dateOfExpiry": "2013-06-08",
        "issuingCountry": "PRT",
        "documentCode": "P",
        "mrzString": "P<PRTFERREIRA<MENDES<<TIAGO<MIGUEL<<<<<<<<<<<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

For ReadID, the “Inconclusive” status cannot be obtained.

Trapets results

The Trapets provider is used for performing lookup/matching of an identity. As you know, there are 2 ways of requesting that service and one of them is by calling the Processes.End-user Lookup service after an identity document verification has been “approved” (please check the “Lookup/Matching – Services Details” section for details on using the lookup/matching services).

Here is an example of a Get Process result of an identity verification process that was performed using Electronic ID and was approved and after which was requested the identity lookup/matching in PEP, sanctions and OFAC lists.

 {
    "provider": "eid",
    "status": "accepted",
    "processId": "ac427947-b2e6-4a47-b012-ef90a779bb2e",
    "createdAt": "2019-04-08T16:21:47Z",
    "updatedAt": "2019-04-08T16:21:47Z",
    "ocr": {
        "lastName": "NILSSON",
        "dateOfExpiry": "2020-10-15",
        "gender": "M",
        "documentType": "passport",
        "documentNumber": "N909050",
        "dateOfBirth": "1965-07-13",
        "similarityScore": "high",
        "firstName": "LUKE",
        "nationality": "PRT",
        "issuingCountry": "PRT"
    },
    "manualApproval": {
        "duration": "68",
        "firstName": "LUKE",
        "lastName": "NILSSON",
        "dateOfExpiry": "2020-10-15",
        "gender": "M",
        "nationality": "PRT",
        "documentNumber": "N909050",
        "issuingCountry": "PRT",
        "rAuthorityId": "11a56f16-6f19-4282-8f2d-3749b86471d5",
        "dateOfBirth": "1965-07-13"
    },
    "finalResult": {
        "firstName": "LUKE",
        "lastName": "NILSSON",
        "dateOfExpiry": "2020-10-15",
        "gender": "M",
        "nationality": "PRT",
        "documentType": "passport",
        "documentNumber": "N909050",
        "issuingCountry": "PRT",
        "dateOfBirth": "1965-07-13",
        "similarityScore": "high"
    },
    "pep": {
        "name": "Luke",
        "hits": [{
            "name": "Luke Nielson",
            "hitRating": 4,
            "dateOfBirth": "1976-07-10",
            "idNumber": "SE197607101347",
            "sourceName": "PEP_Edge"
        }]
    },
    "sanction": {
        "name": "Luke",
        "hits": [{
            "name": "Luke Nielson",
            "hitRating": 2,
            "dateOfBirth": "1976-05-11",
            "idNumber": "SE197607101347",
            "sourceName": "US_EU_S_List"
        }]
    },
    "ofac": {
        "name": "Luke",
        "hits": [{
            "name": "Luke Nielson",
            "hitRating": 1,
            "dateOfBirth": "1976-07-10",
            "idNumber": "SE197607101347",
            "sourceName": "OFAC_REGISTRY"
        }]
    }
}

The Assure API will use the information from the “finalResult” to send as parameters to Trapets. It will then normalize and store the results inside a “pep”, “sanctions” or “ofac” element inside the process.

For details about the fields inside those elements, please check the Lookup/Matching – Services Details.

3. Normalized final result

After a verification is finished and the result is “accepted“, the Assure API will generate a finalResult element and add it to the Get Process response.

This element will contain a uniform summary of the information collected from the provider, meaning that the finalResult element will always contain the same elements (e.g. firstNamelastNamedateOfBirth), regardless the provider that was used for performing the verification (possible exception for some elements the provider may not have returned information about).

Note: The finalResult will only exist if the verification is completed and the final status of the process is “accepted” (see the process status section for more information).

Example of finalResult element in 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"
  }
Field Description Field type
firstName The applicant’s given name. String
lastName The applicant’s surname. String
dateOfExpiry The document’s date of expiry Date: Normalized values
dateOfBirth The applicant’s date of birth. Date: Normalized values
gender The applicant’s gender. enum: Gender Enum
nationality The applicant’s nationality. String: Normalized values
documentType The document’s type. enum: Document Type Enum
documentNumber The document’s number. String
issuingCountry The document’s issuing country. String: Normalized values
similarityScore The biometrics face similarity level. enum: Similarity Score Enum

The information in the finalResult is what will be used by the Assure API to perform lookup/matching of this identity if you decide to execute the End-User Lookup service in this process.

Start web SDK flow – service details

This service provides a way of using the providers’ Web SDKs without having to integrate with them. Because ReadID does not currently provide a Web SDK, this service is only available for usage with Onfido and Electronic ID.

When you use this service you will have to provide some of the same information as if you were creating a process (providernotificationURLauthorizationHeaderprocessType) but you will also have to provide details that are specific to this service:

The URL that will be returned in the response is where you should redirect the end-user to.

By calling this service:

The redirectURL to where the end-user will be redirected at the end of the flow will be added with information about the processId and the flow’s status.

Example of redirectURL after the Web SDK Flow is finished:

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

You should afterwards use those dossierId and processId to Get Process and obtain information about the result of the verification.

As in a basic flow, you will be able to receive a callback notification when the process verification is finished by the provider.

Lookup/Matching – service details

The lookup/matching services of the Assure API allow to perform seek information from sanctions, PEP and OFAC lists about a given identity. Currently, the only available provider to perform this service is Trapets.

Assure API offers two services to do identity lookup/matching – one allows you to use the information obtained about an end-user resulting from an identity verification process (Processes.Lookup End-user) while the other will allow you to input the information about the identity yourself (Assure.Lookup Identity).

Option 1: Perform Lookup/matching of a verified identity

To use this option you must first perform an identity document verification and obtain an “approved” result.

After that you can then call the Processes.Lookup End-user service:

The Assure API will use the information in the finalResult as input for the provider. It will also use “isSoundEx = true”.

Can I perform lookup/matching on any process?

No. You can only perform lookup/matching on processes that have finished and have been accepted (i.e., have an “accepted” status).

This is required because the lookup/matching service needs information about the person’s identity (such as their name and date of birth) and that information is only guaranteed to be correct in processes that have been “accepted”, i.e., in identities that have been verified.

Option 2: Perform Lookup/matching of any identity

If you need to perform a lookup/matching of any person you can just use the general lookup/matching service of the Assure API.

In this case, you don’t need to previously have any dossier nor process, but you must provide information about the person:

Must I send all this information about a person to perform a lookup/matching?

No. The minimum set of information you must to provide is one of the person’s names. But the more info you add about that person, the more filtered the results will be.
For example, if you just send “Ana” you will get a list with all the Ana’s in that database. But if you send more names and also a date of birth, for example, you will narrow that search to a closer match of who you’re looking for.

Result

Both services will provide a list of possible matches for that identity in that list.

Option 1 will append that information to the Get Process. This means that you will have to use Get Process to obtain the information after you used the Processes.Lookup End-user service (and obtained a “200 OK” response).

Option 2 will immediately provide you with a list of results, as exampled below.

Example of a Lookup Identity response:

{
    "name": "Luke",
    "hits": [
        {
            "name": "Luke Nilsson",
            "hitRating": 1,
            "dateOfBirth": "1965-07-13",
            "idNumber": "SE196507135496",
            "sourceName": "PEP_AC"
        },
        {
            "name": "Luke Nilsson",
            "hitRating": 1,
            "dateOfBirth": "1965-07-13",
            "idNumber": "SE196507135496",
            "sourceName": "PEP_Edge"
        }
    ]
}
Element Name Field Name Description Possible values Format
Name name The name that was input. String
hits

(A list of individuals matching the attributes that were sent)

name Name of the individual String
hitRating Indicates how relevant this list item is. The higher the number, the more accurate, with 5 being the most accurate:
Ssn = 5
BirthDate => 4
Year (Birthdate) => 2
Name => 1
[1-5]
dateOfBirth The date of birth Date: Normalized values
idNumber The SSN (social security number, used in this case to mean the national identification number for the country in question), or national identification number, of the individual in the issuing country’s format.
sourceName The name of the source.
  • EU_GLOBAL
  • PEP_Edge
  • UN_CONSOLIDATED

Callbacks

Because the identity verification is performed asynchronously (at least in most use cases), you can register to be notified when a verification is finished.
In that case, you need to provide your “notificationUrl” (and an “authorizationHeader” , if needed) when calling the Create Process service (or on Start Web SDK flow if you are using the alternate flow).

If you register, you will get a slim callback letting you know that the verification of a certain process is finished. This slim callback will contain the id of the process and its status:

Example of a slim callback sent by the Assure API when a verification is finished

{
    "processId":"3065980b-f26b-4ec2-8987-7833b7781dae",
    "status":"rejected"
}
Field Name Description Field type
processId The unique id of the process. string
status The final status of the process after being analysed by the provider. Enum

ImportantYour server’s URL must be whitelisted by Signicat in order to receive these notifications from the Assure API. Please contact the support team to do that.
If you are just testing, consider using https://labs.signicat.com/proxy (read more about it in the link) and avoid the whitelisting process.

To get the full information about the verification result, you will need to use the Get Process service, giving it the processId you got in the callback.
For detailed information about the Get Process response please check the Get Process Service Details section.

Normalization values

All elements in responses you get from the Assure API will be 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 31’66 Alpha 3 country codes. Ex: “PRT”, “NOR”

Enums

List of enums used by the API in requests/responses.

Provider

Name Value
Onfido onfido
Electronic-Id eid
ReadID readid

Document Type

To check the available values please use the service “Get Document Types“.

Process Type

(Note that this is only used for Electronic ID processes)

Value Description
attended Requires that the verification is performed live by an online agent (uses the Attended VideoID service from Electronic ID). The agent will request the end-user to show their ID (and provide other information) and will immediately accept/reject the request.
unattended (default) There is no need for an agent to be online, i.e., the verification is performed as usual (the iD images are uploaded, the request for the verification to start is sent and the result will be returned asynchronously).

Process Status

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

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 this one 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

Value Description
verylow The person in the selfie image is very unlikely to be the person in the document image.
low The person in the selfie image is probably not the same person as in the document image.
medium The person in the selfie image is probably the same person as in the document image.
high The person in the selfie image is very likely to be the same person in the document image.

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 consider.
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 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 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 info 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 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.

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.