Address Service

Description#

Address Service - is a service-integration with Egov for obtaining a user's residence address.

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 the person who is the object of the request for a residence address
IIN - Individual identification number of a citizen of the Republic of Kazakhstan

Stages:#

1. Obtaining API-KEY of the organization#

The first step to use the technology is to obtain the organization's API-KEY. o get the organization's API-KEY, you need to go to Personal Cabinet by following this link 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 KEY is used for clarity. Its actual length is 47 characters or more.

2. Sending a request for a residential address#

When sending a request to obtain a residence address, 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/address/

Request format	Request method
JSON	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
iin	String	Yes	Subject's IIN

Request examples:

cURLPythonJavaScript

curl --location --request POST 'https://kyc.biometric.kz/api/v1/backend/address/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "api_key": "<ORGANIZATION_API_KEY>",
    "iin": "<SUBJECTS_IIN>"
}'

import requests
import json

url = "https://kyc.biometric.kz/api/v1/backend/address/"

payload = json.dumps({
  "api_key": "<ORGANIZATION_API_KEY>",
  "iin": "<SUBJECTS_IIN>"
})
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.json())

let myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

let raw = JSON.stringify({
  "api_key": "<ORGANIZATION_API_KEY>",
  "iin": "<SUBJECTS_IIN>"
});

let requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://kyc.biometric.kz/api/v1/backend/address/", 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:

backend_session_id - Backend session ID
iin - subject's IIN
address - Subject's address

Response example:

{
  "backend_session_id": "f1b5887b-5f91-417a-bf04-bb45fe28cc4e",
  "iin": "011212500777",
  "address": "*Subject's address*"
}

Errors#

Status code	Response	Description
409	Could not send request to address service	Failed to connect to address service
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