Document Recognition V2#

Description#

Document Recognition V2 is an updated version of document recognition technology that provides advanced capabilities for document analysis and verification. The technology includes comprehensive image quality check, recognition of various document types, MRZ (machine-readable zone) check, and document authenticity assessment based on various security parameters.

Key benefits of V2:

Detailed image quality check (focus, glare, resolution, brightness)
Advanced optical document checks
Improved document type recognition with confidence assessment
Support for multi-page documents
Detailed information on check results

Below are the steps for using this technology in more detail. You can also check the OpenAPI specification of all the technologies available for use.

Stages:#

1. Obtaining an organisation's API-KEY#

The first stage for using the technology is to get API-KEY of the organisation. To get the API-KEY of the organisation, you need to log in to your Personal Area at this link. API-KEY is in the Backend Api Key field.

backend_api_key

An example of an organisation's API-KEY:

API-KEY: Efy202XKbVAWRu...

Note

For clarity, the shortened length is used API KEY. Its actual length is 47 or more characters.

2. Sending a request to scan a document#

Requests to this service use data in multipart/form-data format. The response data from the service will be in JSON format.

Request URL:

https://kyc.biometric.kz/api/v2/backend/document/process/

Request Format	Request Method
multipart/form-data	POST

API KEY must be passed in the request body:

Field name	Type	Required	Description
api_key	String	Yes	Organization API KEY in your personal account
file	File[]	Yes	Document files to process

Important

Unlike the first version of the API, V2 allows you to load multiple images of a document at once in the file array.

Request example#

cURLPythonJavaScript

curl -X 'POST' \
'https://kyc.biometric.kz/api/v2/backend/document/process/' \
-H 'accept: application/json' \
-H 'Content-Type: multipart/form-data' \
-F 'api_key=<YOUR_API_KEY>' \
-F 'file=@kz-id-front.jpg;type=image/jpeg' \
-F 'file=@kz-id-back.jpg;type=image/jpeg'

import requests

url = 'https://kyc.biometric.kz/api/v2/backend/document/process/'

files = [
    ('file', ('document-front.jpg', open('kz-id-front.jpg', 'rb'), 'image/jpeg')),
    ('file', ('document-back.jpg', open('kz-id-back.jpg', 'rb'), 'image/jpeg'))
]

data = {
    'api_key': '<YOUR_API_KEY>'
}

response = requests.post(url, files=files, data=data)
print(response.json())

const formData = new FormData();
formData.append('api_key', '<YOUR_API_KEY>');
formData.append('file', document.querySelector('#frontside').files[0]);
formData.append('file', document.querySelector('#backside').files[0]);

