Data

The output of an API call is provided by our decision engine - an automated evaluation mechanism which helps us reduce the risk of fraud as well as improving customer experience in non-assisted enrollments. There are several logical units of evaluation which need to be considered in terms of decision mechanisms and these units are called Trust Factors.

Session Status #

To retrieve a status of the session. Very important endpoint to get an information about the session to check if

• it is being processed still (PENDING) and it is not possible to get results of it yet. If transaction wasn’t finished and session validity (default value is 14 days) is expired, endpoint will return EXPIRED status.
• additional actions are required after initial processing (WAITING_FOR_MANUAL_APPROVE);
• it is possible to retrieve transaction results from all endpoint below (AUTO_APPROVED, MANUAL_APPROVED, AUTO_REJECTED, MANUAL_REJECTED).

It is recommended to keep 1 minute interval for all status requests.

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

Response:
{
  "status": "AUTO_REJECTED",
}

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 except Sesslion List must contain sessionId in url: {sessionId}.

Use cases:

Decision Results #

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

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

Interpretation of these properties is described in Trust Factors section.

Response:
{
  "verifications": {
    "dateOfExpiration": {
      "score": 100,
      "level": "HIGH"
    },
    "dateOfExpiration": {
      "score": 100,
      "level": "HIGH"
    },
    "documentLiveness": {
      "score": 99,
      "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"
    },
    "barcodeOcrCrossCheck": {
      "fields": [
        {
          "inputFieldName": "document_number",
          "ocrTextValue": "PA123456",
          "barcodeTextValue": "PA123456",
          "distance": 0,
          "score": 100
        }
      ],
    "overallOcrFieldsConfidence": {
      "score": 98,
      "level": "HIGH"
    },
    "passiveLiveness": {
      "score": 97,
      "level": "HIGH"
    },
    "mrzValidity": {
      "score": 100,
      "level": "HIGH"
    }
  },
  "decision": {
    "score": 94,
    "level": "HIGH"
  }
}

Document Result #

To retrieve document ocr results & mrz data:

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:

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

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

Response:
{
  "country": "SVK",
  "documentType": "IDENTITY_CARD",
  "documentReleaseYear": "2018", 
  "applicant": 
    {
      "firstName": "JOHN", 
      "lastName": "DOE",
      "dateOfBirth": "1991-01-01", 
      "surnameAndGivenNames": "DOE JOHN"
    },
    "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<IRLPA22197234010191<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"
    },
  "documentBarcodeResults": [
    {
      "name": "sex",
      "value": "M"
    },
    {
      "name": "document_code",
      "value": "03"
    },
    {
      "name": "secondary_identifier",
      "value": "DOE"
    },
    {
      "name": "date_of_birth",
      "value": "1991-01-01"
    },
    {
      "name": "document_number",
      "value": "PA2219234"
    },
    {
      "name": "primary_identifier",
      "value": "JOHN"
    }
  ],
  "availableImages": [
    "primary_face",
    "signature",
    "original_normalized_BACK",
    "original_normalized_FRONT"
  ]
}

Face Result #

To retrieve face (selfie) properties.

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

Response:
{
"age": 34,
"gender": -10000,
"passiveLivenessScore": 100,
"verificationScore": 92,
"availableImages": [
"face_cropped"
]
}

Images #

Retrieve list of available images taken during onboarding process.

• /api/v1/data/fa389839-d740-42cc-ab31-f1cc1804992c/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

Session List #

To retrieve a list of all sessions. Contains following input parameters:

• PageNumber - numeric, to access specific page of all sessions
• PageSize - numberic, defines number of records to be returned per page

• /api/v1/data/session/list

Response:
{
  "pageNumber": 1,
  "pageSize": 10,
  "totalRecords": 1,
  "data": [
  {
    "id": "4fa85f64-5717-4562-b3fc-4c963f66afa6",
    "createdDateUtc": "2022-10-20T15:41:04.5605519+00:00",
    "expiryDateUtc": "2022-10-20T16:41:04.5585871+00:00",
    "documentType": "PASSPORT",
    "verificationStatus": "AUTO_REJECTED",
    "completedDateUtc": "2022-10-20T15:42:41.1875114+00:00",
    "country": "UKR"
  }
  ]
}

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.