> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API проверки почтового адреса: верификация и нормализация

> Didit: POST /v3/address-validation/ проверяет существование адреса и возвращает нормализованный адрес с координатами. $0.10 за адрес.

Didit Address Validation API подтверждает, что почтовый адрес существует, и возвращает его в нормализованном виде, со строками для доставки, компонентами и координатами. Используйте `POST /v3/address-validation/`, когда ваш бэкенд получил адрес и нужно узнать, существует ли он и в какой нормализованной форме.

Address Validation подтверждает только сам адрес. Он никогда не связывает адрес с человеком: результат `verified` означает, что такое место существует, но не то, что там кто-то живёт.

## Отправка адреса

Отправьте адрес одной строкой в поле `address` или в виде структурированных полей: `address_line_1` и, если они есть, `address_line_2`, `city`, `region` и `postal_code`.
Никогда не отправляйте оба формата в одном запросе.
Поле `country` всегда обязательно, в виде кода ISO 3166-1 alpha-2 или alpha-3.

## Интерпретация ответа

* `address_validation.status` является ответом, на который можно опираться:
  * `verified`: адрес подтверждён вплоть до здания (или квартиры, или абонентского ящика).
  * `partially_verified`: адрес подтверждён только до улицы или до наиболее точного уровня, который содержат почтовые справочные данные для этого места.
  * `not_verified`: совпал только регион или только город, либо не совпало ничего.
  * `unavailable`: проверку не удалось выполнить. Повторите попытку позже.
* `address_validation.verification_level` содержит наиболее точный совпавший уровень: `administrative_area`, `locality`, `thoroughfare`, `premise` или `delivery_point`.
* `address_validation.address` и `address_validation.formatted_address` содержат нормализованный адрес, записанный так, как его принято записывать в данной стране.
* `address_validation.latitude` и `address_validation.longitude` указывают местоположение найденного адреса.
* `request_id` идентифицирует запрос. Сессия не создаётся, а результат возвращается только в этом ответе, поэтому сохраните всё необходимое.

HTTP-статус `200` возвращается для каждого выполненного запроса, включая `unavailable`.

## Address Validation в сценарии

Та же проверка доступна как дополнительная опция шагов сценария Верификация личности и Подтверждение адреса.
Включите `address_validation_enabled` в настройках шага, и адрес, указанный человеком (напечатанный в документе, удостоверяющем личность, или в подтверждении адреса), будет проверен после считывания загруженного им файла.
Результат представлен объектом `address_validation` в записи этого шага в решении по сессии (`id_verifications[]` или `poa_verifications[]`).
Адрес со статусом `partially_verified` или `not_verified` вызывает предупреждение `ADDRESS_NOT_VERIFIED`, действие для которого задаёт `address_not_verified_action` шага (по умолчанию `NO_ACTION`, то есть предупреждение только фиксируется).
Проверка со статусом `unavailable` никогда не вызывает это предупреждение и никогда не меняет результат верификации.

## Поведение в песочнице

Ключи песочницы проверяют запрос и всегда возвращают детерминированный результат `verified`, который повторяет отправленный вами адрес. Они не расходуют кредиты.

## Биллинг

Вызов Address Validation API стоит $0.10 за проверенный адрес.
Результат `unavailable` не тарифицируется.
В сценарии дополнительная опция стоит $0.10 за каждый адрес, проверенный шагом.


## OpenAPI