fetch('https://kyc.biometric.kz/api/v2/backend/document/process/', {
    method: 'POST',
    body: formData
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.log('error', error));

Response example#

Response field description#

backend_session_id - Unique session identifier
optical_checks - Document optical check results:
- overall_status - Overall check status
- doc_type - Document type check status
- expiry - Document expiration date check
- image_qa - Image quality check
- mrz - Machine-readable zone check
- pages_count - Document page count
- security - Security element check
- text - Text readability check
quality_checks - Quality check results for each document page:
- image_glares - Image glare check
- image_focus - Image sharpness check
- image_resolution - Image resolution check
- image_colorness - Image color rendering check
- perspective - Checking the correctness of the shooting angle
- bounds - Checking the visibility of the document boundaries
- portrait - Checking the quality of the photograph in the document
- brightness - Checking the level of illumination
- page - Document page identifier
document_types - Information about document types:
- name - Document name
- type - Document type. All document types are listed here
- type_id - Document type system identifier
- issue_year - Year of document form issue
- issuing_country - Document issuing country
- has_rfid - Presence of RFID chip in the document
- has_mrz - Presence of machine-readable zone
- format - Document format in the system
- country_code - ISO country code
- prediction - Confidence level in determining the document type
- required_light_schemes - Required light schemes for verification
- authenticity_light_schemes - Light schemes for authentication
- page - Document page number
- document_id - Internal document identifier in the system
visual_text_json - Text data extracted from the visual zone of the document. All field names that can be returned are listed here
mrz_text_json - Data extracted from the machine-readable zone
images - Images of the document and its elements:
- type - Image type
- content - Image in base64 format
- page - Page number for document images

Sample response in JSON format#

{
  "backend_session_id": "54dc1539-f9a4-4488-8e0d-04e87f86bcbe",
  "optical_checks": {
    "overall_status": true,
    "doc_type": true,
    "expiry": true,
    "image_qa": true,
    "mrz": true,
    "pages_count": 2,
    "security": true,
    "text": true
  },
  "quality_checks": [
    {
      "image_glares": true,
      "image_focus": true,
      "image_resolution": true,
      "perspective": true,
      "bounds": true,
      "portrait": true,
      "page": 0
    },
    {
      "image_glares": true,
      "image_focus": true,
      "image_resolution": true,
      "perspective": true,
      "bounds": true,
      "page": 1
    }
  ],
  "document_types": [
    {
      "name": "Kazakhstan - Id Card (2014) Side B",
      "type": "identity_card",
      "type_id": 12,
      "issue_year": "2014",
      "issuing_country": "Kazakhstan",
      "has_rfid": true,
      "has_mrz": true,
      "format": 0,
      "country_code": "KAZ",
      "prediction": 0.9406079649925234,
      "required_light_schemes": 25165824,
      "authenticity_light_schemes": 3224,
      "page": 1,
      "document_id": -1040772430
    },
    {
      "name": "Kazakhstan - Id Card (2014-2022)",
      "type": "identity_card",
      "type_id": 12,
      "issue_year": "2014-2022",
      "issuing_country": "Kazakhstan",
      "has_rfid": false,
      "has_mrz": false,
      "format": 0,
      "country_code": "KAZ",
      "prediction": 0.9425698518753053,
      "required_light_schemes": 25165824,
      "authenticity_light_schemes": 152,
      "page": 0,
      "document_id": -1040772594
    }
  ],
  "visual_text_json": {
    "surname_and_given_names": "ИВАНОВ ИВАН",
    "years_since_issue": "4",
    "age_at_issue": "24",
    "place_of_birth": "КАЗАХСТАН, АЛМАТЫ",
    "authority": "МВД РЕСПУБЛИКИ КАЗАХСТАН",
    "date_of_issue": "01.01.2020",
    "nationality": "КАЗАХ",
    "surname": "ИВАНОВ",
    "given_names": "ИВАН"
  },
  "mrz_text_json": {
    "document_class_code": "ID",
    "age": "29",
    "nationality": "Kazakhstan",
    "issuing_state_name": "Kazakhstan",
    "remainder_term": "63",
    "final_check_digit": "7",
    "nationality_code": "KAZ",
    "date_of_expiry_check_digit": "8",
    "date_of_expiry": "01.01.2030",
    "sex": "M",
    "date_of_birth_check_digit": "7",
    "date_of_birth": "01.01.1995",
    "personal_number": "950101300123",
    "mrz_strings": "IDKAZ0123456789950101300123<<<^9501017M3001018KAZ<<<<<<<<<<<7^IVANOV<<IVAN<<<<<<<<<<<<<<<<",
    "document_number_check_digit": "1",
    "document_number": "012345678",
    "issuing_state_code": "KAZ",
    "last_name": "IVANOV",
    "first_name": "IVAN",
    "given_names": "IVAN",
    "surname": "IVANOV",
    "mrz_type": "ID-1",
    "surname_and_given_names": "IVANOV IVAN",
    "line_2_optional_data": "KAZ",
    "optional_data": "950101300123"
  },
  "images": [
    {
      "type": "portrait",
      "content": "base64"
    },
    {
      "type": "signature",
      "content": "base64"
    },
    {
      "type": "bar_code",
      "content": "base64"
    },
    {
      "type": "document_front",
      "content": "base64",
      "page": 0
    },
    {
      "type": "document_front",
      "content": "base64",
      "page": 1
    },
    {
      "type": "ghost_portrait",
      "content": "base64"
    }
  ]
}