Перейти к основному содержанию
POST
curl
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 за каждый адрес, проверенный шагом.

Авторизации

x-api-key
string
header
обязательно

API-ключ вашего приложения из раздела «Разработчикам» -> «API-ключи» в Business Console. Основной ключ имеет полный доступ. Именованный ключ может иметь ограниченную область действия: без доступа, чтение или запись для каждого ресурса, ограничение определенными сценариями или одобренными сессиями, списком IP-адресов и сроком действия. 401 означает, что ключ неверен, отозван или его срок действия истек; 403 означает, что ключ не был передан, у ключа нет доступа к этому ресурсу или действию, либо запрос поступил с адреса вне его списка IP-адресов; 404 на маршруте сессии означает, что сессия не входит в сценарии или статусы ключа. Ключ без доступа к медиа получает URL изображений, видео и PDF как null, а ключ без прав на запись сессий получает ссылки на сессии и токены как null. См. https://docs.didit.me/console/api-keys.

Тело

application/json

Один адрес: в одну строку (address) или в виде структурированных полей как минимум с address_line_1, но никогда оба варианта одновременно.

country
string
обязательно

Двух- или трехбуквенный код страны адреса по стандарту ISO 3166-1 (alpha-2 или alpha-3).

Maximum string length: 3
Пример:

"US"

address
string

Полный адрес одной строкой.

Maximum string length: 500
Пример:

"Paseo de la Castellana 259, 28046 Madrid"

address_line_1
string

Улица и номер дома.

Maximum string length: 255
Пример:

"1600 Amphitheatre Pkwy"

address_line_2
string

Квартира, номер офиса/помещения, этаж или здание.

Maximum string length: 255
city
string

Город или населённый пункт.

Maximum string length: 128
Пример:

"Mountain View"

region
string

Штат, провинция или регион.

Maximum string length: 128
Пример:

"CA"

postal_code
string
Maximum string length: 32
Пример:

"94043"

Ответ

Проверка завершена. Проверьте address_validation.status; HTTP-код для завершённого запроса всегда 200.

request_id
string<uuid>
обязательно

Идентификатор этого запроса; укажите его при обращении в поддержку. Сессия не создаётся.

address_validation
object
обязательно

Результат одной проверки Address Validation: существует ли адрес и его нормализованная форма. Подтверждается только адрес; он никогда не привязывается к человеку.

created_at
string<date-time>
обязательно
Последнее изменение 7 ноября 2026 г.