Web Flow

If you have an API username and API password you can create an enrolment token. This token will be used to identify your user.

Create a new enrolment session

The API currently supports basic authentication. All endpoints require an Authentication header in the following form:

Authorization: 'Basic ' + Base64.encode(username + ':' + password)

Send a HTTP POST request to:

  • /enrolment/api/v1/Session/init

The following parameters are used for requests and responses:

ParameterDirectionDescription
sessionIdrequestunique, short-lived code to be generated by the client to track specific sessions
returnUrlrequestcustom page to be displayed by the client solution after completion of the onboarding process, usually the progress bar should be displayed waiting for one of the available verification results: HIGH, MEDIUM, LOW (meaning and expected workflow described in Trust Factors section)
accessTokenresponseJWT access token to be used in the enrolment process during Redirect to Web Enrolment
sessionIdresponsethe same unique code sent in request, returned for the traceability
Request:
{
  "sessionId": "ad90c821-e5ea-4385-be5b-4fc9f9ea24ee",
  "returnUrl": "{A url where end user will be redirected after enrolment}"
}

Response:
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uSWQiOiJhZDkwYzgyMS1lNWVhLTQzODUtYmU1Yi00ZmM5ZjllYTI0ZWU
  iLCJjdXN0b21lciI6IjEyZjUwMjM1LWFkNmYtNDVmNi1iOGM1LTE2ZGM1N2QwOTI1MyIsIm5iZiI6MTY0Mzk3NDMyMywiZXhwIjoxNjQzOTc3OTIzfQ.t5zU
  PHZjpo-q3Rl5ZibyKSaBXAdItuCRdTBMS2JW8gQ",
  "sessionId": "ad90c821-e5ea-4385-be5b-4fc9f9ea24ee"
}

Example:
curl -X POST "
/enrolment/api/v1/Session/init" -H "accept: text/plain" -H
"Authorization: Basic aW5ub3ZhdHJpY3M6aW5ub3ZhdHJpY3M=" -H "Content-Type: application/json" -d "{\"sessionId\":\"ad90c82
1-e5ea-4385-be5b-4fc9f9ea24ee\",\"returnUrl\":\"your url\"}"

Redirect to Web Enrolment

After successfully generating a token you should have a valid accessToken.

You may initiate a HTTP redirect action for your client to:

  • /web-enrolment/

by appending a generated token as a URL query string parameter. An example redirect URL looks like this:

  • /web-enrolment/?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

After the redirection, the user will see our WEB Enrolment UI:

The number of steps depends on the configuration; the standard configuration is document capture followed by face capture. After completion of these steps, the user is redirected to the URL defined in returnUrl: “{A url where the end user will be redirected after enrolment}” described in Send Request.

Data Retrieval

When the end user completes the enrolment you can request data and status of the enrolment. Request must contain basic auth header with API username and API password:

Authorization: 'Basic ' + Base64.encode(username + ':' + password) Every request must contain sessionId in url: {sessionId}.

Use cases:

Use caseDescriptionEndpoint
Decision Resultsretrieve verification score and trust factors scores of the onboarding process/decision/results
Document Resultretrieve document attributes (OCR, images, MRZ parsing)/document/result
Face Resultretrieve face (selfie) properties/face/result
Imagesretrieve list of available images/images
Image Downloaddownload image/image/{imageName}

Decision Results

To retrieve verification score and trust factors scores. Contains 2 properties:

PropertyDescription
verificationsList of Trust Factors scores (each contains score/level pair)
decisionMain output of whole process, contains score/level pair
  • /api/v1/data/fa389839-d740-42cc-ab31-f1cc1804992c/decision/results

Interpretation of these properties is described in Trust Factors section.

Response:
{
  "verifications": {
    "age": {
      "score": 100,
      "level": "HIGH"
    },
    "dateOfExpiration": {
      "score": 100,
      "level": "HIGH"
    },
    "faceVerification": {
      "score": 71,
      "level": "HIGH"
    },
    "mrzOcrCrossCheck": {
      "fields": [
        {
          "inputFieldName": "firstName",
          "ocrTextValue": "John",
          "mrzTextValue": "John",
          "distance": 0,
          "score": 100
        },
        {
          "inputFieldName": "lastName",
          "ocrTextValue": "Doe",
          "mrzTextValue": "Doe",
          "distance": 0,
          "score": 100
        }
      ],
      "score": 100,
      "level": "HIGH"
    },
    "passiveLiveness": {
      "score": 97,
      "level": "HIGH"
    }
  },
  "decision": {
    "score": 94,
    "level": "HIGH"
  }
}

Document Result

To retrieve document ocr results & mrz data:

PropertiesDescription
documentVisualResultslist of parameters read from visual part of the document - depends on document type and country
documentMrzResultsparsed MRZ fields (if MRZ presents)
availableImageslist of parsed document images

documentMrzResults property contains “name”/“value” pair for each field, documentVisualResults contains “name”/“value”, plus confience (0..100), pageSide (BACK or FRONT) and “normalizedDateValue” if field is about Date format.

List of all supported fields:

Visual
document_number
document_class_code
issuing_state_name
issuing_state_code
nationality
given_name
surname
personal_number
date_of_birth
date_of_expiry
date_of_issue
sex
place_of_birth
height
authority
MRZ
full_string
mrz_type
document_code
issuing_state_or_organization
primary_identifier
secondary_identifier
document_number
document_number_check_digit
nationality
date_of_birth
date_of_birth_check_digit
sex
date_of_expiry
date_of_expiry_check_digit
personal_number_or_optional_data
personal_number_or_optional_data_check_digit
composite_check_digit
Images
primary_face
signature
fingerprint
original_normalized

