MX-Document

Description

MX-Document is a service integration
for scanning documents, retrieving digital information about a subject from the state database, and
comparing subject faces obtained after scanning the document and extracting information.

For seamless integration through the Backend API,
use Swagger (OpenAPI)

---

Steps:

1. Obtaining the Organization API-KEY

The first step in using the technology is to obtain the organization’s API-KEY.
To get the API-KEY, log in to your Personal Account via
this link.
The API-KEY is located in the Backend Api Key field.

Example of an organization API-KEY:

API-KEY: Efy202XKbVAWRu...

Note

For demonstration purposes, a shortened version of the API KEY is shown. The actual length is 47 or more characters.

2. Sending a request to run the MX-Document technology

When sending a request to run the MX-Document technology, the data is sent in JSON format.

Important

To use this service, you must have an active subscription.
More about subscriptions can be found here.

Request URL:

https://kyc.biometric.kz/api/v1/backend/mx-document/extract-id-qr/

Request format	Method
multipart/form-data	POST

The API KEY must be passed in the request body:

Наименование поля	Тип	Обязательно	Описание
api_key	String	Да	API KEY организации в личном кабинете
frontside_image	File	Да	Переднее изображение документа
backside_image	File	Да	Заднее изображение документа

Request examples:

cURLPythonJavaScript

    curl -X 'POST' \
    'https://kyc.biometric.kz/api/v1/backend/mx-document/extract-id-qr/' \
    -H 'accept: application/json' \
    -H 'Content-Type: multipart/form-data' \
    -F 'frontside_image=@<path_to_frontside_image;type=image/<image_extension>' \
    -F 'backside_image=@<path_to_backside_image;type=image/<image_extension>' \
    -F 'api_key=<organization_api_key>'

import requests

url = 'https://kyc.biometric.kz/api/v1/backend/mx-document/extract-id-qr/'

headers = {
    'Accept': 'application/json',
    'Content-Type': 'multipart/form-data',
}

files = {
    'frontside_image': (
        frontside_image_path,
        open(frontside_image_path, 'rb'),
        'image/<image_extension>',
    ),
    'backside_image': (
        backside_image_path,
        open(backside_image_path, 'rb'),
        'image/<image_extension>',
    ),
}

data = {
    'api_key': '<organization_api_key>',
}

response = requests.post(
    url=url,
    headers=headers,
    data=data,
    files=files,
)

print(response.json())

/*
    dependencies to install via npm: 
    form-data, fs, node-fetch
*/

import FormData from 'form-data';
import fs from 'fs';
import fetch from 'node-fetch';

const url = 'https://kyc.biometric.kz/api/v1/backend/mx-document/extract-id-qr/';
const apiKey = '<organization_api_key>';
const frontside_image_path = "<path_to_frontside_image>";
const backside_image_path = "<path_to_backside_image>";

const formData = new FormData();
formData.append('api_key', apiKey);
formData.append('frontside_image', fs.createReadStream(frontside_image_path));
formData.append('backside_image', fs.createReadStream(backside_image_path));

fetch(url, {
    method: 'POST',
    headers: {
    'accept': 'application/json',
    },
    body: formData
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));

The response will contain the data extracted from the document in JSON format with the following fields:

• face_photo – subject’s face photo in base64 format.
• result – status of the technology process.
• result_json – subject’s document scanning data in JSON format.
• qr_extraction_data – information extracted from the QR code in JSON format.
• qr_validation_data – QR code validation data in JSON format.
• face_comparison_data – result of the face comparison obtained during the process in JSON format.
• failure_reason – reason for the technology failure.

---

Errors

Status Code	Response	Description
400	No active or future subscription for technology MX-Document	No active or upcoming subscription for MX-Document technology
404	Not Found	Object not found (e.g., Organization by the specified API-KEY)
400	MX-Document extraction failed	Basic error during document recognition
400	QR-code not found	QR code not found
400	Invalid image data provided	Invalid document image provided
400	Client does not have access to MX-Document technology	The client does not have access to the technology. Reasons: no subscription, subscription expired, or technology is not active
400	MX-Document result already exist	The MX-Document result already exists
400	Subscription has not started	The subscription has not yet been activated
400	Client does not have subscription	The client does not have a subscription. More details about subscriptions can be found here
422	Validation Error	Required values were not provided in the request or their type does not match the documentation
503	Cannot connect to MX-Document service	Unable to connect to the MX-Document service
503	Cannot decode MX-Document response	Unable to decode the response from the MX-Document service