> ## 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.

# Biométrie : recherche faciale et liste de blocage

> Découvrez comment Didit associe la biométrie faciale aux entités utilisateurs : recherche 1:N, détection des doublons, liste de blocage et import manuel.



Prompt de biométrie faciale
        Copier le prompt dans le presse-papiers



      
      

\<pre>

\````# Goal — search, blocklist, and act on User face biometrics

Faces are captured automatically during liveness inside a verification session, and can also be uploaded to an existing User profile when you are migrating users from another provider. You interact with biometrics through three action surfaces: **profile face upload** (attach an imported face to a User), **face search** (find a user by face), and the **Lists API** (blocklist a face so future sessions are auto-declined).

\## 1) Upload a face to an imported User profile

Use this when you already created or imported a User with `vendor_data` and have a trusted face image from your previous provider.

\```bash
\# 1. Get the Didit internal User id from vendor_data
curl https://verification.didit.me/v3/users/user-42/ \
-H "x-api-key: $DIDIT_API_KEY"

\# 2. Upload a base64-encoded face to that profile
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "comment": "Imported from previous KYC provider"}'
\```

Limits: max 5 faces per User, max 2 MB per image, and the image must contain a detectable face. This enrolls the face for profile evidence and future duplicate/face-search matching. It does not blocklist the face.

\## 2) Face search — 1:N

Use to detect duplicate accounts, identify a face from a CCTV frame, or recognise a returning customer before running new KYC.

\```bash
curl -X POST https://verification.didit.me/v3/face-search/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "user_image=@./selfie.jpg"
\```

Response includes match candidates with similarity scores. Wire your workflow (in the console) to auto-decline / flag / warn on duplicate hits, or call this endpoint directly from your backend before creating a session.

\## 3) Face blocklist — block a user by face

To block a known bad actor going forward, upload their face to a **face-type list** in your application. Any future session whose liveness selfie matches the embedding is auto-declined.

\```bash
\# Upload a face directly to a face-type list (no session needed)
curl -X POST https://verification.didit.me/v3/lists/$LIST_UUID/entries/face-upload/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "reason": "confirmed_fraud"}'
\```

If the face you want to block came from an existing session, use `POST /v3/lists/{list_uuid}/entries/` with `reference_session_id` instead — the backend extracts the biometric and links the entry back to the session.

Remove a face from the list with the Delete entry endpoint:

\```bash
curl -X DELETE https://verification.didit.me/v3/lists/$LIST_UUID/entries/$ENTRY_UUID/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

The Lists API supports face, document, email, phone, and IBAN list types. See /management-api/lists/overview for the full catalog.

\## 4) Blocklisting after a decline

Declining a session adds the face to no blocklist: the User stays `ACTIVE` and no list entry is written, so a later session with the same face is decided by the workflow's own rules, not by a list match. To block a declined subject, upload the face to a face-type list yourself with the Lists API call above — a decline never does it for you.

\## 5) Where the face lives on the User

\- `portrait_image` on the User entity is a signed URL to the latest approved selfie.
\- Manually uploaded profile faces are listed under the User profile face collection and returned by the profile face list endpoint.
\- `approved_duplicate_status` on each face is one of `NOT_DUPLICATED` / `DUPLICATED`.
\- Embeddings (numeric vectors) are stored separately from the image. Deleting a session deletes the image and, by default, the embedding. An application that opted in to biometric-template retention keeps one image-free template anchored to the User after the session is deleted; it has a finite expiry and is purged on User deletion, a privacy-erasure deletion (deletion_instruction: "privacy_erasure"), or an explicit purge via /v3/biometric-templates/ (see /management-api/biometric-templates/overview).

\## Failure modes

\- `400` from face-search / upload-face — image has no detectable face, multiple faces, or is too low-quality. Re-capture and retry.
\- `404` on Lists API — wrong `list_id` or list deleted.
\- `403` — your role lacks permission on the `lists` resource.
\- `429` — rate-limited.

\## Response shape

See /standalone-apis/face-search and /management-api/lists/upload-face for full schemas. Match objects use `similarity` (0–1) and reference the linked User `vendor_data` when known.

\## Sources of truth

\- /management-api/users/upload-face — attach an imported face to a User profile
\- /standalone-apis/face-search — face search request / response
\- /management-api/lists/upload-face — face blocklist upload
\- /management-api/lists/delete-entry — remove from list
\- /management-api/biometric-templates/overview — templates retained after session deletion
\- /core-technology/face-search/overview — search behaviour
\- /core-technology/liveness/overview — face capture during sessions
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

Coller dans

Les données biométriques faciales sont au cœur de chaque entité User. Didit capture un visage pendant la [détection du vivant](https://docs.didit.me/fr/core-technology/liveness/overview.md), génère un embedding vectoriel et le stocke pour quatre fonctionnalités en aval : **recherche faciale 1:N**, **détection des doublons**, **application de la liste de blocage** et **réauthentification biométrique**.> [!NOTE]
>
> Les visages enregistrés servent aussi de référence pour l'[Authentification biométrique](https://docs.didit.me/fr/core-technology/biometric-auth/overview.md) : créez une session d'authentification biométrique avec le `vendor_data` de l'utilisateur et omettez `portrait_image`, et Didit réutilise automatiquement le visage enregistré (d'abord le visage approuvé lors de la détection du vivant, puis la photo de la puce du passeport électronique, puis le portrait du document d'identité, et enfin un visage de profil enrôlé manuellement).## Comment les visages sont rattachés à un utilisateur**1. Capturé pendant la détection du vivant**Lorsqu'un utilisateur passe une session avec la détection du vivant activée, Didit capture un selfie, exécute une détection passive du vivant, extrait le plus grand visage et génère un embedding vectoriel pour la recherche.**2. Stocké sur le profil utilisateur**Le visage est lié à la session et à l'entité User parente. L'URL du portrait apparaît sur le profil utilisateur sous la forme `portrait_image`.**3. Indexé pour la recherche**L'embedding est ajouté à l'index de recherche. Les sessions suivantes peuvent effectuer des recherches 1:N dans cet index.## Recherche faciale (1:N)La recherche faciale vous permet de retrouver un utilisateur en téléversant une image et en la comparant à chaque visage enrôlé dans votre application.Cas d'usage :- **Détection des doublons** lors de l'onboarding : empêcher une même personne de créer deux comptes.
- **Recherche inversée** : identifier l'utilisateur derrière une image de vidéosurveillance ou une image utilisée dans une enquête pour fraude.
- **Reconnaissance des clients récurrents** : éviter le KYC pour un client récurrent.La recherche faciale s'exécute automatiquement pendant les nouvelles sessions lorsque votre workflow a la détection des doublons activée. Elle est aussi proposée comme API autonome :- `POST /v3/face-search/` : [recherche faciale autonome](https://docs.didit.me/fr/standalone-apis/face-search.md)## Détection des doublonsChaque nouveau visage peut être comparé aux visages enrôlés existants afin de repérer les doublons. Didit attribue à chaque visage un `approved_duplicate_status` :| Statut | Signification |
| - | - |
| `NOT_DUPLICATED` | Aucune correspondance trouvée au-dessus du seuil de similarité |
| `DUPLICATED` | Le visage correspond à un ou plusieurs visages d'une session déjà approuvée |Les workflows peuvent être configurés pour :- **Refuser** automatiquement les sessions signalées comme doublons.
- **Signaler pour examen** : transférer à un analyste humain.
- **Alerter uniquement** : autoriser la session tout en ajoutant un tag de risque.Configurez cette option dans la console, à *Workflows → \[votre workflow] → Face Match / Liveness → Duplicate detection*.## Liste de blocage des visagesLe refus d'une session n'ajoute pas le visage à une liste de blocage. Pour rejeter les futures sessions présentant le même visage, ajoutez-le vous-même à la liste de blocage : depuis la [page Liste de blocage](https://docs.didit.me/fr/console/blocklist-users.md) ou avec l'[API Lists](https://docs.didit.me/fr/management-api/lists/overview.md). Une nouvelle session dont le selfie de détection du vivant correspond à cette entrée est refusée automatiquement.## Importer un visage dans le profil d'un utilisateurSi vous migrez depuis un autre fournisseur KYC, vous pouvez créer d'abord l'utilisateur, puis y rattacher une image de visage de confiance. L'utilisateur reste identifié par votre `vendor_data`, mais l'endpoint de téléversement de visage utilise l'identifiant interne de l'utilisateur chez Didit (`didit_internal_id`) afin que la cible soit sans ambiguïté.**1. Créer ou récupérer l'utilisateur**Appelez [`POST /v3/users/create/`](https://docs.didit.me/fr/management-api/users/create) avec votre `vendor_data` stable, ou appelez `GET /v3/users/{vendor_data}/` si l'utilisateur existe déjà.**2. Lire didit\_internal\_id**La réponse de l'utilisateur contient `didit_internal_id`. Continuez à utiliser `vendor_data` dans votre propre système ; réservez `didit_internal_id` aux endpoints de rattachement de profil.**3. Téléverser le visage**Appelez [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](https://docs.didit.me/fr/management-api/users/upload-face) avec une image de visage encodée en base64.```bash theme={null}
# 1. Create or retrieve the User keyed by your vendor_data
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "previous_provider": "legacy-kyc-vendor" }
  }'

