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

# API des gabarits biométriques

> Gérez avec Didit les gabarits biométriques faciaux sans image conservés après suppression de session : lister, filtrer, inspecter, purger.



Invite de l'API des gabarits biométriques
        Copier le prompt dans le presse-papiers



      
      

\<pre>

\`Manage the biometric templates my Didit application retains after deleting verification sessions.

What a biometric template is:
When an application opts in (face_retention_policy: "retain_until_user_deleted", or retain_face_embeddings: true on a delete call), deleting a KYC session deletes the session and all of its data but keeps ONE image-free face biometric template anchored to the session's User. The template keeps duplicate-face, multi-account, biometric-authentication, and list matching working for that person. It contains the numeric face template plus retention metadata only — never the face image, liveness video, document data, extracted identity fields, the decision, or the deleted session's id. It is biometric data: not anonymous, not transient, and not deleted with the session. It has a finite expires_at.

Endpoints (base https://verification.didit.me, header x-api-key: YOUR_API_KEY; API keys only — Console user tokens get 403):
\- GET  /v3/biometric-templates/            — paginated list (limit/offset). Filters: vendor_data (substring, case-insensitive), vendor_user_uuid, status, source_type, retained_from, retained_to (ISO 8601), ordering (retained_at | -retained_at | expires_at | -expires_at; default -retained_at). Purged templates are not listed.
\- GET  /v3/biometric-templates/count/      — {"count": n} with the same filters.
\- GET  /v3/biometric-templates/{uuid}/     — one template.
\- DELETE /v3/biometric-templates/{uuid}/   — purge one template. 200 {"uuid": "...", "outcome": "purged" | "already_purged"}.
\- POST /v3/biometric-templates/delete/     — bulk purge. Body: {"template_uuids": ["..."]} OR {"delete_all": true} plus optional filters (vendor_data, vendor_user_uuid, status, source_type, retained_from, retained_to) that narrow delete_all. 200 {"results": [{"uuid": "...", "outcome": "purged" | "already_purged"}]}.

Template object:
\{
"uuid": "<template id>",
"vendor_user_uuid": "<User id>",
"vendor_data": "<the User's current vendor_data, resolved live>",
"source_type": "session_delete" | "automatic_retention" | "backfill",
"provenance_reference": "<opaque UUID, not the deleted session id>",
"retention_policy": "delete_with_session" | "retain_until_user_deleted",
"retention_override": true | false | null,
"retained_at": "<ISO 8601>",
"expires_at": "<ISO 8601>",
"retained_by": "<principal id: application UUID for API keys, Console member id, or service:...>",
"retained_by_type": "API_KEY" | "CONSOLE_USER" | "SYSTEM",
"instruction_class": "operational_session_delete" | "privacy_erasure",
"instruction_source": "api" | "console" | "automatic_retention" | "backfill" | "privacy_erasure" | "explicit_template_purge" | "vendor_user_delete" | "expiry" | "reconciliation" | "migration" | "system",
"instruction_id": "<your instruction_id or a Didit-generated one>",
"held_out_of_use": false,
"status": "pending" | "active" | "expired" | "held_out_of_use" | "purge_pending" | "purge_failed" | "purged",
"purged_at": null | "<ISO 8601>"
}
Only status "active" templates that are not held_out_of_use, not past expires_at, and whose User still exists take part in matching.

Purge points (all remove the template from matching and delete the stored template):
\- DELETE /v3/biometric-templates/{uuid}/ or POST /v3/biometric-templates/delete/
\- POST /v3/users/delete/ for the owning User
\- any session deletion for that User sent with deletion_instruction: "privacy_erasure"
\- automatic expiry at expires_at
Switching the application policy back to delete_with_session does NOT purge existing templates — purge them explicitly.

Failure modes:
\- 400 — {"template_uuids": ["This field is required unless delete_all is true."]} on bulk purge without a selector; invalid filter values.
\- 403 — {"detail": "You do not have permission to perform this action."} (Console user token, or key not allowed).
\- 404 — {"detail": "Biometric template not found."} on GET of an unknown or purged template.
\- 503 — {"detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable."} The template moves to status purge_failed and is already excluded from matching; repeat the purge.

Every retain and purge attempt, including failures, is recorded on Didit's audit trail with the acting principal, instruction class, instruction_source, instruction_id, and outcome.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`

\</pre>



      
      

Coller dans