````yaml ru/openapi-25.json POST /v3/address-validation/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: >-
    API верификации личности. Аутентификация выполняется с помощью заголовка
    x-api-key.
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/address-validation/:
    post:
      tags:
        - Standalone APIs
      summary: Проверить адрес
      description: >-
        Подтвердите факт существования адреса и получите его в нормализованном
        виде: строки доставки, компоненты и координаты. Проверяется только
        адрес; он никогда не связывается с человеком.


        **Запрос.** Отправьте адрес одной строкой (`address`) или
        структурированными полями (`address_line_1` и, опционально,
        `address_line_2`, `city`, `region`, `postal_code`), но не обоими
        способами одновременно, и обязательно укажите `country` (ISO 3166-1
        alpha-2 или alpha-3).


        **Результат.** `address_validation.status` принимает значение `verified`
        (подтверждён до здания), `partially_verified` (подтверждён только до
        улицы или выше), `not_verified` (совпали только регион или город, либо
        совпадений нет) или `unavailable` (проверку не удалось выполнить). Код
        HTTP: `200` для каждого завершённого запроса, включая `unavailable`;
        повторите запрос с результатом `unavailable` позже.


        **Биллинг.** Запрос в продакшене стоит $0.10 за проверенный адрес.
        Результат `unavailable` не тарифицируется. Ничего не сохраняется, кроме
        записи об использовании: сессия не создаётся, а результат возвращается
        только в этом ответе.


        **Песочница.** Ключи песочницы проверяют корректность запроса и всегда
        детерминированно возвращают результат `verified`, дублирующий переданный
        адрес, без списания кредитов.


        **Аутентификация.** Передавайте API-ключ вашего приложения в заголовке
        `x-api-key`. При отсутствии или недействительности учётных данных
        возвращается `403` - этот API никогда не возвращает `401`.


        **Лимит запросов.** Общий лимит на запись составляет 300 запросов в
        минуту на API-ключ для endpoints POST/PATCH/DELETE (создание транзакций
        и отправка событий имеют отдельный лимит в 600).
      operationId: post_v3_address_validation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressValidationRequest'
            examples:
              Structured:
                summary: Структурированные поля адреса
                value:
                  address_line_1: 1600 Amphitheatre Pkwy
                  city: Mountain View
                  region: CA
                  postal_code: '94043'
                  country: US
              One line:
                summary: Полный адрес одной строкой
                value:
                  address: Paseo de la Castellana 259, 28046 Madrid
                  country: ES
      responses:
        '200':
          description: >-
            Проверка завершена. Проверьте `address_validation.status`; HTTP-код
            для завершённого запроса всегда `200`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressValidationResponse'
              examples:
                Verified:
                  summary: Реальный адрес, подтверждённый вплоть до здания
                  value:
                    request_id: 6f7d2c1e-1c5a-4a1e-9b8f-2a1f0f4b9c3d
                    address_validation:
                      status: verified
                      verification_level: premise
                      address:
                        address_line_1: 1600 Amphitheatre Pkwy
                        address_line_2: null
                        city: Mountain View
                        region: CA
                        postal_code: 94043-1351
                        country: US
                      formatted_address: 1600 Amphitheatre Pkwy, Mountain View CA 94043-1351
                      latitude: 37.422022
                      longitude: -122.08429
                    created_at: '2026-10-27T11:20:00.000000+00:00'
                Not verified:
                  summary: 'Вымышленная улица: совпал только город'
                  value:
                    request_id: 0b9e3f4a-6c2d-4e8b-a1f7-5d3c2b1a0e9f
                    address_validation:
                      status: not_verified
                      verification_level: locality
                      address:
                        address_line_1: Calle Inventada Que No Existe 99999 28046
                        address_line_2: null
                        city: Madrid
                        region: Madrid
                        postal_code: null
                        country: ES
                      formatted_address: >-
                        Calle Inventada Que No Existe 99999 28046, Madrid,
                        MADRID, SPAIN
                      latitude: 40.42603054
                      longitude: -3.68645331
                    created_at: '2026-10-27T11:21:00.000000+00:00'
                Unavailable:
                  summary: Проверку не удалось выполнить; плата не взимается
                  value:
                    request_id: 3c1b2a0f-9e8d-4c7b-b6a5-1f0e9d8c7b6a
                    address_validation:
                      status: unavailable
                      verification_level: null
                      address: null
                      formatted_address: null
                      latitude: null
                      longitude: null
                    created_at: '2026-10-27T11:22:00.000000+00:00'
        '400':
          $ref: '#/components/responses/AddressValidationValidationError'
        '403':
          $ref: '#/components/responses/AddressValidationPermissionDenied'
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl -X POST https://verification.didit.me/v3/address-validation/ \
              -H 'x-api-key: YOUR_API_KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "address_line_1": "1600 Amphitheatre Pkwy",
                "city": "Mountain View",
                "region": "CA",
                "postal_code": "94043",
                "country": "US"
              }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.address_validation.validate(
                address_line_1="1600 Amphitheatre Pkwy",
                city="Mountain View",
                region="CA",
                postal_code="94043",
                country="US",
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

            // Reads DIDIT_API_KEY.
            const didit = new Didit();

            const result = await didit.addressValidation.validate({
              address_line_1: "1600 Amphitheatre Pkwy",
              city: "Mountain View",
              region: "CA",
              postal_code: "94043",
              country: "US",
            });
            console.log(result);
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;

            import me.didit.types.AddressValidationRequest;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.addressValidation().validate(AddressValidationRequest.builder()
                    .addressLine1("1600 Amphitheatre Pkwy")
                    .city("Mountain View")
                    .region("CA")
                    .postalCode("94043")
                    .country("US")
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->addressValidation->validate([
                'address_line_1' => '1600 Amphitheatre Pkwy',
                'city' => 'Mountain View',
                'region' => 'CA',
                'postal_code' => '94043',
                'country' => 'US',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.address_validation.validate(
              address_line_1: "1600 Amphitheatre Pkwy",
              city: "Mountain View",
              region: "CA",
              postal_code: "94043",
              country: "US"
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await client.AddressValidation.ValidateAsync(new
            AddressValidationRequest

            {
                AddressLine1 = "1600 Amphitheatre Pkwy",
                City = "Mountain View",
                Region = "CA",
                PostalCode = "94043",
                Country = "US",
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    AddressValidationRequest:
      type: object
      required:
        - country
      description: >-
        Один адрес: в одну строку (`address`) или в виде структурированных полей
        как минимум с `address_line_1`, но никогда оба варианта одновременно.
      properties:
        address:
          type: string
          maxLength: 500
          description: Полный адрес одной строкой.
          example: Paseo de la Castellana 259, 28046 Madrid
        address_line_1:
          type: string
          maxLength: 255
          description: Улица и номер дома.
          example: 1600 Amphitheatre Pkwy
        address_line_2:
          type: string
          maxLength: 255
          description: Квартира, номер офиса/помещения, этаж или здание.
        city:
          type: string
          maxLength: 128
          description: Город или населённый пункт.
          example: Mountain View
        region:
          type: string
          maxLength: 128
          description: Штат, провинция или регион.
          example: CA
        postal_code:
          type: string
          maxLength: 32
          example: '94043'
        country:
          type: string
          maxLength: 3
          description: >-
            Двух- или трехбуквенный код страны адреса по стандарту ISO 3166-1
            (alpha-2 или alpha-3).
          example: US
    AddressValidationResponse:
      type: object
      required:
        - request_id
        - address_validation
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            Идентификатор этого запроса; укажите его при обращении в поддержку.
            Сессия не создаётся.
        address_validation:
          $ref: '#/components/schemas/AddressValidationResult'
        created_at:
          type: string
          format: date-time
    AddressValidationResult:
      type: object
      description: >-
        Результат одной проверки Address Validation: существует ли адрес и его
        нормализованная форма. Подтверждается только адрес; он никогда не
        привязывается к человеку.
      required:
        - status
        - verification_level
        - address
        - formatted_address
        - latitude
        - longitude
      properties:
        status:
          type: string
          enum:
            - verified
            - partially_verified
            - not_verified
            - unavailable
          description: >-
            `verified`: адрес подтверждён с точностью до здания (или квартиры,
            или абонентского ящика). `partially_verified`: адрес подтверждён
            только до улицы либо до максимального уровня точности, доступного в
            почтовых справочных данных для этой местности. `not_verified`:
            совпал только регион или город, либо ничего не совпало.
            `unavailable`: проверку не удалось выполнить (например, справочный
            сервис не ответил); плата за неё не взимается, и она никак не влияет
            на верификацию.
        verification_level:
          type: string
          nullable: true
          enum:
            - administrative_area
            - locality
            - thoroughfare
            - premise
            - delivery_point
            - null
          description: >-
            Наиболее точный уровень, на котором совпал адрес. `null`, если
            совпадений нет или `status` имеет значение `unavailable`.
        address:
          type: object
          nullable: true
          description: Нормализованный адрес. `null`, если `status` равен `unavailable`.
          properties:
            address_line_1:
              type: string
              nullable: true
              description: >-
                Первая строка адреса доставки в формате, принятом в данной
                стране.
              example: 1600 Amphitheatre Pkwy
            address_line_2:
              type: string
              nullable: true
              description: >-
                Вторая строка адреса доставки (квартира, здание или район), если
                она есть в адресе.
            city:
              type: string
              nullable: true
              example: Mountain View
            region:
              type: string
              nullable: true
              description: Штат, провинция или регион.
              example: CA
            postal_code:
              type: string
              nullable: true
              example: 94043-1351
            country:
              type: string
              nullable: true
              description: Двухбуквенный код страны ISO 3166-1 alpha-2.
              example: US
        formatted_address:
          type: string
          nullable: true
          description: Нормализованный адрес в одну строку.
          example: 1600 Amphitheatre Pkwy, Mountain View CA 94043-1351
        latitude:
          type: number
          nullable: true
          example: 37.422022
        longitude:
          type: number
          nullable: true
          example: -122.08429
  responses:
    AddressValidationValidationError:
      description: >-
        Тело запроса недействительно: отсутствует или неизвестно поле `country`,
        отсутствует адрес, либо переданы одновременно `address` и
        структурированные поля.
      content:
        application/json:
          examples:
            Unknown country:
              value:
                country:
                  - >-
                    Use an ISO 3166-1 alpha-2 or alpha-3 country code, e.g. 'US'
                    or 'USA'.
            No address:
              value:
                address:
                  - >-
                    Send the address: 'address' on one line, or the structured
                    fields with 'address_line_1'.
            Both shapes:
              value:
                address:
                  - >-
                    Send either 'address' or the structured fields
                    (address_line_1, ...), not both.
    AddressValidationPermissionDenied:
      description: >-
        API-ключ отсутствует или недействителен, у ключа с ограниченной областью
        видимости отсутствует доступ на запись `sessions`, либо организация не
        может покрыть валидацию. Этот API никогда не возвращает `401`.
      content:
        application/json:
          examples:
            Missing or invalid API key:
              value:
                detail: You do not have permission to perform this action.
            Not enough credits:
              value:
                detail: >-
                  You don't have enough credits to perform this request. Please
                  top up at https://business.didit.me
                code: insufficient_credits
    RateLimitedWrite:
      description: >-
        Превышен общий лимит на запись в 300 запросов в минуту на один API-ключ.
        Подождите время, указанное в `Retry-After`, перед повторной попыткой.
      content:
        application/json:
          schema:
            type: object
            required:
              - detail
            properties:
              detail:
                type: string
          example:
            detail: >-
              Write request rate limit exceeded. You can make up to 300 requests
              per minute.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API-ключ вашего приложения из раздела «Разработчикам» -> «API-ключи» в
        Business Console. Основной ключ имеет полный доступ. Именованный ключ
        может иметь ограниченную область действия: без доступа, чтение или
        запись для каждого ресурса, ограничение определенными сценариями или
        одобренными сессиями, списком IP-адресов и сроком действия. 401
        означает, что ключ неверен, отозван или его срок действия истек; 403
        означает, что ключ не был передан, у ключа нет доступа к этому ресурсу
        или действию, либо запрос поступил с адреса вне его списка IP-адресов;
        404 на маршруте сессии означает, что сессия не входит в сценарии или
        статусы ключа. Ключ без доступа к медиа получает URL изображений, видео
        и PDF как null, а ключ без прав на запись сессий получает ссылки на
        сессии и токены как null. См. https://docs.didit.me/console/api-keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.