Document Recognition
Description#
Document Recognition is a document reading technology. Automatic Document Identification recognises documents by type and country. Conducts a series of technical checks to detect fraud or inconsistencies and Verifies that all information is correct.
For comfortable integration via Backend API use Swagger (OpenAPI)
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.
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.
Important
To use this service, you must have a subscription to it. You can read more about subscriptions here.
URL of request:
https://kyc.biometric.kz/api/v1/backend/document/parse/
| Query format | Query method |
|---|---|
| multipart/form-data | POST |
API KEY must be passed in the request body:
| Field name | Type | Obligatorily | Description |
|---|---|---|---|
| api_key | String | Yes | API KEY of the organization in the personal cabinet |
| frontside_image | File | No | Document front side photo |
| backside_image | File | No | Document back side photo |
| country_code | File | yes | Document Country |
Important
Although the frontside_image and backside_image fields are optional,
one of these fields must necessarily be passed in the query.
Request examples:
import requests
url = "https://kyc.biometric.kz/api/v1/backend/document/parse/"
payload = {'api_key': '<YOUR_API_KEY>',
'country_code': 'kz'}
files=[
('frontside_image',('doc_front.jpg',open('doc_front.jpg','rb'),'image/jpeg')),
('backside_image',('doc_back.jpg',open('doc_back.jpg','rb'),'image/jpeg'))
]
headers = {}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)
var formdata = new FormData();
formdata.append("api_key", "<YOUR_API_KEY>");
formdata.append("frontside_image", fileInput.files[0], "doc_front.jpg");
formdata.append("backside_image", fileInput.files[0], "doc_back.jpg");
formdata.append("country_code", "kz");
var requestOptions = {
method: 'POST',
body: formdata,
redirect: 'follow'
};
fetch("https://kyc.biometric.kz/api/v1/backend/document/parse/", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
The response will be JSON with the following fields:
- first_name - First name;
- last_name - Last name;
- patronymic - Middle name/Patronymic;
- personal_number - Identification number;
- date_of_birth - Date of birth;
- document_number - Document number;
- authority - Issuing authority;
- date_of_issue - Date of issue;
- date_of_expiry - Expiration date;
- country_code - Document's country code;
- document_type - Information about document type;
- frontside / backside - Document sides;
- p - Confidence coefficient in determining the document type (0-1);
- id - Document type identifier;
- uv_exp - Camera exposure value for UV lighting required to capture images of this document type;
- fdsid_list - Additional document information and relationship with IRS documents;
- list - Array of IRS document identifiers;
- d_mrz - Presence of Machine Readable Zone (MRZ) on the document;
- d_type - Document type;
- d_year - Document issue year;
- d_format - Document format;
- icao_code - Country code according to ICAO classification;
- d_description - Description / type of document;
- d_country_name - Country name;
- document_name - Document name;
- rfid_presence - Presence of RFID chip in the document (0 - no, 1 - yes, 2 - unknown);
- necessary_lights - Set of lighting scheme identifiers required for OCR recognition of this document type;
- check_authenticity - Set of authenticity verification parameters for this document type;
- authenticity_necessary_lights - Set of lighting scheme identifiers required for authenticity verification of this document type;
- images - Photos in base64 format:
- face_photo - Face photo;
- front_side_image - Front side of the document photo;
- back_side_image - Back side of the document photo;
Response example:
{
"first_name": "Тест",
"last_name": "Тестов",
"patronymic": "Тестович",
"personal_number": "123456789012",
"date_of_birth": "01.10.1996",
"document_number": "document_number",
"authority": "МВД РЕСПУБЛИКИ КАЗАХСТАН",
"date_of_issue": "02.07.2012",
"date_of_expiry": "02.07.2022",
"country_code": "kz",
"document_type": {
"frontside": {
"p": 0.9425698518753053,
"id": -1040772594,
"uv_exp": 6,
"fdsid_list": {
"list": [
15400,
21490,
21495,
21657,
22165
],
"d_mrz": false,
"d_type": 12,
"d_year": "2014-2022",
"d_format": 0,
"icao_code": "KAZ",
"d_state_code": null,
"d_state_name": null,
"d_description": "Identity Card",
"d_country_name": "Kazakhstan"
},
"document_name": "Kazakhstan - Id Card (2014-2022)",
"rfid_presence": 0,
"necessary_lights": 25165824,
"check_authenticity": 524837,
"authenticity_necessary_lights": 152
},
"backside": {
"document_name": "Kazakhstan - Id Card (2014) Side B",
"id": -1040772430,
"p": 0.9406079649925234,
"rfid_presence": 1,
"fdsid_list": {
"icao_code": "KAZ",
"list": [
15400,
21495,
21657,
21490
],
"d_type": 12,
"d_format": 0,
"d_mrz": true,
"d_description": "Identity Card",
"d_year": "2014",
"d_country_name": "Kazakhstan",
"d_state_code": null,
"d_state_name": null
},
"necessary_lights": 25165824,
"check_authenticity": 10552359,
"uv_exp": 6,
"authenticity_necessary_lights": 3224
}
},
"images": {
"face_photo": "base64",
"front_side_image": "base64",
"front_side_image": "base64"
},
"failure_reason": "None"
}
Errors#
| Код состояния | Ответ | Описание |
|---|---|---|
| 400 | Frontside document not found | Front side document data not found |
| 400 | Document image at frontside_image field is not frontside |
Document image is not the front side |
| 400 | Document image at backside_image field is not backside |
Document image is not the back side |
| 400 | Client does not have access to Document Recognition Technology | Client does not have access to the technology. Reasons: subscription is missing, expired, or the technology is not active Причины: подписка отсутствует, либо она истекла, или технология не активна |
| 415 | Not allowed file, valid extensions: .jpg .png .jpeg | Invalid file extension, allowed extensions: .jpg .png .jpeg |
| 400 | Subscription has not started | Subscription has not been activated yet |
| 400 | No active or future subscription for technology | No active or future subscription for the technology |
| 400 | Client does not have subscription | Client does not have a subscription, read more about subscriptions here |