GBDFL

Description#

GBDFL is a service for obtaining verified information about individuals from the State Database of the Republic of Kazakhstan. The data is provided based on the Individual Identification Number IIN of the subject.

For convenient integration via Backend API, please use Swagger (OpenAPI)

Terms#

Subject - A person who is the object of a request to obtain information from GBDFL
OTP code - A temporary code that is sent to the subject's phone from 1414 and is used to confirm receipt of electronic documents
State Database of Individuals (GBDFL) - Unified database of individuals of the Republic of Kazakhstan
IIN - Individual Identification Number of a citizen of the Republic of Kazakhstan

Steps:#

1. Obtaining the organization's API-KEY#

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 log in to the Personal Cabinet at this link. The API-KEY is located in the Backend Api Key field

backend_api_key

Example of organization's API-KEY:

API-KEY: Efy202XKbVAWRu...

Note

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

2. Sending a request to obtain information from GBDFL #

Important to consider

To request data from GBDFL, you must complete the following technologies using Backend integration:

Liveness (Subject's face)
E-Document (Subject's identity card)
Face2Face (Using sessions obtained from completing the previous two technologies)

After completing the above technologies, information about the subject from GBDFL can be obtained within 3 hours

When sending a request to obtain an electronic document, data in JSON format is used.

Important

To use this service, you must have a subscription to it. You can read more about subscriptions here.

Request URL:

https://kyc.biometric.kz/api/v1/backend/gbdfl/

Request format	Request method
JSON	POST

API KEY must be passed in the request body:

Field name	Type	Required	Description
api_key	String	Yes	Organization's API KEY in personal cabinet
iin	String	Yes	IIN of the subject
face2face_backend_session_id	String	Yes	Backend session ID

Request examples:

cURLPythonJavaScript

    curl -X 'POST' \
    'https://kyc.biometric.kz/api/v1/backend/gbdfl/' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
    "api_key": "<organization_api_key>",
    "iin": "<subjects_iin>",
    "face2face_backend_session_id": "<backend_session_id>"
    }'

import requests

url = 'https://kyc.biometric.kz/api/v1/backend/gbdfl/'

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

data = {
    'api_key': '<organization_api_key>',
    'iin': '<subjects_iin>',
    'face2face_backend_session_id': '<backend_session_id>',
}

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

print(response.json())

const url = 'https://kyc.biometric.kz/api/v1/backend/gbdfl/';

const apiKey = '<organization_api_key>';

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

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

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 a JSON with the following fields:

backend_session_id - Session identifier
failure_reason - Reason for unsuccessful completion
type - Error type
detail - Detailed error description
face2face_result - Face2Face comparison result
- prediction - Comparison result prediction
- prediction_percent - Face matching percentage
- backend_session_id - Face2Face session identifier
- result - Boolean result of successful comparison (true/false)
- source_session_1 - Data of the first source session for comparison
  - id - Unique session identifier
  - technology - Technology information
    - name - Technology name
    - code - Technology code
  - status - Session status (CREATED, FAILED, etc.)
  - created_at - Session creation date and time
  - updated_at - Last session update date and time
- source_session_2 - Data of the second source session for comparison
  - id - Unique session identifier
  - technology - Technology information
    - name - Technology name
    - code - Technology code
  - status - Session status (CREATED, FAILED, etc.)
  - created_at - Session creation date and time
  - updated_at - Last session update date and time
iin - IIN of the Subject
result_json - Result data in JSON format
- iin - Individual Identification Number of the subject
- surname - Subject's surname
- name - Subject's first name
- patronymic - Subject's patronymic
- birth_date - Subject's date of birth (format: YYYY-MM-DD)
- gender - Subject's gender (Male/Female)
- nationality - Subject's nationality
- citizenship - Subject's citizenship
- life_status - Subject's life status
- birth_place - Birth place information
  - country - Country of birth
  - region - Region of birth
  - district - District of birth
  - city - City of birth
- documents - Array of subject's documents
  - type - Document type (e.g., ID CARD RK, PASSPORT)
  - number - Document number
  - issue_date - Document issue date (format: YYYY-MM-DD)
  - expiry_date - Document expiry date (format: YYYY-MM-DD)
  - issuer - Issuing authority
  - status - Document validity status (e.g., DOCUMENT IS VALID)
- registration_address - Subject's registration address
  - country - Registration country
  - region - Registration region
  - district - Registration district
  - city - Registration city
  - street - Registration street
  - building - Building number
  - flat - Apartment number
  - begin_date - Registration start date at the address (format: YYYY-MM-DD)
status - Status of obtaining information from GBDFL
result - Result of successful completion (true/false)

Note

The following statuses are possible for obtaining information from GBDFL:

UNAPPROVED
PENDING
VALID
INVALID
TIMEOUT
NOT_FOUND
FAILED
ERROR_ACCEPTED

Response example:

{
  "backend_session_id": "a7f3c891-4b2e-4d5a-9c7f-1e8d6b9a3f2c",
  "failure_reason": null,
  "face2face_result": {
    "prediction": "0.987214",
    "prediction_percent": "98.7",
    "backend_session_id": "3e9b7d42-6c1a-4f8e-a2d5-9b4c8e1f7a3d",
    "result": true,
    "source_session_1": {
      "id": "5f8a2c3d-9e4b-4a1c-b7d6-2f3e8a9c1b4d",
      "technology": {
        "name": "Liveness Short",
        "code": "LDSH"
      },
      "status": "COMPLETED",
      "created_at": "2025-10-15T10:23:45.123Z",
      "updated_at": "2025-10-15T10:24:12.456Z"
    },
    "source_session_2": {
      "id": "8b4d3a2c-1e9f-4c7a-a5b8-6d2e9f3c1a7b",
      "technology": {
        "name": "E-Document",
        "code": "ED"
      },
      "status": "COMPLETED",
      "created_at": "2025-10-15T10:24:30.789Z",
      "updated_at": "2025-10-15T10:25:18.234Z"
    }
  },
  "iin": "950215301234",
  "result_json": {
    "iin": "950215301234",
    "surname": "Нурланов",
    "name": "Асхат",
    "patronymic": "Ерланович",
    "birth_date": "1995-02-15",
    "gender": "Мужской",
    "nationality": "КАЗАХ",
    "citizenship": "КАЗАХСТАН",
    "life_status": "Нормальный",
    "birth_place": {
      "country": "КАЗАХСТАН",
      "region": "Алматинская область",
      "district": "Талгарский",
      "city": "Талгар"
    },
    "documents": [
      {
        "type": "УДОСТОВЕРЕНИЕ РК",
        "number": "N23456789",
        "issue_date": "2015-03-10",
        "expiry_date": "2035-03-10",
        "issuer": "МВД РК",
        "status": "ДОКУМЕНТ ДЕЙСТВИТЕЛЕН"
      },
      {
        "type": "ПАСПОРТ",
        "number": "N98765432",
        "issue_date": "2020-08-15",
        "expiry_date": "2030-08-15",
        "issuer": "МВД РК",
        "status": "ДОКУМЕНТ ДЕЙСТВИТЕЛЕН"
      }
    ],
    "registration_address": {
      "country": "КАЗАХСТАН",
      "region": "Алматы",
      "district": "Медеуский",
      "city": "Алматы",
      "street": "Абая",
      "building": "52",
      "flat": "45",
      "begin_date": "2018-06-20"
    }
  },
  "status": "VALID",
  "result": true
}

Errors#

Status Code	Response	Description
400	Subscription has not started	The 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, you can read more about subscriptions here
400	Client does not have access to GBDFL technology	Client does not have access to the technology. Reasons: subscription is missing, expired, or the technology is not active
404	Face2Face backend session not found	Backend session with Face2Face result not found
404	Organization not found	Organization not found for the provided API key

Failure Reasons#

failure_reason.type	failure_reason.detail	Description
CLIENT	The required verifications for GBDFL are expired	The validity period of required verifications (Liveness/EDocument) has expired
CLIENT	INVALID	Invalid token received from the government service
CLIENT	TIMEOUT	Token received from the government service has expired
CLIENT	NOT_FOUND	Requested data for the subject was not found
CLIENT	FAILED	Error while retrieving data from the government service
CLIENT	Face2Face failed	Negative Face2Face result
CLIENT	Liveness failed	Negative Liveness result
CLIENT	EDocument validation error:	Negative EDocument result
CLIENT	Required technology in Face2Face result missing: tech_code, tech_code	Face2Face result was not obtained from required technology sessions (Liveness/EDocument)
CLIENT	Face2Face source sessions are missing	Face2Face result was not obtained from technology sessions
CLIENT	GBDFL Face2Face result missing	Face2Face session does not contain a result
SERVICE_ERROR	Can`t connect to GBDFL service	Failed to send request to GBDFL service