# Response includes:
# { "didit_internal_id": "11111111-2222-3333-4444-555555555555", ... }

# 2. Upload the imported face to the User profile
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/11111111-2222-3333-4444-555555555555/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'
```Les visages de profil importés sont enrôlés dans le même index de visages que celui utilisé pour la détection des doublons et la recherche faciale. Ils ne sont pas automatiquement ajoutés à une liste de blocage. Pour bloquer un acteur malveillant connu, téléversez plutôt le visage dans une liste de type visage.> [!WARNING]
>
> Ne téléversez que des visages que vous êtes autorisé à traiter selon votre propre notice de confidentialité et votre accord de migration. Ne conservez les identifiants du fournisseur source dans `metadata` ou `comment` que s'ils peuvent être exposés sans risque à vos opérateurs de conformité.### Fonctionnement du blocage| Déclencheur | Action |
| - | - |
| Session `DECLINED` | Aucun ajout à une liste de blocage ; l'utilisateur reste `ACTIVE` |
| Un analyste ajoute manuellement un visage à la liste de blocage depuis la console | Visage ajouté, statut de l'utilisateur mis à jour selon la politique |
| Ajout programmatique via l'API Lists | Téléverser l'image du visage dans une liste de blocage de type visage |### Téléverser un visage dans la liste de blocagePour bloquer un utilisateur par son visage de façon programmatique, téléversez l'image du visage dans une liste de blocage de type visage via l'endpoint dédié [Téléverser un visage dans une liste](https://docs.didit.me/fr/management-api/lists/upload-face.md). Didit extrait l'embedding biométrique et l'insère dans l'index correspondant : toute future session dont le selfie de détection du vivant correspond est refusée automatiquement.> [!NOTE]
>
> Le téléversement de visage de profil et le téléversement dans la liste de blocage sont deux opérations différentes. Utilisez le téléversement de profil pour rattacher un visage importé de confiance à un utilisateur, à des fins de preuve, de détection des doublons et de recherche faciale. Utilisez l'[API Lists](https://docs.didit.me/fr/management-api/lists/overview.md) pour bloquer un visage afin que les futures sessions correspondantes soient rejetées.### Retirer un visage de la liste de blocageRetirez l'entrée depuis la console, à *Blocklist → Faces → row actions → Remove*, ou utilisez l'endpoint [Supprimer l'entrée](https://docs.didit.me/fr/management-api/lists/delete-entry.md).## Gabarits biométriques conservés après suppression d'une sessionLa suppression d'une session supprime l'image du visage et, par défaut, l'embedding facial. La personne n'apparaît donc plus dans la détection des doublons ni dans la recherche faciale. Si vous supprimez des sessions peu après leur approbation mais devez encore détecter les inscriptions répétées, activez la [conservation des gabarits biométriques](https://docs.didit.me/fr/console/data-retention.md#conservation-des-gabarits-biométriques) sur l'application, ou envoyez `retain_face_embeddings: true` dans l'appel de suppression.Didit supprime ensuite la session et l'ensemble de ses données comme d'habitude, et conserve un gabarit biométrique facial distinct, géré séparément et sans image, rattaché à l'utilisateur :- Il contient uniquement le gabarit numérique du visage et les métadonnées de conservation. Il ne contient jamais l'image du visage, la vidéo de détection du vivant, les données du document, les champs d'identité extraits, la décision ni l'identifiant de la session supprimée.
- Il participe à la détection des doublons, à la recherche faciale, à l'authentification biométrique et à vos listes de visages exactement comme un visage issu d'une session active. Les correspondances sont signalées avec `source: "retained_template"`, le `vendor_user_id` et les `vendor_data` de l'utilisateur, ainsi qu'un `biometric_template_id`.
- Il s'agit de données biométriques dotées d'une valeur `expires_at` définie. Il est purgé lorsque l'utilisateur est supprimé, lorsqu'une session de cet utilisateur est supprimée avec `deletion_instruction: "privacy_erasure"`, à son expiration, ou lorsque vous le purgez dans **Lists → Gabarits biométriques** ou via l'[API des gabarits biométriques](https://docs.didit.me/fr/management-api/biometric-templates/overview.md).
- Une session créée sans `vendor_data` n'a aucun utilisateur auquel rattacher un gabarit. Sa suppression renvoie `ineligible_no_vendor_user`, et l'embedding est supprimé avec la session.
- Les gabarits conservés ne sont jamais placés sur liste de blocage. Une entrée de liste de blocage créée à partir de la session supprimée conserve sa propre entrée biométrique indépendante et son propre cycle de vie.Les gabarits rattachés à un utilisateur apparaissent sur le profil utilisateur, sous **Gabarits biométriques**, avec une action de purge.## Résumé du cycle de vie des visages```mermaid theme={null}
stateDiagram-v2
    [*] --> Enrolled: Face captured during liveness
    Enrolled --> Approved: Session approved
    Enrolled --> Declined: Session declined
    Enrolled --> Duplicated: 1:N search finds match
    Duplicated --> Approved: Allowed by workflow
    Duplicated --> Declined: Rejected by workflow
    Enrolled --> Blocklisted: Face uploaded to a face-type list
    Declined --> [*]: Nothing blocklisted
    Blocklisted --> [*]: Manually removed
    Approved --> [*]: Session deleted (default)
    Approved --> RetainedTemplate: Session deleted with retention enabled
    RetainedTemplate --> [*]: Expiry, User deletion, privacy erasure, or purge
