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 frontale del viso da utilizzare per la ricerca. 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 ~0.5 MB prima dell'elaborazione, pertanto risoluzioni molto elevate non migliorano la precisione. L'immagine deve contenere almeno un volto rilevabile — altrimenti l'endpoint restituisce 400. Quando sono presenti più volti, la ricerca viene eseguita su quello più grande e viene aggiunto un avviso MULTIPLE_FACES_DETECTED.

search_type
enum<string>
predefinito:most_similar

Politica di ricerca. most_similar (predefinita) classifica ogni volto registrato nella tua applicazione in base alla somiglianza. blocklisted_or_approved limita i candidati ai volti in blocklist, ai volti in allowlist, ai volti provenienti da sessioni approvate e ai volti dei profili utente importati — posizionando per prime le voci in blocklist.

Opzioni disponibili:
most_similar,
blocklisted_or_approved
Esempio:

"most_similar"

rotate_image
boolean
predefinito:false

Quando è true, il servizio prova rotazioni di 90 gradi dell'input e utilizza l'orientamento che offre il miglior rilevamento del volto. Utile quando manca l'orientamento EXIF. Aggiunge latenza.

Esempio:

false

save_api_request
boolean
predefinito:true

Quando è true (predefinito), memorizza la chiamata come sessione di tipo API, emette un webhook status.updated, pre-firma i valori di match_image_url e registra il volto cercato nel tuo indice di Ricerca facciale (le registrazioni di Ricerca facciale sono escluse dalle ricerche future). Quando è false, la ricerca è una tantum — non viene memorizzata alcuna sessione e il volto non viene registrato.

Esempio:

true

vendor_data
string

Identificativo opaco opzionale (il tuo ID utente, email, UUID...) memorizzato nella sessione persistita e restituito. Non esclude i volti dello stesso utente dai risultati di ricerca.

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: viene interpretato come oggetto.

Esempio:

Risposta

Ricerca facciale completata. face_search.matches contiene fino a 5 volti simili ordinati per somiglianza; un array vuoto indica che nessun volto registrato ha superato la soglia minima di somiglianza. status è Declined solo in caso di corrispondenze con la blocklist; le sole corrispondenze duplicate restituiscono Approved, quindi esamina matches e warnings, non solo status. Quando save_api_request=true, request_id è l'ID della sessione salvata. Ciascuna corrispondenza include source (session, imported, list_entry o retained_template), vendor_user_id e biometric_template_id; una corrispondenza retained_template proviene da un modello biometrico senza immagini conservato dopo l'eliminazione della sessione di origine e presenta campi di sessione, match_image_url e user_details impostati su null.

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.

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