Please note not all field might be located on the specific document.

  • /api/v1/data/fa389839-d740-42cc-ab31-f1cc1804992c/document/result
Response:
{
  "documentVisualResults": [
    {
      "name": "authority",
      "value": "Main Passport Office, Dublin",
      "confidence": 90,
      "pageSide": "BACK"
    },
    {
      "name": "date_of_issue",
      "normalizedDateValue": "2018-08-01T00:00:00",
      "value": "2018-08-01”,
      "confidence": 90,
      "pageSide": "BACK"
    },
    {
      "name": "height”,
      "value": "175 cm",
      "confidence": 100,
      "pageSide": "BACK"
    },
    {
      "name": "sex",
      "value": "M",
      "confidence": 100,
      "pageSide": "BACK"
    },
    {
      "name": "date_of_birth",
      "normalizedDateValue": "1991-01-01T00:00:00",
      "value": "1991-01-01”,
      "confidence": 100,
      "pageSide": "FRONT"
    },
    {
      "name": "date_of_expiry",
      "normalizedDateValue": "2023-08-01T00:00:00",
      "value": "2023-08-01”,
      "confidence": 90,
      "pageSide": "FRONT"
    },
    {
      "name": "document_number",
      "value": "PA2219234”,
      "confidence": 90,
      "pageSide": "FRONT"
    },
    {
      "name": "given_name",
      "value": “JOHN,
      "confidence": 100,
      "pageSide": "FRONT"
    },
    {
      "name": "nationality",
      "value": "LATVIJAS",
      "confidence": 91,
      "pageSide": "FRONT"
    },
    {
      "name": "personal_number",
      "value": “01019111111”,
      "confidence": 100,
      "pageSide": "FRONT"
    },
    {
      "name": "surname",
      "value": “DOE”,
      "confidence": 95,
      "pageSide": "FRONT"
    }
  ],
  "documentMrzResults": [
    {
      "name": "composite_check_digit",
      "value": "1"
    },
    {
      "name": "date_of_birth",
      "value": "1991-01-01”
    },
    {
      "name": "date_of_birth_check_digit",
      "value": "2"
    },
    {
      "name": "date_of_expiry",
      "value": "2023-08-01”
    },
    {
      "name": "date_of_expiry_check_digit",
      "value": "6"
    },
    {
      "name": "document_code",
      "value": "I"
    },
    {
      "name": "document_number",
      "value": "PA2219234”
    },
    {
      "name": "document_number_check_digit",
      "value": "4"
    },
    {
      "name": "full_string",
      "value": "I<LVAPA22197234010191<11102<<<^9103122M2308146IRL<<<<<<<<<<<1^DOE<<<<<<<<JOHN<<<<<<<<<<<<<<<"
    },
    {
      "name": "issuing_state_or_organization",
      "value": "IRL”
    },
    {
      "name": "mrz_type",
      "value": "ID-1"
    },
    {
      "name": "nationality",
      "value": "IRL"
    },
    {
      "name": "personal_number_or_optional_data",
      "value": "01019111111"
    },
    {
      "name": "primary_identifier",
      "value": "JOHN"
    },
    {
      "name": "secondary_identifier",
      "value": "DOE"
    },
    {
      "name": "sex",
      "value": "M"
    }
  ],
  "availableImages": [
    "primary_face",
    "signature",
    "original_normalized_BACK",
    "original_normalized_FRONT"
  ]
}

Face Result

To retrieve face (selfie) properties.

PropertiesDescription
detectionScorethe face attribute for evaluating the confidence score of the face related to the face detection. Face confidence values are within the interval [0,10000]. The higher the value of the attribute, the better quality of the face. The decision threshold is around 600
ageestimated age of applicant in years
passiveLivenessScorethe face attribute for evaluating the passive liveness score of a face. Passive liveness score values are within the interval [0,100]. Values between 0 and 89 indicate ‘face not live’, values over 89 indicate face live
verificationScoreresult of document image and selfie comparison within the interval [0;100]. Values between 0 and 36 indicate ‘no match’, values over 36 indicate ‘match’
availableImageslist of face images
  • /api/v1/data/fa389839-d740-42cc-ab31-f1cc1804992c/face/result
Response:
{
  "detectionScore": 7160.8154297,
  "age": 32.0765076,
  "gender": -9927,
  "passiveLivenessScore": 97.1387558,
  "verificationScore": 70.6021347,
  "availableImages": [
    "face_cropped"
  ]
}

Images

Retrieve list of available images taken during onboarding process.

  • /api/v1/data/fa389839-d740-42cc-ab31-f1cc1804992c/images
PropertiesDescription
documentlist of document images, usually contains images of the whole document, face image; sometimes additional images like signature, QR code, etc.
facelist of face images, usually contains original and cropped images
Response:
{
  "document": [
    "primary_face",
    "original_normalized_FRONT",
    "original_normalized_BACK"
  ],
  "face": [
    "face_cropped"
  ]
}

Image Download

Download a specific image taken during onboarding process and available as a line in Images endpoint.

  • /api/v1/data/fa389839-d740-42cc-ab31-f1cc1804992c/images/primary_face

In response, content type will be image/jpeg:

 content-length: 61505
 content-type: image/jpeg

Data Deletion

Delete onboarding data belonging to you. This endpoint removes all person data including photos (document, face), parsed document information, trust factors, scores etc.

The API currently supports basic authentication. All endpoints require an Authentication header in the following form:

Authorization: 'Basic ' + Base64.encode(username + ':' + password)

Send a HTTP DELETE request to:

  • /api/v1/data/fa389839-d740-42cc-ab31-f1cc1804992c

No input properties for this endpoint.