```## Téléverser un visage depuis la consoleLes opérateurs de conformité peuvent téléverser des visages manuellement :1) Accédez à *Users → \[user] → Actions → Upload face*.
2) Sélectionnez une image ; Didit extrait le plus grand visage et enregistre un nouvel enregistrement de visage lié à l'utilisateur.
3) Le visage est enregistré pour les preuves de profil, la détection des doublons et la recherche faciale. Utilisez la zone de liste de blocage lorsque l'objectif est de rejeter les futures sessions correspondantes.Cette fonctionnalité est utile dans les cas suivants :- Vous disposez d'un portrait connu d'un client, vérifié par un canal hors ligne.
- Vous souhaitez alimenter une liste de blocage avec des acteurs malveillants connus issus de votre base de données de fraude.## Confidentialité et conservation- Les embeddings faciaux sont des vecteurs numériques, et non des images. Les images elles-mêmes sont stockées dans un stockage objet chiffré, avec un accès par URL signée. Un embedding facial constitue une donnée biométrique.
- La conservation suit la politique de [conservation des données](https://docs.didit.me/fr/console/data-retention.md) de votre application. Les gabarits biométriques conservés suivent la période de [conservation des gabarits biométriques](https://docs.didit.me/fr/console/data-retention.md#conservation-des-gabarits-biométriques), plus stricte et finie.
- La suppression d'une session supprime l'image et, par défaut, l'embedding. Si votre application a activé la conservation des gabarits biométriques, la suppression d'une session conserve un gabarit sans image jusqu'à son expiration ou sa purge.
- Pour une demande de droit à l'effacement au titre du RGPD ou du CCPA, supprimez les sessions de la personne avec `deletion_instruction: "privacy_erasure"`, ou supprimez l'utilisateur : dans les deux cas, tous les gabarits conservés sont également purgés. Les entrées de liste de blocage facial que vous gérez restent en place jusqu'à ce que vous les retiriez.## Étapes suivantes> [card] [Recherche faciale](https://docs.didit.me/fr/core-technology/face-search/overview.md)
>
> Fonctionnement de la recherche faciale 1:N.> [card] [Détection du vivant](https://docs.didit.me/fr/core-technology/liveness/overview.md)
>
> Détection du vivant qui capture le visage.> [card] [API de liste de blocage](https://docs.didit.me/fr/management-api/lists/upload-face.md)
>
> Téléverser un visage dans une liste de blocage.> [card] [Gabarits biométriques](https://docs.didit.me/fr/management-api/biometric-templates/overview.md)
>
> Gabarits conservés après suppression de la session.> [card] [Liste de blocage des utilisateurs](https://docs.didit.me/fr/entities/users/blocklist.md)
>
> Fonctionnement de la mise sur liste de blocage d'un utilisateur.


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