Saltar al contingut principal
POST
cURL

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

multipart/form-data
user_image
file
requerit

Imatge frontal del rostre per fer la cerca. Extensions permeses: tiff, jpg, jpeg, png, webp. Mida màxima de càrrega: 5 MB (els fitxers més grans es rebutgen amb 400). Les imatges es comprimeixen automàticament a ~0.5 MB abans de processar-les, de manera que una resolució gaire alta no millora la precisió. La imatge ha de contenir almenys una cara detectable; en cas contrari, l'endpoint retorna 400. Si hi ha diverses cares presents, es busca la més gran i s'afegeix una advertència MULTIPLE_FACES_DETECTED.

search_type
enum<string>
predeterminat:most_similar

Política de cerca. most_similar (per defecte) classifica cada cara registrada a la teva aplicació per similitud. blocklisted_or_approved restringeix els candidats a cares a la llista de bloqueig, cares a la llista blanca, cares de sessions aprovades i cares de perfils d'usuari importats — classificant les entrades a la llista de bloqueig en primer lloc.

Opcions disponibles:
most_similar,
blocklisted_or_approved
Exemple:

"most_similar"

rotate_image
boolean
predeterminat:false

Quan és true, el servei prova rotacions de 90 graus de l'entrada i utilitza l'orientació que ofereix la millor detecció facial. Útil quan falta l'orientació EXIF. Afegeix latència.

Exemple:

false

save_api_request
boolean
predeterminat:true

Quan és true (per defecte), manté la crida com una sessió de tipus API, emet un webhook status.updated, presigna els valors de match_image_url i inscriu la cara cercada al teu índex de cerca facial (les inscripcions de Cerca facial s'exclouen de cerques futures). Quan és false, la cerca és d'un sol ús: no s'emmagatzema cap sessió i la cara no s'inscriu.

Exemple:

true

vendor_data
string

Identificador opac opcional (el teu ID d'usuari, correu electrònic, UUID…) desat a la sessió persistent i retornat a la resposta. No exclou les cares del mateix usuari dels resultats de cerca.

Exemple:

"user-123"

metadata
object

Objecte JSON opcional emmagatzemat amb la sessió (quan save_api_request=true) i retornat. En sol·licituds multipart, envia'l com a camp de cadena codificat en JSON; s'analitza com un objecte.

Exemple:

Resposta

Cerca facial completada. face_search.matches conté fins a 5 cares similars ordenades per similitud; una matriu buida vol dir que cap cara registrada ha superat el llindar mínim de similitud. status és Declined només per coincidències amb la llista de bloqueig — les coincidències duplicades per si soles retornen Approved, per tant inspecciona matches i warnings, no només status. Quan save_api_request=true, request_id és l'identificador de sessió persistit. Cada coincidència conté source (session, imported, list_entry o retained_template), vendor_user_id i biometric_template_id; una coincidència retained_template prové d'una plantilla biomètrica sense imatge conservada després que la sessió d'origen s'hagués suprimit i té null als camps de sessió, match_image_url i user_details.

request_id
string<uuid>

ID de sessió persistida quan save_api_request=true (utilitzable amb GET /v3/session/{sessionId}/decision/); en cas contrari, un UUID de correlació transitori.

vendor_data
string | null

Ressò de les vendor_data que has enviat, o null.

metadata
object | null

Ressò de l'objecte metadata que has enviat, o null.

created_at
string<date-time>

Marca de temps ISO 8601 (UTC) de quan s'ha generat la resposta, p. ex. 2026-06-12T01:04:42.763237+00:00.

Darrera modificació el 7 de novembre del 2026