Passer au contenu principal
POST
cURL

Autorisations

x-api-key
string
header
requis

La clé API de votre application, issue de Développeurs -> Clés API dans la Business Console. La clé principale dispose d'un accès complet. Une clé nommée peut être restreinte : aucun, lecture ou écriture par ressource, limitée à certains workflows ou aux sessions approuvées, à une liste d'adresses IP et à une date d'expiration. 401 signifie que la clé est incorrecte, révoquée ou expirée ; 403 signifie qu'aucune clé n'a été envoyée, que la clé n'a pas accès à cette ressource ou action, ou que la requête provient d'une adresse hors de sa liste d'IP ; 404 sur une route de session signifie que la session est hors des workflows ou des statuts de la clé. Une clé sans accès aux médias reçoit les URL d'images, de vidéos et de PDF à null, et une clé sans accès en écriture aux sessions reçoit les liens et tokens de session à null. Voir https://docs.didit.me/console/api-keys.

Corps

multipart/form-data
user_image
file
requis

Image du visage de face avec laquelle effectuer la recherche. Extensions autorisées : tiff, jpg, jpeg, png, webp. Taille maximale de téléversement : 5 MB (les fichiers plus volumineux sont rejetés avec une erreur 400). Les images sont automatiquement compressées à ~0.5 MB avant traitement, de sorte que les très hautes résolutions n'améliorent pas la précision. L'image doit contenir au moins un visage détectable — sinon l'endpoint renvoie 400. Lorsque plusieurs visages sont présents, la recherche porte sur le plus grand et un avertissement MULTIPLE_FACES_DETECTED est ajouté.

search_type
enum<string>
défaut:most_similar

Règle de recherche. most_similar (par défaut) classe chaque visage inscrit dans votre application par similarité. blocklisted_or_approved restreint les candidats aux visages sur liste de blocage, sur liste blanche, aux visages issus de sessions approuvées et aux visages de profils d'utilisateurs importés — les entrées sur liste de blocage étant classées en premier.

Options disponibles:
most_similar,
blocklisted_or_approved
Exemple:

"most_similar"

rotate_image
boolean
défaut:false

Lorsque la valeur est true, le service applique des rotations de 90 degrés à l'image fournie et utilise l'orientation qui produit la meilleure détection faciale. Utile lorsque l'orientation EXIF est manquante. Ajoute de la latence.

Exemple:

false

save_api_request
boolean
défaut:true

Lorsque la valeur est true (par défaut), conserve l'appel sous forme de session de type API, émet un webhook status.updated, pré-signe les valeurs match_image_url et inscrit le visage recherché dans votre index de Recherche faciale (les inscriptions à la Recherche faciale sont exclues des recherches futures). Lorsque la valeur est false, la recherche est ponctuelle — aucune session n'est stockée et le visage n'est pas inscrit.

Exemple:

true

vendor_data
string

Identifiant opaque optionnel (votre identifiant d'utilisateur, e-mail, UUID…) stocké sur la session persistée et renvoyé. Il n'exclut pas les visages du même utilisateur des résultats de recherche.

Exemple:

"user-123"

metadata
object

Objet JSON optionnel stocké avec la session (lorsque save_api_request=true) et renvoyé. Dans les requêtes multipart, envoyez-le sous forme de champ textuel encodé en JSON — il est analysé sous forme d'objet.

Exemple:

Réponse

Recherche faciale terminée. face_search.matches contient jusqu'à 5 visages similaires classés par similarité ; un tableau vide signifie qu'aucun visage enregistré n'a dépassé le seuil minimal de similarité. status est Declined uniquement en cas de correspondance avec une liste de blocage — les correspondances en doublon seules renvoient Approved, inspectez donc matches et warnings, pas seulement status. Lorsque save_api_request=true, request_id est l'identifiant de la session conservée. Chaque correspondance contient source (session, imported, list_entry ou retained_template), vendor_user_id et biometric_template_id ; une correspondance retained_template provient d'un gabarit biométrique sans image conservé après la suppression de la session source et présente des champs de session, match_image_url et user_details à null.

request_id
string<uuid>

Identifiant de session persistante lorsque save_api_request=true (utilisable avec GET /v3/session/{sessionId}/decision/) ; sinon un UUID de corrélation temporaire.

vendor_data
string | null

Écho des vendor_data que vous avez envoyées, ou null.

metadata
object | null

Écho de l'objet metadata que vous avez envoyé, ou null.

created_at
string<date-time>

Horodatage ISO 8601 (UTC) du moment où la réponse a été générée, ex. 2026-06-12T01:04:42.763237+00:00.

Dernière modification le 7 novembre 2026