Saltar al contenido principal
POST
curl
La API de Validación de direcciones de Didit confirma que una dirección postal existe y la devuelve normalizada, con sus líneas de entrega, sus componentes y sus coordenadas. Usa POST /v3/address-validation/ cuando tu backend tenga una dirección y necesite saber si existe y cuál es su forma normalizada. La Validación de direcciones solo confirma la dirección. Nunca vincula la dirección con una persona: un resultado verified significa que el lugar existe, no que alguien viva allí.

Envía la dirección

Envíala en una sola línea en address, o como campos estructurados: address_line_1 y, cuando los tengas, address_line_2, city, region y postal_code. Nunca envíes ambos formatos en una misma solicitud. country siempre es obligatorio, como código ISO 3166-1 alfa-2 o alfa-3.

Interpreta la respuesta

  • address_validation.status es la respuesta sobre la que debes construir tu lógica:
    • verified: la dirección se confirmó hasta el edificio (o hasta la vivienda o el apartado postal).
    • partially_verified: se confirmó solo hasta la calle, o hasta el nivel más preciso que contienen los datos postales de referencia para ese lugar.
    • not_verified: solo coincidió la región o la ciudad, o no coincidió nada.
    • unavailable: no se pudo ejecutar la validación. Vuelve a intentarlo más tarde.
  • address_validation.verification_level es el nivel más preciso en el que hubo coincidencia: administrative_area, locality, thoroughfare, premise o delivery_point.
  • address_validation.address y address_validation.formatted_address contienen la dirección normalizada, escrita como se escribe en ese país.
  • address_validation.latitude y address_validation.longitude ubican la dirección encontrada.
  • request_id identifica la solicitud. No se crea ninguna sesión y el resultado solo se devuelve en esta respuesta, así que guarda lo que necesites.
El código HTTP es 200 para toda solicitud completada, unavailable incluido.

Validación de direcciones dentro de un flujo de verificación

La misma comprobación es un complemento de los pasos de Verificación de identidad y Prueba de domicilio del flujo de verificación (workflow). Activa address_validation_enabled en la configuración del paso y la dirección que aportó la persona (impresa en el documento de identidad o en la prueba de domicilio) se valida en cuanto se lee lo que subió. El resultado es el objeto address_validation de la entrada de ese paso en la decisión de la sesión (id_verifications[] o poa_verifications[]). Una dirección partially_verified o not_verified genera la advertencia ADDRESS_NOT_VERIFIED, cuya acción es la address_not_verified_action del paso (NO_ACTION por defecto, que solo registra la advertencia). Una validación unavailable nunca la genera y nunca modifica la verificación.

Comportamiento en sandbox

Las claves de sandbox validan la solicitud y siempre devuelven un resultado verified determinista que repite la dirección que enviaste. No consumen créditos.

Facturación

Una llamada a la API de Validación de direcciones cuesta $0.10 por dirección validada. Un resultado `unavailable` no se cobra. En un flujo, el complemento cuesta $0.10 por cada dirección validada por un paso.

Autorizaciones

x-api-key
string
header
requerido

La clave de API de tu aplicación, que encontrarás en Developers -> API keys en la Business Console. La clave principal tiene acceso completo. Una clave con nombre puede tener un alcance limitado: ninguno, lectura o escritura por recurso, limitada a algunos flujos o a sesiones aprobadas, a una lista de direcciones IP y a una fecha de caducidad. 401 significa que la clave es incorrecta, se revocó o expiró; 403 significa que no se envió ninguna clave, que la clave no tiene acceso a este recurso o acción, o que la solicitud provino de una dirección fuera de su lista de IP; 404 en una ruta de sesión significa que la sesión está fuera de los flujos o estados de la clave. Una clave sin acceso a contenido multimedia recibe las URL de imágenes, videos y PDF como null, y una clave sin permiso de escritura en sesiones recibe los enlaces y tokens de sesión como null. Consulta https://docs.didit.me/console/api-keys.

Cuerpo

application/json

Una dirección: en una sola línea (address) o como campos estructurados con al menos address_line_1, nunca ambas cosas.

country
string
requerido

Código ISO 3166-1 alpha-2 o alpha-3 del país de la dirección.

Maximum string length: 3
Ejemplo:

"US"

address
string

La dirección completa en una sola línea.

Maximum string length: 500
Ejemplo:

"Paseo de la Castellana 259, 28046 Madrid"

address_line_1
string

Calle y número.

Maximum string length: 255
Ejemplo:

"1600 Amphitheatre Pkwy"

address_line_2
string

Apartamento, oficina, planta o edificio.

Maximum string length: 255
city
string

Ciudad o localidad.

Maximum string length: 128
Ejemplo:

"Mountain View"

region
string

Estado, provincia o región.

Maximum string length: 128
Ejemplo:

"CA"

postal_code
string
Maximum string length: 32
Ejemplo:

"94043"

Respuesta

La validación se completó. Lee address_validation.status; el código HTTP es siempre 200 para una solicitud completada.

request_id
string<uuid>
requerido

Identificador de esta solicitud; indícalo al contactar con soporte. No se crea ninguna sesión.

address_validation
object
requerido

El resultado de una validación de dirección: si la dirección existe y su forma normalizada. Solo confirma la dirección; nunca la vincula a una persona.

created_at
string<date-time>
requerido
Última modificación el 1 de noviembre de 2026