Vai al contenuto principale
POST
curl
L’API Address Validation di Didit conferma che un indirizzo postale esiste e lo restituisce normalizzato, con le sue righe di recapito, le componenti e le coordinate. Usa POST /v3/address-validation/ quando il tuo backend ha un indirizzo e deve sapere se esiste e in quale forma normalizzata. Address Validation conferma solo l’indirizzo. Non collega mai l’indirizzo a una persona: un risultato verified indica che il luogo esiste, non che qualcuno vi abiti.

Invia l’indirizzo

Invialo su una sola riga in address, oppure come campi strutturati: address_line_1 e, se disponibili, address_line_2, city, region e postal_code. Non inviare mai entrambe le forme nella stessa richiesta. country è sempre obbligatorio, come codice ISO 3166-1 alpha-2 o alpha-3.

Interpreta la risposta

  • address_validation.status è la risposta su cui basarsi:
    • verified: l’indirizzo è stato confermato fino all’edificio (o all’appartamento o alla casella postale).
    • partially_verified: è stato confermato solo fino alla via, oppure al livello più preciso che i dati di riferimento postali contengono per quel luogo.
    • not_verified: hanno trovato corrispondenza solo la regione o la città, oppure nessun elemento.
    • unavailable: la validazione non è stata eseguita. Riprova più tardi.
  • address_validation.verification_level è il livello più preciso trovato: administrative_area, locality, thoroughfare, premise o delivery_point.
  • address_validation.address e address_validation.formatted_address contengono l’indirizzo normalizzato, scritto nel modo in cui lo scrive il paese.
  • address_validation.latitude e address_validation.longitude indicano la posizione dell’indirizzo trovato.
  • request_id identifica la richiesta. Non viene creata alcuna sessione e il risultato è restituito solo in questa risposta, quindi salva ciò che ti serve.
HTTP restituisce 200 per ogni richiesta completata, incluso unavailable.

Address Validation all’interno di un workflow

Lo stesso controllo è un’aggiunta ai passaggi del workflow ID Verification e Proof of Address. Attiva address_validation_enabled nelle impostazioni del passaggio: l’indirizzo fornito dalla persona (stampato sul documento d’identità o sulla prova di residenza) viene validato una volta elaborato il caricamento. Il risultato è l’oggetto address_validation nella voce di quel passaggio all’interno della decisione della sessione (id_verifications[] o poa_verifications[]). Un indirizzo partially_verified o not_verified genera l’avviso ADDRESS_NOT_VERIFIED, la cui azione è address_not_verified_action del passaggio (NO_ACTION per impostazione predefinita, che si limita a registrare l’avviso). Una validazione unavailable non genera mai questo avviso e non modifica mai la verifica.

Comportamento in sandbox

Le chiavi sandbox validano la richiesta e restituiscono sempre un risultato verified deterministico che riprende l’indirizzo inviato. Non consumano crediti.

Fatturazione

Ogni chiamata all’API Address Validation costa $0.10 per indirizzo validato. Un risultato `unavailable` non viene addebitato. In un workflow, l'aggiunta costa $0.10 per ogni indirizzo validato da un passaggio.

Autorizzazioni

x-api-key
string
header
obbligatorio

La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys.

Corpo

application/json

Un indirizzo: su una riga (address) o come campi strutturati con almeno address_line_1, mai entrambi.

country
string
obbligatorio

Codice ISO 3166-1 alpha-2 o alpha-3 del paese dell'indirizzo.

Maximum string length: 3
Esempio:

"US"

address
string

L'indirizzo completo su una sola riga.

Maximum string length: 500
Esempio:

"Paseo de la Castellana 259, 28046 Madrid"

address_line_1
string

Via e numero civico.

Maximum string length: 255
Esempio:

"1600 Amphitheatre Pkwy"

address_line_2
string

Appartamento, suite, piano o edificio.

Maximum string length: 255
city
string

Città o località.

Maximum string length: 128
Esempio:

"Mountain View"

region
string

Stato, provincia o regione.

Maximum string length: 128
Esempio:

"CA"

postal_code
string
Maximum string length: 32
Esempio:

"94043"

Risposta

La validazione è stata completata. Leggi address_validation.status; il codice HTTP è sempre 200 per una richiesta completata.

request_id
string<uuid>
obbligatorio

Identificatore di questa richiesta; comunicalo all'assistenza. Non viene creata alcuna sessione.

address_validation
object
obbligatorio

Il risultato di una verifica dell'indirizzo (Address Validation): se l'indirizzo esiste e la sua forma normalizzata. Conferma esclusivamente l'indirizzo; non collega mai l'indirizzo a una persona.

created_at
string<date-time>
obbligatorio
Ultima modifica il 7 novembre 2026