Vai al contenuto principale
POST
cURL

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

multipart/form-data
user_image
file
obbligatorio

Immagine del volto dal vivo o candidata da verificare (es. un selfie). Invia una singola foto frontale con il volto del soggetto chiaramente visibile e ben illuminato. Estensioni consentite: tiff, jpg, jpeg, png, webp. Dimensione massima di caricamento: 5 MB (i file più grandi vengono rifiutati con 400). Le immagini vengono compresse automaticamente a circa 0,5 MB prima dell'elaborazione, quindi risoluzioni molto elevate non migliorano la precisione.

ref_image
file
obbligatorio

Immagine del volto di riferimento con cui effettuare il confronto (es. la fototessera di un documento d'identità o una foto registrata in precedenza). Stessi limiti di formato e dimensione di user_image.

face_match_score_decline_threshold
number<float>
predefinito:30

Soglia di somiglianza (0–100) che determina lo status della risposta. Un punteggio calcolato pari o inferiore a questo valore imposta status su Declined e aggiunge un avviso LOW_FACE_MATCH_SIMILARITY; un punteggio rigorosamente superiore restituisce Approved. Il valore predefinito 30 è permissivo — aumentalo (ad es. 50–60) per una verifica più rigorosa. I valori al di fuori di 0–100 restituiscono 400.

Intervallo richiesto: 0 <= x <= 100
Esempio:

50

rotate_image
boolean
predefinito:false

Quando è true, il servizio prova le immagini di input con incrementi di 90 gradi (0, 90, 180, 270) e utilizza l'orientamento che offre il miglior rilevamento del volto; utile per le acquisizioni da dispositivo mobile prive di orientamento EXIF. Aggiunge latenza, quindi attivalo solo se non puoi garantire immagini orientate correttamente.

Esempio:

false

save_api_request
boolean
predefinito:true

Quando è true (predefinito), rende persistente la chiamata come sessione di tipo API — visibile nella Business Console, recuperabile tramite GET /v3/session/{sessionId}/decision/ utilizzando il request_id restituito, e notificata tramite un webhook status.updated. Quando è false, non viene memorizzato nulla e request_id è un UUID temporaneo utilizzabile solo per la correlazione della risposta.

Esempio:

true

vendor_data
string

Stringa opaca opzionale (il tuo ID utente interno, email, UUID...) memorizzata nella sessione persistita e restituita nella risposta. Usala per correlare le chiamate API con i tuoi record e per filtrare le sessioni in un secondo momento.

Esempio:

"user-123"

metadata
object

Oggetto JSON opzionale memorizzato con la sessione (quando save_api_request=true) e restituito nella risposta. Nelle richieste multipart, invialo come campo stringa con codifica JSON (ad es. metadata={"flow":"login"}) — viene interpretato come oggetto.

Esempio:

Risposta

Confronto facciale calcolato. face_match.score è un numero decimale compreso tra 0 e 100 (due cifre decimali); status è Approved quando il punteggio è strettamente superiore a face_match_score_decline_threshold, altrimenti Declined con un avviso esplicativo. Una coppia con bassa somiglianza o non valutabile restituisce comunque 200: esamina face_match.status e face_match.warnings, non solo il codice HTTP. Quando save_api_request=true, request_id è l'ID della sessione salvata.

request_id
string<uuid>

ID della sessione salvata quando save_api_request=true (utilizzabile con GET /v3/session/{sessionId}/decision/); altrimenti un UUID di correlazione temporaneo.

face_match
object
vendor_data
string | null

Eco del vendor_data inviato, o null.

metadata
object | null

Eco dell'oggetto metadata inviato, o null.

created_at
string<date-time>

Timestamp ISO 8601 (UTC) di generazione della risposta, ad es. 2026-06-12T01:04:42.763237+00:00.

Ultima modifica il 7 novembre 2026