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",
    "result": false,
    "failure_reason": "55555555-5555-4555-8555-555555555555"
  }
}