Skip to content

E-Document

Description#

E-Document - is a service-integration with Egov to receive personal electronic documents from the state database. Electronic documents can be obtained in JSON, PDF or photo format.

The steps for using this technology are described in more detail below. You can also check the OpenAPI-specification of all available technologies to use.

Terms#

  • Subject - is a person who is the object of an electronic document request in the E-Document service.
  • OTP-code - is a temporary code that comes to the subject's phone from 1414 and is used to confirm receipt of electronic documents.
  • Mobile Citizen Data Base(MCDB) - is a unified database of users' mobile phone numbers required to provide public services, send SMS passwords when authorizing or signing up for services, using a one-time password. Find the instructions on how to register in the database here.
  • IIN - individual identification number of a citizen of the Republic of Kazakhstan.
  • Unix timestamp - is a system for describing moments in time adopted by Unix and other POSIX-compatible operating systems. Defined as the number of seconds elapsed since midnight on January 1, 1970.

Stages:#

1. Obtaining API-KEY of the organization#

The first step to use the technology is to obtain the organization's API-KEY. To get the organization's API-KEY, you need to go to Personal Cabinet by following this link. API-KEY is in the Backend Api Key field.

backend_api_key

An example of an organization's API-KEY:

API-KEY: Efy202XKbVAWRu...

Note

The shortened length of the API KEYis used for clarity. Its actual length is 47 characters or more.

2. Sending a request for an electronic document#

The following should be taken into account

To request an electronic document of a subject his/her personal data must be registered in the Mobile Citizen Data Base of the Republic of Kazakhstan.

When sending a request for an electronic document, data in JSON format is used

Important

To use this service, you must have a subscription. Read more about subscriptions here.

Request URL:

https://kyc.biometric.kz/api/v1/backend/e-document/online-access/request/

Request format Request method
JSON POST

document_type must be passed as a path parameter:

Value Description
identity_card Identity card
driver_license Driver`s license
birth_certificate Certificate of birth
marriage_certificate Certificate of marriage
change_fio_certificate Сertificate of change of surname, first name, patronymic
divorce_certificate Divorce certificate
diploma Diploma
srts SRTS
vaccination Vaccination passport
social_id Social ID
disability_certificate ID of a person with a disability
large_family_certificate Certificate of a large family
asp_certificate Certificate of the recipient of targeted social assistance
tech_passport Technical passport
pension Pension
passport Passport of a citizen of the Republic of Kazakhstan
student_card Student card
vnzh Residence Permit
pcr_certificate The Result of PCR testing on COVID-19
lbg_card Stateless Person Card
insurance_policy Insurance Policy
hunter Hunter Certificate
oralman Oralman
attorney Attorney

The following should be taken into account

To request the required type of document, it must be in the state database of the Republic of Kazakhstan. If there is no document in the database, the subject will not receive a message with the OTP-code for further confirmation and receipt of the electronic document.

Unfortunately, we are not entitled to provide information about the presence or absence of a document due to the limitations of a government service that does not provide such data.

API KEY must be passed in the request body:

Field name Type required Description
api_key String Yes API KEY of the organization in the personal cabinet
iin String Yes Subject's IIN(#subject-anchor)
phone String Yes Subject's phone number

Request examples:

    curl -X 'POST' \
    'https://kyc.biometric.kz/api/v1/backend/e-document/online-access/request/{document_type}/' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
    "api_key": "<organization_api_key>",
    "iin": "<subjects_iin>",
    "phone": "<subjects_phone>"
    }'

import requests

url = 'https://kyc.biometric.kz/api/v1/backend/e-document/online-access/request/{document_type}/'

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

data = {
    'api_key': '<organization_api_key>',
    'iin': '<subjects_iin>',
    'phone': '<subjects_phone>',
}

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

print(response.json())

const url = 'https://kyc.biometric.kz/api/v1/backend/e-document/online-access/request/{document_type}/';

const apiKey = '<organization_api_key>';

const headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
};

const data = {
    api_key: apiKey,
    iin: '<subjects_iin>',
    phone: '<subjects_phone>'
};

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

The response will be JSON with the following fields:

  • backend_session_id - session identifier for receiving an electronic document;

After sending the request, the subject phone number specified in the request receives a message with an OTP-code for further confirmation and receipt of an electronic document.

3. Sending a request for confirmation of receipt of an electronic document#

The following should be taken into account

It is obligatory to send a request for an electronic document.

Requests to our service use only data in JSON format.
Response data from the service will be presented in the same format.

Request URL:

https://kyc.biometric.kz/api/v1/backend/e-document/online-access/approve/

Request format Request method
JSON POST
Field name Type required Description
backend_session_id String Yes Session ID, from the response of sending a request for receiving
code String Yes Received OTP-code
file Boolean Yes Include document file in response
file_type String Yes Document file type. Available values: pdf, image

Request examples:

    curl -X 'POST' \
    'https://kyc.biometric.kz/api/v1/backend/e-document/online-access/approve/' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
    "backend_session_id": "<backend_session_id>",
    "code": "<otp_code>",
    "file": true,
    "file_type": "pdf"
  }'

import requests

url = 'https://kyc.biometric.kz/api/v1/backend/e-document/online-access/approve/'

headers = {
    'accept': 'application/json',
    'Content-Type': 'application/json',
}

data = {
    'backend_session_id': '<backend_session_id>',
    'code': '<otp_code>',
    'file': True,
    'file_type': 'pdf',
}

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

print(response.json())

const url = 'https://kyc.biometric.kz/api/v1/backend/e-document/online-access/approve/';

const headers = {
    'accept': 'application/json',
    'Content-Type': 'application/json',
};

const data = {
    'backend_session_id': '<backend_session_id>',
    'code': '<otp_code>',
    'file': true,
    'file_type': 'pdf',
};

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

Important

All images and files come in base64 format.
Depending on the file type selected in the confirmation request, the electronic document may come as a pdf or a base64 image.
The received files must be saved with a .pdf or .jpg .

The response will be a JSON formated requested document with the folowing fields:

  • document_type - document type.
  • result_json - data of the subject's document in json format.
  • face_photo - photo of the subject's face in base64 format.
  • qrcode - qrcode of the subject's document in base64 format.
  • barcode - barcode of the subject's document in base64 format.
  • document_image - image of the subject's document, in base64 format.
  • document_pdf - subject's document in PDF format in base64 encoding.

Errors#

Status code Response Description
404 Subject not found in CMDB The user is not registered in the MCDB(mobile citizens database). Find instructions on how to register in the database here
503 Can`t connect to e-document service Unable to connect to the Egov government service
503 EDocument service is not available now The Egov government service is not currently available
504 Could not send request to e-document service Timeout of request to the Egov government service
424 Government service error Received an unprocessed response from the Egov government service
404 Profile is not found The profile of the requested citizen was not found
400 Invalid IIN Invalid IIN
400 EDocument for this session has already been received E-Document for this session has already been received. Occurs if the user with the same session passes several times
400 Client does not have access to E-Document technology Client does not have access to the technology. Reasons: No subscription, or it has expired, or the technology is not active
400 You have already requested a document for this session You cannot make multiple requests with the same session
400 You have not sent a request for access to an e-document User did not request access to the electronic document, send a request to receive the document
400 Subscription has not started Subscription has not been activated yet
400 No active or future subscription for technology No active or future subscription to the technology
400 Client does not have subscription Client does not have a subscription, you can read more about subscriptions here