Par défaut, la suppression d'une session de vérification supprime aussi l'embedding facial utilisé par la [Recherche faciale 1:N](https://docs.didit.me/fr/core-technology/face-search/overview.md) et par la détection de doublons pour cette session. Les applications qui ont besoin que la détection de doublons continue de fonctionner après la suppression d'une session peuvent activer la **conservation des gabarits biométriques**. Didit supprime alors 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, sans aucune image, et rattaché à l'[utilisateur](https://docs.didit.me/fr/entities/users/overview.md) de la session.L'API des gabarits biométriques vous permet de voir exactement quels gabarits votre application détient, pourquoi, jusqu'à quand, et de les purger à tout moment. Chaque gabarit est aussi visible dans la Business Console, sous **Lists → Biometric templates**, ainsi que sur le profil de l'utilisateur propriétaire.> [!WARNING]
>
> Un gabarit biométrique conservé est une donnée biométrique. Il n'est pas anonyme, il n'est pas temporaire, et il n'est pas supprimé avec la session. Il reste en place jusqu'à sa date d'expiration programmée, jusqu'à une échéance légale applicable plus tôt, jusqu'à la suppression de l'utilisateur, jusqu'à une demande d'effacement de données personnelles, ou jusqu'à une purge explicite. N'activez la conservation que si vos instructions en tant que responsable de traitement et votre notice de confidentialité la couvrent.## Comment un gabarit est créé| Déclencheur | `source_type` | D'où provient l'instruction |
| - | - | - |
| Vous supprimez une session sur une application ayant activé la conservation, ou envoyez `retain_face_embeddings: true` sur [Supprimer une session](https://docs.didit.me/fr/sessions-api/delete-session.md) ou [Supprimer des sessions par lot](https://docs.didit.me/fr/management-api/sessions/batch-delete.md) | `session_delete` | `instruction_source: api` ou `console` |
| La [fenêtre de conservation des données](https://docs.didit.me/fr/console/data-retention.md) générale de votre application fait expirer une session sur une application ayant activé la conservation | `automatic_retention` | `instruction_source: automatic_retention` |
| Un rattrapage exécuté par Didit que vous avez demandé pour les sessions supprimées avant votre adhésion | `backfill` | `instruction_source: backfill` |La conservation nécessite un ancrage à un utilisateur. Une session créée sans `vendor_data` n'a pas d'utilisateur associé, elle ne peut donc pas conserver de gabarit. La suppression renvoie `ineligible_no_vendor_user`, et l'embedding est supprimé avec la session.## Contenu d'un gabarit| Conservé | Jamais conservé |
| - | - |
| Le gabarit facial numérique utilisé pour la comparaison | L'image du visage, la vidéo de détection du vivant, les images de documents, les recadrages de portrait et tout autre média |
| Un nouvel `uuid` de gabarit généré aléatoirement et une `provenance_reference` opaque | L'id, le numéro, la décision, les champs d'identité extraits ou les payloads de fonctionnalités de la session supprimée |
| L'utilisateur propriétaire (`vendor_user_uuid`) ; `vendor_data` est résolu à partir de l'utilisateur lors de la lecture du gabarit, et n'est jamais copié | L'état de la liste de blocage, les correspondances antérieures, les étiquettes de fraude ou les revendications d'identité inter-organisations |
| `retained_at`, `expires_at`, `retention_policy`, `retention_override`, `instruction_class`, `instruction_source`, `instruction_id`, `retained_by`, `retained_by_type` | Les adresses e-mail des acteurs |Les gabarits sont cloisonnés par locataire et utilisés uniquement sur instruction de votre part, au sein de votre application : détection de visages en double et de comptes multiples, [Authentification biométrique](https://docs.didit.me/fr/core-technology/biometric-auth/overview.md), et vos propres listes faciales. Ils ne sont jamais utilisés pour l'entraînement de modèles, pour des analyses, pour la correspondance inter-organisations, pour les signaux partagés de [Networks](https://docs.didit.me/fr/console/networks.md), ni pour le traitement indépendant de la fraude par Didit.## Objet du gabarit biométrique```json theme={null}
{
  "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b",
  "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f",
  "vendor_data": "user-42",
  "source_type": "session_delete",
  "provenance_reference": "6b1e8d2f-4a3c-4f9e-8c7d-1a2b3c4d5e6f",
  "retention_policy": "retain_until_user_deleted",
  "retention_override": null,
  "retained_at": "2026-08-28T10:15:42.318402Z",
  "expires_at": "2027-08-28T10:15:42.318402Z",
  "retained_by": "3c9e2b1f-7d4a-4e8b-9c1d-5f6a7b8c9d0e",
  "retained_by_type": "API_KEY",
  "instruction_class": "operational_session_delete",
  "instruction_source": "api",
  "instruction_id": "post-approval-cleanup-2026-08",
  "held_out_of_use": false,
  "status": "active",
  "purged_at": null
}
```| Champ | Type | Description |
| - | - | - |
| `uuid` | UUID | Id du gabarit. Généré aléatoirement ; non dérivé de la session supprimée ni de son visage. |
| `vendor_user_uuid` | UUID | L'utilisateur propriétaire. |
| `vendor_data` | chaîne ou null | Le `vendor_data` actuel de l'utilisateur, résolu lors de la lecture du gabarit. |
| `source_type` | énumération | `session_delete`, `automatic_retention` ou `backfill`. |
| `provenance_reference` | UUID | Référence opaque qui relie le gabarit à sa piste d'audit. Ce n'est pas l'id de la session supprimée, et elle ne peut pas être résolue vers celui-ci via l'API. |
| `retention_policy` | énumération | La politique de l'application au moment de la conservation : `delete_with_session` ou `retain_until_user_deleted`. |
| `retention_override` | booléen ou null | La valeur `retain_face_embeddings` envoyée lors de la suppression, ou `null` lorsque la politique a été appliquée. |
| `retained_at` | date-heure | Date de création du gabarit. |
| `expires_at` | date-heure | Date à laquelle le gabarit expire et est purgé automatiquement. Toujours renseignée. |
| `retained_by` | chaîne | Entité ayant donné l'instruction : l'id de l'application pour les clés API, l'id du membre de la Console pour les actions dans la Console, ou un identifiant `service:` pour la conservation automatique. Jamais une adresse e-mail. |
| `retained_by_type` | énumération | `API_KEY`, `CONSOLE_USER` ou `SYSTEM`. |
| `instruction_class` | énumération | `operational_session_delete` ou `privacy_erasure`. |
| `instruction_source` | énumération | `api`, `console`, `automatic_retention`, `backfill`, `privacy_erasure`, `explicit_template_purge`, `vendor_user_delete`, `expiry`, `reconciliation`, `migration` ou `system`. |
| `instruction_id` | chaîne | L'`instruction_id` que vous avez envoyé lors de la suppression, ou un id généré par Didit si vous l'avez omis. |
| `held_out_of_use` | booléen | `true` uniquement tant qu'un gel juridique s'applique. Un gabarit gelé est exclu de toute comparaison. Voir [Gels juridiques](#gels-juridiques). |
| `status` | énumération | Statut du cycle de vie, voir ci-dessous. |
| `purged_at` | date-heure ou null | Date à laquelle le gabarit a été purgé. |### Statut| `status` | Signification | Dans la comparaison |
| - | - | - |
| `pending` | Le gabarit est en cours de création. Si la suppression qui l'a créé a renvoyé `503`, relancez la suppression pour l'achever. | Non |
| `active` | Le gabarit participe à la comparaison jusqu'à `expires_at`. | Oui, sauf si `held_out_of_use` vaut `true` ou si `expires_at` est dépassé |
| `expired` | `expires_at` est dépassé et la purge automatique est en cours. | Non |
| `held_out_of_use` | Un gel juridique s'applique. | Non |
| `purge_pending` | Une purge est en cours. | Non |
| `purge_failed` | Une purge n'a pas pu aboutir car un magasin biométrique était indisponible. Relancez la purge ; le gabarit reste exclu de la comparaison entre-temps. | Non |
| `purged` | Le gabarit est supprimé. Visible uniquement dans la réponse de purge sous la forme `already_purged` ; les gabarits purgés ne sont pas listés et renvoient `404` lorsqu'on demande leur détail. | Non |## Comment les gabarits sont utilisés dans la correspondanceUn gabarit `active` participe exactement aux mêmes opérations de mise en correspondance qu'un visage issu d'une session en direct : la détection automatique de doublons lors des nouvelles sessions, l'[API de recherche faciale autonome](https://docs.didit.me/fr/standalone-apis/face-search.md), l'[Authentification biométrique](https://docs.didit.me/fr/core-technology/biometric-auth/overview.md) et vos listes faciales. Une correspondance avec un gabarit conservé est signalée avec `source: "retained_template"`, le `vendor_user_id` et les `vendor_data` de l'utilisateur propriétaire, ainsi que le `biometric_template_id`. Elle ne comporte jamais d'identifiant de session, d'image de correspondance, de détails d'identité ni de statut, car la session qui a produit le visage n'existe plus. Voir [rapport de recherche faciale](https://docs.didit.me/fr/core-technology/face-search/report-face-search.md).Un gabarit conservé n'est jamais placé sur liste de blocage. Si le visage de la session supprimée figurait sur une liste de blocage faciale, cette entrée de liste conserve sa propre entrée biométrique indépendante et son propre cycle de vie : supprimer l'entrée de la liste supprime l'entrée de la liste de blocage, et purger le gabarit n'affecte pas la liste.## Points de purgeTous les points suivants retirent le gabarit des correspondances et suppriment le gabarit stocké :| Point de purge | Comment |
| - | - |
| Purge explicite | [`DELETE /v3/biometric-templates/{uuid}/`](https://docs.didit.me/fr/management-api/biometric-templates/purge) ou [`POST /v3/biometric-templates/delete/`](https://docs.didit.me/fr/management-api/biometric-templates/batch-purge), ou **Lists → Biometric templates** dans la Console |
| Suppression d'utilisateur | [`POST /v3/users/delete/`](https://docs.didit.me/fr/management-api/users/delete) purge chaque gabarit rattaché à l'utilisateur avant la suppression de celui-ci |
| Effacement au titre de la vie privée | Toute suppression d'une session de cet utilisateur envoyée avec `deletion_instruction: "privacy_erasure"` purge chaque gabarit rattaché à l'utilisateur, quelle que soit la politique de l'application |
| Expiration | Didit purge automatiquement le gabarit dès que `expires_at` est dépassé |Revenir à la politique d'application `delete_with_session` empêche la création de nouveaux gabarits, mais ne purge **pas** les gabarits existants. Purgez-les explicitement.Une purge supprime d'abord le gabarit stocké, puis seulement marque le gabarit comme purgé. Ainsi, une purge qui renvoie `503` laisse le gabarit en `purge_failed`, déjà exclu des correspondances, et il est possible de la répéter sans risque. Une purge répétée d'un gabarit déjà purgé renvoie `already_purged`.## Piste d'auditChaque tentative de conservation et de purge, y compris les échecs et les résultats non éligibles, est enregistrée avec le principal à l'origine de l'action (`retained_by` ou principal de purge et son type), `instruction_class`, `instruction_source`, `instruction_id`, `provenance_reference` et le résultat. Envoyez votre propre `instruction_id` lors des suppressions afin de pouvoir corréler la piste d'audit de Didit avec votre journal d'effacement. Les entrées d'audit ne contiennent jamais d'images, de vecteurs, de champs d'identité ni d'adresses e-mail.## Gels juridiquesUn gel juridique est une exception, il n'est jamais un mode de conservation. Didit ne place pas de gel de sa propre initiative : un gel ne peut faire suite qu'à une instruction documentée au titre de votre accord de traitement des données, ou à une ordonnance contraignante d'une autorité compétente. Tant qu'un gel s'applique, le gabarit est marqué `held_out_of_use` : il est exclu de tout type de correspondance et de la restauration de routine, et il n'est jamais consultable. Aucune API ne permet de créer ou de lever un gel. Contactez votre interlocuteur Didit si vous recevez une ordonnance qui concerne des gabarits conservés.## Autorisations et authentificationLes endpoints Biometric Templates n'acceptent que les clés API d'application (`x-api-key`). Les jetons d'utilisateur de la Business Console sont rejetés avec `403`. Les utilisateurs de la Console gèrent les gabarits via **Lists → Biometric templates** avec leurs autorisations `lists`.## Endpoints| Endpoint | Méthode | Fonction |
| - | - | - |
| [`/v3/biometric-templates/`](https://docs.didit.me/fr/management-api/biometric-templates/list) | GET | Liste paginée avec filtres |
| [`/v3/biometric-templates/count/`](https://docs.didit.me/fr/management-api/biometric-templates/count) | GET | Nombre avec les mêmes filtres |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/fr/management-api/biometric-templates/get) | GET | Un gabarit |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/fr/management-api/biometric-templates/purge) | DELETE | Purger un gabarit |
| [`/v3/biometric-templates/delete/`](https://docs.didit.me/fr/management-api/biometric-templates/batch-purge) | POST | Purger par liste d'identifiants ou par filtre |## Voir aussi- [Supprimer une session](https://docs.didit.me/fr/sessions-api/delete-session.md)
- [Suppression de sessions par lot](https://docs.didit.me/fr/management-api/sessions/batch-delete.md)
- [Conservation des données](https://docs.didit.me/fr/console/data-retention.md#conservation-des-gabarits-biométriques)
- [Visages et biométrie](https://docs.didit.me/fr/entities/users/faces-and-biometrics.md)


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