> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Recherche faciale 1:N : API de détection des doublons

> Repérez doublons et fraudeurs avec Didit grâce à la recherche faciale 1:N. Gratuite avec la vérification d'identité, réponse en moins de 2 s.

La Recherche faciale est une fonctionnalité puissante qui vous permet de rechercher un visage spécifique parmi l'ensemble de vos sessions de vérification d'identité approuvées. Cette capacité aide à identifier les comptes en double, à prévenir la fraude et à renforcer vos mesures de sécurité.

Prompt d'intégration de la Recherche faciale
        Copier le prompt dans le presse-papiers



      
      

\<pre>

\````# Goal
Integrate Didit Face Search (1:N — search a face across your enrolled users + blocklist) into your app.

\# Delivery mode
Face Search is a **standalone API**. It runs against the face index your application has enrolled through prior verifications (sessions with save_api_request=true or Passive Liveness with save_api_request=true), faces uploaded to User profiles, your face lists, and any image-free biometric templates the application retained after deleting sessions (opt-in, see /management-api/biometric-templates/overview). There is no separate Face Search workflow feature.

POST https://verification.didit.me/v3/face-search/
multipart/form-data — x-api-key: YOUR_API_KEY

Required: `user_image` (jpg/jpeg/png/tiff/webp, max 5 MB; PDFs not accepted). The image must contain at least one detectable face (largest bbox wins when multiple).

Optional: `search_type` = "most_similar" (default — dedupe / returning-user) | "blocklisted_or_approved" (blocklist screening).

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/face-search/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'search_type=most_similar' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```

\# Response shape (singular)
Unlike most features, Face Search returns a **singular** `face_search` object — not a plural array:
\{ request_id, face_search: { status, total_matches, matches: [{ session_id, session_number, similarity_percentage, source, vendor_data, vendor_user_id, biometric_template_id, verification_date, user_details, match_image_url, status, is_blocklisted, is_allowlisted, api_service }], user_image: {entities}, warnings: [...] } }

match.source is "session", "imported", "list_entry", or "retained_template". A retained_template hit comes from an image-free biometric template kept after the source session was deleted: session_id, session_number, status, api_service, match_image_url, and user_details are null; vendor_data and vendor_user_id identify the User; biometric_template_id is the template you can inspect or purge via /v3/biometric-templates/{id}/.

\`status` is "Declined" only when at least one blocklist match is found. Pure duplicate matches return "Approved" (informational) — apply your own dedupe policy in app logic.

\# Warnings
Face Search emits risk codes from the LogWarningChoices.FACEMATCH bucket plus blocklist/duplicate semantics:
FACE_IN_BLOCKLIST, POSSIBLE_FACE_IN_BLOCKLIST, DUPLICATED_FACE, POSSIBLE_DUPLICATED_FACE, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/face-search/warnings-face-search.

\# Failure modes to handle
\- HTTP 400 — no face detected in user_image. Ask the user to retake.
\- HTTP 403 — out of credits.
\- status="Declined" with FACE_IN_BLOCKLIST — definitive blocklist hit; reject.
\- POSSIBLE_FACE_IN_BLOCKLIST — borderline match below the hard threshold; route to manual review.
\- DUPLICATED_FACE — user already verified under a different vendor_data; merge or block according to policy.

\# See also
\- Canonical schema: /reference/data-models#face-search
\- Per-feature report: /core-technology/face-search/report-face-search
\- Risk catalogue: /core-technology/face-search/warnings-face-search
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

Coller dans

