Skip to content

Address

The overview describes the common field interpretation rules, failure reasons, and full/light file formats.

Parent: address_result. Registered address retrieved by IIN; a shared block for Address technology variants.

Fields of address_result.

Fields marked “Required” are always present within this object. Other fields are included when a value is available; null is excluded from the response.

Field JSON type Purpose and conditions
iin string Required. IIN used for the request.
status string, enum Required: UNAPPROVED, PENDING, VALID, INVALID, TIMEOUT, NOT_FOUND, FAILED, REQUEST_RATE_LIMIT_EXCEEDED_ERROR; see the meanings.
address object Structured address, if retrieved; see the table below.
failure_reason string, UUID Identifier of the recorded failure reason, if present. In this block, it is not a {type, detail} object. The aggregate error array may contain the reason's description.
result boolean Stored technology result: true means accepted, false means a negative result. May be absent before calculation; consider the status and the details below.

The Address result may already be false in the initial record before a response is received; interpret it together with status.

Parent: address_result.address.

Fields marked “Required” are always present within this object. Other fields are included when a value is available; null is excluded from the response.

Field JSON type Purpose and conditions
country object Country; see the territorial unit structure below.
region object Region; see the territorial unit structure below.
district object District; see the territorial unit structure below.
city string Locality.
street string Street.
building string Building number / designation.
flat string Apartment number / designation.
foreign_data object Dynamic foreign address data; the nested schema is not fixed.

Parents: address_result.address.country, .region, .district.

Fields marked “Required” are always present within this object. Other fields are included when a value is available; null is excluded from the response.

Field JSON type Purpose and conditions
code string Territorial unit code from the source; the API has no closed reference list.
nameRu string Name in Russian.
nameKz string Name in Kazakh.
changeDate string or object Modification date in the provider's format; may be a dynamic object instead of a string. No uniform format or nested schema is defined.

JSON examples

Fragments of the root response object, not complete responses. All values and URLs are illustrative. File formats follow the explanations on this page.

{
  "address_result": {
    "iin": "000000000000",
    "status": "FAILED",
    "address": {
      "country": {
        "code": "KZ",
        "nameRu": "Казахстан",
        "nameKz": "Қазақстан",
        "changeDate": "2026-01-01"
      },
      "region": {
        "code": "75",
        "nameRu": "Алматы",
        "nameKz": "Алматы",
        "changeDate": "2026-01-01"
      },
      "district": {
        "code": "7511",
        "nameRu": "Условный район",
        "nameKz": "Шартты аудан",
        "changeDate": "2026-01-01"
      },
      "city": "Almaty",
      "street": "Example Street",
      "building": "10",
      "flat": "20",
      "foreign_data": {
        "source": "example"
      }
    },
    "result": false
  }
}