Saltar al contingut principal
POST
curl
L’API d’Address Validation de Didit confirma que una adreça postal existeix i la retorna normalitzada, amb les seves línies de lliurament, components i coordenades. Fes servir POST /v3/address-validation/ quan el teu backend tingui una adreça i necessiti saber si existeix i en quina forma normalitzada. Address Validation només confirma l’adreça. Mai no vincula l’adreça amb una persona: un resultat verified vol dir que el lloc existeix, no que hi visqui ningú.

Envia l’adreça

Envia-la en una sola línia a address, o bé com a camps estructurats: address_line_1 i, si els tens, address_line_2, city, region i postal_code. Mai no enviïs les dues formes en una mateixa sol·licitud. country és sempre obligatori, com a codi ISO 3166-1 alpha-2 o alpha-3.

Interpreta la resposta

  • address_validation.status és la resposta en què pots basar-te:
    • verified: l’adreça s’ha confirmat fins a l’edifici (o el pis o l’apartat de correus).
    • partially_verified: s’ha confirmat només fins al carrer, o fins al nivell més precís que les dades de referència postals tenen per a aquell lloc.
    • not_verified: només ha coincidit la regió o la ciutat, o no ha coincidit res.
    • unavailable: la validació no ha pogut executar-se. Torna-ho a intentar més tard.
  • address_validation.verification_level és el nivell més precís que ha coincidit: administrative_area, locality, thoroughfare, premise o delivery_point.
  • address_validation.address i address_validation.formatted_address contenen l’adreça normalitzada, escrita com l’escriu el país.
  • address_validation.latitude i address_validation.longitude situen l’adreça coincident.
  • request_id identifica la sol·licitud. No es crea cap sessió i el resultat només es retorna en aquesta resposta, així que guarda el que necessitis.
El codi HTTP és 200 per a totes les sol·licituds completades, inclòs unavailable.

Address Validation dins d’un flux de treball

El mateix control és un complement dels passos dels fluxos de treball de Verificació d’identitat i de Comprovant de domicili. Activa address_validation_enabled a la configuració del pas, i l’adreça que ha facilitat la persona (impresa al document d’identitat o al comprovant de domicili) es validarà un cop s’hagi llegit la càrrega. El resultat és l’objecte address_validation de l’entrada d’aquell pas dins de la decisió de la sessió (id_verifications[] o poa_verifications[]). Una adreça partially_verified o not_verified activa l’advertència ADDRESS_NOT_VERIFIED, l’acció de la qual és el valor de address_not_verified_action del pas (NO_ACTION per defecte, que només registra l’advertència). Una validació unavailable mai no activa aquesta advertència i mai no canvia la verificació.

Comportament del sandbox

Les claus de sandbox validen la sol·licitud i retornen sempre un resultat verified determinista que retorna l’adreça que has enviat. No consumeixen crèdits.

Facturació

Una crida a l’API d’Address Validation costa $0.10 per adreça validada. Un resultat `unavailable` no es cobra. En un flux de treball, el complement costa $0.10 per cada adreça que un pas hagi validat.

Autoritzacions

x-api-key
string
header
requerit

La clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau primària té accés complet. Una clau amb nom pot tenir l'abast limitat: cap, lectura o escriptura per recurs, limitada a determinats fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 significa que la clau és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una ruta de sessió significa que la sessió està fora dels fluxos de treball o estats de la clau. Una clau sense accés a fitxers multimèdia rep els URL d'imatge, vídeo i PDF com a null, i una clau sense permís d'escriptura de sessions rep els enllaços de sessió i els tokens com a null. Consulta https://docs.didit.me/console/api-keys.

Cos

application/json

Una adreça: en una sola línia (address) o com a camps estructurats amb almenys address_line_1, mai tots dos alhora.

country
string
requerit

Codi ISO 3166-1 alpha-2 o alpha-3 del país de l'adreça.

Maximum string length: 3
Exemple:

"US"

address
string

Tota l'adreça en una sola línia.

Maximum string length: 500
Exemple:

"Paseo de la Castellana 259, 28046 Madrid"

address_line_1
string

Carrer i número.

Maximum string length: 255
Exemple:

"1600 Amphitheatre Pkwy"

address_line_2
string

Apartament, suite, planta o edifici.

Maximum string length: 255
city
string

Ciutat o localitat.

Maximum string length: 128
Exemple:

"Mountain View"

region
string

Estat, província o regió.

Maximum string length: 128
Exemple:

"CA"

postal_code
string
Maximum string length: 32
Exemple:

"94043"

Resposta

La validació s'ha completat. Llegeix address_validation.status; HTTP és sempre 200 per a una sol·licitud completada.

request_id
string<uuid>
requerit

Identificador d'aquesta sol·licitud; indica'l a l'equip de suport. No s'ha creat cap sessió.

address_validation
object
requerit

El resultat d'una Address Validation: si l'adreça existeix i la seva forma normalitzada. Només confirma l'adreça; mai vincula l'adreça a una persona.

created_at
string<date-time>
requerit
Darrera modificació el 7 de novembre del 2026