La leçon de l'Academy sur la lecture d'un résultat de vérification aborde la recherche faciale et les listes de blocage à 6:53.[Recherche faciale et listes de blocage — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=413\&rel=0\&playsinline=1)![Flux de recherche faciale 1:N Didit intégré à la détection du vivant pour la détection des doublons et des correspondances avec la liste de blocage](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/face-search-liveness.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=0cb5738f8ceaae7891cf13631485c400)## Intégration automatique de la Recherche faciale> La Recherche faciale est automatiquement effectuée lors des contrôles de détection du vivant dans les sessions de vérification afin de détecter les utilisateurs en double et de vérifier la présence de visages sur liste de blocage.### Détection automatique des doublonsLorsqu'un utilisateur effectue un contrôle de détection du vivant pendant la vérification d'identité :- Ses données biométriques faciales sont automatiquement comparées à celles de tous les utilisateurs précédemment vérifiés
- Le système identifie les comptes potentiellement en double en fonction de la similarité faciale
- Les correspondances sont signalées conformément à vos seuils de similarité configurés
- Vous pouvez examiner les utilisateurs potentiellement en double et prendre des mesures### Intégration de la liste de blocageLa Recherche faciale s'intègre parfaitement avec la [fonctionnalité de liste de blocage](https://docs.didit.me/fr/management-api/lists/overview.md) :- Pendant la vérification, les visages sont automatiquement vérifiés par rapport à votre liste de blocage
- Si une correspondance avec un visage sur liste de blocage est trouvée, la vérification est automatiquement refusée
- Cela empêche les utilisateurs problématiques précédemment identifiés de créer de nouveaux comptes
- Permet de préserver l'intégrité de votre processus de vérification### Le selfie pris pendant la capture du documentPendant que l'utilisateur prend en photo son document, la caméra frontale prend un selfie de lui (Silent Capture). Chaque fois que le document est évalué, ce selfie passe par la même recherche 1:N que le selfie de détection du vivant :- Il est comparé à votre liste de blocage de visages et aux utilisateurs déjà approuvés dans votre application, avec les mêmes seuils de similarité et le même ordre de priorité que la recherche de détection du vivant.
- Une correspondance avec la liste de blocage déclenche `FRONT_CAMERA_FACE_IN_BLOCKLIST` (toujours Refusé) ou `POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST` (toujours en cours d'examen). Une correspondance avec un utilisateur approuvé déclenche `FRONT_CAMERA_DUPLICATED_FACE` ou `POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE`, ainsi que `FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH` lorsque cet utilisateur approuvé a été vérifié sous un nom différent, et `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` lorsque la pièce d'identité de cet utilisateur présente une date de naissance différente. Voir les [avertissements de vérification d'identité](https://docs.didit.me/fr/core-technology/id-verification/warnings-id-verification.md).
- Les correspondances sont répertoriées dans les détails de la session, sur la carte de vérification d'identité, et renvoyées dans `id_verifications[].document_selfie_face_matches` de la [décision de la session](https://docs.didit.me/fr/sessions-api/retrieve-session.md). Elles utilisent le même format d'entrée que `liveness_checks[].matches`. Le champ est `null` pour les sessions plus anciennes ou lorsque la recherche n'a pas été exécutée, et un tableau vide lorsqu'elle a été exécutée et n'a rien trouvé. `match_image_url` est une URL présignée qui expire.
- Seul le plus grand visage du selfie est utilisé, et uniquement lorsque le détecteur a un score de confiance suffisant quant au fait qu'il s'agit d'un visage. Un selfie par document est analysé : celui du recto, ou celui du verso lorsque le selfie du recto ne présente aucun visage net.
- Le selfie est uniquement comparé. Son gabarit biométrique n'est jamais stocké, de sorte que les sessions ultérieures ne sont jamais comparées à celui-ci. Pour bannir une personne à partir du selfie d'une session, ajoutez-le à votre liste de blocage de visages depuis la page de la session.Cette recherche dispose de son propre bouton d'activation et de ses propres actions sur l'étape **Vérification d'identité**, dans l'onglet **Règles** de l'étape (**Recherche faciale par capture silencieuse**), ou avec `document_selfie_face_search_enabled` et les actions `document_selfie_duplicated_face_*` dans la [configuration des fonctionnalités du workflow](https://docs.didit.me/fr/management-api/workflows/feature-configs.md#vérification-d’identité-ocr). Elle est activée par défaut ; l'action en cas de visage dupliqué est définie par défaut sur Approuver (l'avertissement est toujours signalé) et les vérifications croisées du nom et du document sont définies par défaut sur Examen, tout comme leurs équivalents pour la détection du vivant. La recherche nécessite le selfie, elle ne s'exécute donc que lorsque Silent Capture est activé. Désactiver Recherche faciale sur l'étape Détection du vivant désactive également cette recherche : cette désactivation concerne le visage de la personne, elle s'applique donc à tous les selfies de la session.### La règle de discordance de documentLa règle de **discordance de document** (`DUPLICATED_FACE_DOCUMENT_MISMATCH` pour le selfie de détection du vivant, `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` pour Silent Capture) signale un visage dupliqué uniquement lorsque la pièce d'identité de l'utilisateur correspondant présente une date de naissance différente.
Une même personne présentant un document différent, par exemple un passeport après une carte d'identité, n'est pas signalée.
Un document renouvelé n'est pas non plus signalé.
Deux sessions qui partagent le même numéro de document provenant du même pays ne sont jamais signalées.### Désactiver la Recherche faciale automatiqueLa Recherche faciale automatique est activée par défaut pour chaque étape Détection du vivant. Si vos exigences en matière de confidentialité l'imposent, vous pouvez la désactiver par workflow depuis l'onglet **Règles** de l'étape **Détection du vivant** dans la Business Console (mode simple et avancé), ou avec `face_search_enabled: false` sur le nœud `LIVENESS` ou `AGE_ESTIMATION` dans la [configuration des fonctionnalités du workflow](https://docs.didit.me/fr/management-api/workflows/feature-configs.md#détection-du-vivant).Lorsque cette option est désactivée, le selfie de détection du vivant est toujours évalué au titre de la détection du vivant et comparé en 1:1 au portrait du document dans la Correspondance faciale, mais il n'atteint jamais l'index des visages :- Aucune recherche n'est exécutée, la session n'obtient donc aucun verdict de doublon, de liste de blocage ou de liste d'autorisation et son champ `liveness_checks[].matches` reste vide. Les règles **Visage dupliqué**, **discordance de nom**, **discordance de document** et relatives aux visages inter-organisations n'ont aucun élément sur lequel intervenir et sont masquées dans la Console.
- Aucun gabarit biométrique n'est stocké pour le selfie, de sorte que les sessions ultérieures ne peuvent pas être comparées à celle-ci et il n'y a rien à conserver pour la [conservation des gabarits biométriques](https://docs.didit.me/fr/console/data-retention.md#conservation-des-gabarits-biométriques) après la suppression de la session.
- Le selfie n'est pas utilisé pour résoudre une personne biométrique partagée pour les contrôles inter-organisations.
- Le selfie pris pendant la capture du document n'est pas non plus analysé (aucun risque lié à la liste de blocage ou de doublon `FRONT_CAMERA_*`) : la désactivation couvre chaque selfie de la session. Le bouton propre à l'étape Vérification d'identité (voir ci-dessus) peut également désactiver cette recherche de manière autonome.**À quelle étape appartient le bouton d'activation.** Le bouton se trouve sur l'étape qui capture le selfie, de sorte qu'une étape de **Détection du vivant** ou d'**Estimation de l'âge** gère son propre paramètre. Une étape **Correspondance faciale** n'en possède aucun en propre : lorsqu'un utilisateur reprend le selfie à cet endroit – après que vous lui avez demandé de soumettre à nouveau cette étape, par exemple –, la nouvelle capture suit le paramètre de l'étape Détection du vivant, de sorte qu'une désactivation maintient également le nouveau selfie hors de l'index. Si votre workflow se divise en plusieurs étapes Détection du vivant, le paramètre qui s'applique est celui de la branche par laquelle la session est réellement passée, et la lecture faciale inter-organisations suit cette même étape.Les workflows existants conservent le comportement actuel jusqu'à ce que vous le désactiviez. La modification s'applique aux sessions démarrées après l'enregistrement du workflow ; les gabarits stockés lors des sessions antérieures restent dans l'index jusqu'à ce que ces sessions soient supprimées ou purgées. Cette option n'affecte pas l'[API de Recherche faciale](https://docs.didit.me/fr/standalone-apis/face-search.md) autonome, que vous appelez explicitement.> [!WARNING]
>
> Votre liste de blocage des visages est appliquée lors de la vérification par cette même recherche 1:N. Si la Recherche faciale est désactivée sur l'étape de Détection du vivant, une personne figurant sur liste de blocage ne sera interceptée ni à cette étape, ni par le selfie pris lors de la capture du document ; si la Recherche faciale par capture silencieuse est désactivée sur l'étape de Vérification d'identité, elle ne le sera pas non plus par ce selfie.### Accès à l'APILa fonctionnalité de Recherche faciale est également disponible via notre [API](https://docs.didit.me/fr/standalone-apis/face-search.md), vous permettant de :- Soumettre des recherches faciales par voie programmatique
- Intégrer des fonctionnalités de correspondance faciale au sein de vos propres applications
- Concevoir des workflows personnalisés de détection des fraudes
- Créer des systèmes automatisés pour la détection des doublons## Fonctionnalités clés- **Haute précision** : des algorithmes biométriques avancés fournissent des résultats de correspondance fiables
- **Seuils configurables** : personnalisez la sensibilité de correspondance selon votre tolérance au risque
- **Analyse exhaustive** : effectuez des recherches parmi l'ensemble de vos utilisateurs vérifiés
- **Résultats rapides** : traitez les recherches rapidement, même avec d'importantes bases de données d'utilisateurs
- **Respect de la vie privée** : la mise en correspondance utilise des gabarits faciaux numériques cantonnés à votre application ; l'index ne quitte jamais votre environnement dédié### Seuils configurablesVous pouvez personnaliser la sensibilité de recherche en définissant différents seuils pour les scores de similarité :> [!NOTE]
>
> Ces seuils peuvent être ajustés en fonction de votre tolérance au risque et de vos exigences de sécurité.## Comment cela fonctionne**1. Extraction faciale**Lorsqu'une recherche est initiée, le système traite l'image de référence :| Processus | Description |
| - | - |
| **Extraction des caractéristiques** | Isole les caractéristiques faciales à partir de l'image de référence |
| **Normalisation** | Standardise les données faciales pour une comparaison cohérente |
| **Validation de la qualité** | Vérifie la qualité de l'image et la netteté du visage |
| **Encodage vectoriel** | Crée une représentation vectorielle mathématique du visage |**2. Algorithme de comparaison**Le système effectue des recherches sur l'ensemble de votre base de données de sessions vérifiées :- Compare le vecteur facial de référence à **chaque visage enregistré dans votre application** : visages de session, visages téléversés dans les profils User, vos listes de visages et tous les gabarits biométriques conservés
- Utilise une architecture de réseau neuronal avancée optimisée pour la rapidité et la précision
- Prend en charge deux modes de recherche : **les plus similaires** (liste classée) et **placés sur liste de blocage ou approuvés** (filtrés par statut)
- Traite rapidement de grandes bases de données grâce à une indexation optimisée**3. Calcul du score de similarité**Pour chaque comparaison, un pourcentage de similarité est généré :| Plage de score | Interprétation |
| :-: | - |
| **90%+** | Correspondance forte — très probablement la même personne |
| **70–89%** | Correspondance possible — peut nécessiter un examen manuel |
| **Moins de 70%** | Individus probablement distincts |Vos seuils de correspondance configurés déterminent les résultats qui sont signalés.**4. Restitution des résultats**Le système renvoie un ensemble complet de résultats :- **Liste classée** des correspondances potentielles triées par score de similarité
- **Détails de la correspondance**, y compris l'ID de session, la date de vérification et les données du fournisseur
- **Pourcentage de similarité** pour chaque correspondance
- **Images correspondantes** disponibles pour un examen visuel
- **Statut sur liste de blocage** indiquant si le visage correspondant figure sur liste de blocage## Sessions supprimées et gabarits biométriques conservésLa suppression d'une session supprime par défaut son embedding facial, de sorte que la personne disparaît de l'index et peut effectuer une nouvelle vérification sans signalement de doublon. Les applications qui suppriment les sessions peu après leur approbation mais doivent toujours intercepter les réinscriptions peuvent activer la [conservation des gabarits biométriques](https://docs.didit.me/fr/console/data-retention.md#conservation-des-gabarits-biométriques). Didit conserve alors un gabarit biométrique sans image, rattaché à l'utilisateur après la suppression de la session, et ce gabarit participe à la Recherche faciale et à la détection automatique des doublons exactement comme le visage d'une session active.Une correspondance sur un gabarit conservé est signalée avec `source: "retained_template"`, les champs `vendor_user_id` et `vendor_data` de l'utilisateur associé, ainsi qu'un `biometric_template_id`. Elle ne comporte aucun identifiant de session, image de correspondance, détail d'identité ou statut de session, car la session à l'origine du visage n'existe plus. Les gabarits conservés ne sont jamais placés sur liste de blocage ; les entrées de la liste de blocage des visages conservent leur propre enregistrement biométrique indépendant.Le gabarit est conservé jusqu'à sa date d'expiration prévue, la suppression de l'utilisateur, une demande d'effacement au titre de la protection de la vie privée, ou une purge explicite via l'[API des gabarits biométriques](https://docs.didit.me/fr/management-api/biometric-templates/overview.md) ou **Lists → Biometric templates** dans la Console.## Pourcentage de similaritéLe pourcentage de similarité est l'indicateur principal utilisé pour déterminer les correspondances potentielles :- **Pourcentage élevé (généralement 90% et plus)** : indique une forte probabilité que les visages appartiennent à la même personne.
- **Pourcentage moyen (70-89%)** : suggère des correspondances possibles pouvant nécessiter un examen plus approfondi.
- **Pourcentage faible (inférieur à 70%)** : indique probablement des individus distincts.Le seuil exact définissant une « correspondance » peut être configuré en fonction de vos exigences de sécurité. L'augmentation du seuil réduit les faux positifs mais peut accroître les faux négatifs.## Cas d'usage- **Prévention de la fraude** : identifiez les utilisateurs tentant de créer plusieurs comptes
- **KYC renforcé** : ajoutez une couche de vérification supplémentaire à votre processus de KYC
- **Conformité réglementaire** : répondez aux exigences en matière de détection des comptes en doublon
- **Contrôle d'accès** : vérifiez l'authenticité des utilisateurs pour les zones à sécurité renforcée
- **Forces de l'ordre** : aidez les organismes autorisés à identifier des personnes d'intérêt


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.