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

# Biometrische Templates API

> Verwalten Sie bildfreie biometrische Templates nach der Sitzungslöschung über die Didit API: auflisten, zählen, filtern, prüfen und löschen.



Prompt für die Biometric Templates API
        Prompt in die Zwischenablage kopieren



      
      

\<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>



      
      

Einfügen in

Standardmäßig wird beim Löschen einer Verifizierungssitzung auch das Gesichts-Embedding gelöscht, das die [Gesichtssuche 1:N](https://docs.didit.me/de/core-technology/face-search/overview.md) und die Duplikaterkennung für diese Sitzung unterstützt hat. Anwendungen, bei denen die Duplikaterkennung nach dem Löschen einer Sitzung weiterhin funktionieren muss, können die **Aufbewahrung biometrischer Templates** aktivieren. Didit löscht dann die Sitzung und alle ihre Daten wie gewohnt und behält ein separat verwaltetes, bildfreies biometrisches Gesichts-Template, das dem [Benutzer](https://docs.didit.me/de/entities/users/overview.md) der Sitzung zugeordnet ist.Mit der Biometric Templates API können Sie genau einsehen, welche Vorlagen Ihre Anwendung speichert, warum sie gespeichert werden und bis wann, und Sie können sie jederzeit löschen. Jede Vorlage ist außerdem in der Business Console unter **Lists → Biometric templates** und im Profil des zugehörigen Benutzers sichtbar.> [!WARNING]
>
> Ein aufbewahrtes biometrisches Template gehört zu den biometrischen Daten. Es ist nicht anonym, es ist nicht vorübergehend, und es wird nicht zusammen mit der Sitzung gelöscht. Es bleibt bestehen, bis sein geplantes Ablaufdatum erreicht ist, eine früher greifende gesetzliche Frist abläuft, der Benutzer gelöscht wird, ein Antrag auf Löschung aus Datenschutzgründen eingeht oder es ausdrücklich gelöscht wird. Aktivieren Sie die Aufbewahrung nur, wenn Ihre Weisung als Verantwortlicher und Ihre Datenschutzerklärung sie abdecken.## Wie eine Vorlage erstellt wird| Auslöser | `source_type` | Herkunft der Weisung |
| - | - | - |
| Sie löschen eine Sitzung in einer Anwendung, die die Aufbewahrung aktiviert hat, oder senden `retain_face_embeddings: true` bei [Sitzung löschen](https://docs.didit.me/de/sessions-api/delete-session.md) oder [Batch-Sitzungen löschen](https://docs.didit.me/de/management-api/sessions/batch-delete.md) | `session_delete` | `instruction_source: api` oder `console` |
| Der allgemeine [Datenaufbewahrungszeitraum](https://docs.didit.me/de/console/data-retention.md) Ihrer Anwendung läuft für eine Sitzung in einer Anwendung ab, die die Aufbewahrung aktiviert hat | `automatic_retention` | `instruction_source: automatic_retention` |
| Ein von Didit durchgeführtes Backfill, das Sie für Sitzungen beauftragt haben, die vor Ihrer Aktivierung gelöscht wurden | `backfill` | `instruction_source: backfill` |Die Aufbewahrung erfordert einen Benutzer als Zuordnung. Eine Sitzung, die ohne `vendor_data` erstellt wurde, hat keinen Benutzer und kann daher keine Vorlage aufbewahren. Die Löschung meldet `ineligible_no_vendor_user`, und das Gesichts-Embedding wird zusammen mit der Sitzung gelöscht.## Was eine Vorlage enthält| Aufbewahrt | Niemals aufbewahrt |
| - | - |
| Die numerische Gesichtsvorlage für den Abgleich | Das Gesichtsbild, das Liveness-Video, Dokumentbilder, Porträtausschnitte und alle anderen Medien |
| Eine neue, zufällige Vorlagen-`uuid` und eine undurchsichtige `provenance_reference` | Die Sitzungs-ID, die Nummer, die Entscheidung, die extrahierten Identitätsfelder oder die Funktions-Payloads der gelöschten Sitzung |
| Der Benutzer, dem die Vorlage gehört (`vendor_user_uuid`). `vendor_data` wird beim Lesen der Vorlage aus dem Benutzer aufgelöst und niemals kopiert | Sperrlisten-Status, frühere Übereinstimmungen, Betrugskennzeichnungen oder organisationsübergreifende Identitätsansprüche |
| `retained_at`, `expires_at`, `retention_policy`, `retention_override`, `instruction_class`, `instruction_source`, `instruction_id`, `retained_by`, `retained_by_type` | E-Mail-Adressen der handelnden Personen |Vorlagen sind auf Ihren Mandanten beschränkt und werden nur auf Ihre Weisung innerhalb Ihrer Anwendung verwendet: für die Erkennung doppelter Gesichter und mehrfacher Konten, für die [Biometrische Authentifizierung](https://docs.didit.me/de/core-technology/biometric-auth/overview.md) und für Ihre eigenen Gesichtslisten. Sie werden niemals für das Training von Modellen, für Analysen, für organisationsübergreifenden Abgleich, für gemeinsam genutzte Signale aus [Networks](https://docs.didit.me/de/console/networks.md) oder für die eigenständige Betrugsverarbeitung durch Didit verwendet.## Vorlagenobjekt```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
}
```| Feld | Typ | Beschreibung |
| - | - | - |
| `uuid` | UUID | Vorlagen-ID. Zufällig erzeugt und nicht von der gelöschten Sitzung oder ihrem Gesicht abgeleitet. |
| `vendor_user_uuid` | UUID | Der Benutzer, dem die Vorlage gehört. |
| `vendor_data` | string oder null | Das aktuelle `vendor_data` des Benutzers, beim Lesen der Vorlage aufgelöst. |
| `source_type` | enum | `session_delete`, `automatic_retention` oder `backfill`. |
| `provenance_reference` | UUID | Undurchsichtige Referenz, die die Vorlage mit ihrem Audit-Trail verbindet. Sie ist nicht die ID der gelöschten Sitzung und kann über die API nicht auf diese zurückgeführt werden. |
| `retention_policy` | enum | Die Richtlinie der Anwendung zum Zeitpunkt der Aufbewahrung: `delete_with_session` oder `retain_until_user_deleted`. |
| `retention_override` | boolean oder null | Der Wert `retain_face_embeddings`, der bei der Löschung gesendet wurde, oder `null`, wenn die Richtlinie angewendet wurde. |
| `retained_at` | datetime | Zeitpunkt, zu dem die Vorlage erstellt wurde. |
| `expires_at` | datetime | Zeitpunkt, zu dem die Vorlage abläuft und automatisch gelöscht wird. Immer gesetzt. |
| `retained_by` | string | Akteur, der die Weisung erteilt hat: die Anwendungs-ID bei API-Schlüsseln, die Mitglieds-ID der Console bei Console-Aktionen oder eine `service:`-Kennung für die automatische Aufbewahrung. Niemals eine E-Mail-Adresse. |
| `retained_by_type` | enum | `API_KEY`, `CONSOLE_USER` oder `SYSTEM`. |
| `instruction_class` | enum | `operational_session_delete` oder `privacy_erasure`. |
| `instruction_source` | enum | `api`, `console`, `automatic_retention`, `backfill`, `privacy_erasure`, `explicit_template_purge`, `vendor_user_delete`, `expiry`, `reconciliation`, `migration` oder `system`. |
| `instruction_id` | string | Die `instruction_id`, die Sie bei der Löschung gesendet haben, oder eine von Didit generierte ID, wenn Sie sie weggelassen haben. |
| `held_out_of_use` | boolean | `true` nur, solange eine rechtliche Sperre gilt. Eine gesperrte Vorlage wird von jedem Abgleich ausgeschlossen. Siehe [Rechtliche Sperren](#rechtliche-sperren). |
| `status` | enum | Lebenszyklusstatus, siehe unten. |
| `purged_at` | datetime oder null | Zeitpunkt, zu dem die Vorlage gelöscht wurde. |### Status| `status` | Bedeutung | Beim Abgleich? |
| - | - | - |
| `pending` | Die Vorlage wird erstellt. Wenn die Löschung, die sie erzeugt hat, `503` zurückgegeben hat, wiederholen Sie die Löschung, um sie abzuschließen. | Nein |
| `active` | Die Vorlage nimmt bis `expires_at` am Abgleich teil. | Ja, außer wenn `held_out_of_use` den Wert `true` hat oder `expires_at` überschritten ist |
| `expired` | `expires_at` ist überschritten, und die automatische Löschung läuft. | Nein |
| `held_out_of_use` | Eine rechtliche Sperre gilt. | Nein |
| `purge_pending` | Eine Löschung läuft. | Nein |
| `purge_failed` | Eine Löschung konnte nicht abgeschlossen werden, weil ein biometrischer Speicher nicht verfügbar war. Wiederholen Sie die Löschung. Die Vorlage bleibt in der Zwischenzeit vom Abgleich ausgeschlossen. | Nein |
| `purged` | Die Vorlage ist gelöscht. Nur in der Löschantwort als `already_purged` sichtbar. Gelöschte Vorlagen werden nicht aufgelistet und liefern bei der Detailabfrage `404`. | Nein |## Wie Vorlagen beim Abgleich verwendet werdenEine `active`-Vorlage nimmt am selben Abgleich teil wie ein Live-Gesicht aus einer Sitzung: an der automatischen Erkennung von Duplikaten bei neuen Sitzungen, an der eigenständigen [Gesichtssuche-API](https://docs.didit.me/de/standalone-apis/face-search.md), an der [Biometrischen Authentifizierung](https://docs.didit.me/de/core-technology/biometric-auth/overview.md) und an Ihren Gesichtslisten. Ein Treffer auf eine gespeicherte Vorlage wird mit `source: "retained_template"`, dem `vendor_user_id` und den `vendor_data` des zugehörigen Benutzers sowie der `biometric_template_id` gemeldet. Er enthält niemals eine Sitzungs-ID, ein Vergleichsbild, Identitätsdaten oder einen Status, weil die Sitzung, die das Gesicht erzeugt hat, nicht mehr existiert. Siehe [Bericht zur Gesichtssuche](https://docs.didit.me/de/core-technology/face-search/report-face-search.md).Eine gespeicherte Vorlage wird niemals auf eine Sperrliste gesetzt. Stand das Gesicht der gelöschten Sitzung auf einer Gesichts-Sperrliste, behält dieser Listeneintrag seinen eigenen, unabhängigen biometrischen Eintrag und seinen eigenen Lebenszyklus: Das Entfernen des Listeneintrags löscht den Sperrlisten-Eintrag, und das Löschen der Vorlage berührt die Liste nicht.## LöschpunkteAlle folgenden Ereignisse entfernen die Vorlage aus dem Abgleich und löschen die gespeicherte Vorlage:| Löschpunkt | Vorgehen |
| - | - |
| Explizite Löschung | [`DELETE /v3/biometric-templates/{uuid}/`](https://docs.didit.me/de/management-api/biometric-templates/purge) oder [`POST /v3/biometric-templates/delete/`](https://docs.didit.me/de/management-api/biometric-templates/batch-purge) oder **Lists → Biometric templates** in der Console |
| Löschung des Benutzers | [`POST /v3/users/delete/`](https://docs.didit.me/de/management-api/users/delete) löscht jede dem Benutzer zugeordnete Vorlage, bevor der Benutzer gelöscht wird |
| Datenschutzbedingte Löschung | Jede Löschung einer Sitzung dieses Benutzers, die mit `deletion_instruction: "privacy_erasure"` gesendet wird, löscht jede dem Benutzer zugeordnete Vorlage, unabhängig von der Anwendungsrichtlinie |
| Ablauf | Didit löscht die Vorlage automatisch, sobald `expires_at` verstrichen ist |Wenn Sie die Anwendungsrichtlinie wieder auf `delete_with_session` umstellen, werden keine neuen Vorlagen mehr erstellt. Bestehende Vorlagen werden dadurch aber **nicht** gelöscht. Löschen Sie sie explizit.Eine Löschung entfernt zuerst die gespeicherte Vorlage und markiert die Vorlage erst danach als gelöscht. Wenn eine Löschung mit `503` antwortet, bleibt die Vorlage daher im Status `purge_failed`, ist bereits vom Abgleich ausgeschlossen und lässt sich gefahrlos wiederholen. Eine wiederholte Löschung einer bereits gelöschten Vorlage gibt `already_purged` zurück.## Audit-TrailJeder Versuch, eine Vorlage aufzubewahren oder zu löschen, wird protokolliert, auch fehlgeschlagene Versuche und Vorgänge mit nicht zulässigem Ergebnis. Protokolliert werden der handelnde Akteur (`retained_by` bzw. der löschende Akteur und der Typ des Akteurs), `instruction_class`, `instruction_source`, `instruction_id`, `provenance_reference` und das Ergebnis. Senden Sie bei Löschungen Ihre eigene `instruction_id`, damit Sie den Audit-Trail von Didit mit Ihrem Löschprotokoll abgleichen können. Audit-Einträge enthalten niemals Bilder, Vektoren, Identitätsfelder oder E-Mail-Adressen.## Rechtliche SperrenEine rechtliche Sperre ist eine Ausnahme und niemals ein Aufbewahrungsmodus. Didit setzt von sich aus keine rechtlichen Sperren. Eine Sperre kann nur auf eine dokumentierte Anweisung im Rahmen Ihres Auftragsverarbeitungsvertrags oder auf eine verbindliche Anordnung einer zuständigen Behörde folgen. Solange eine Sperre gilt, wird die Vorlage als `held_out_of_use` markiert. Sie ist von jeder Art des Abgleichs und von der routinemäßigen Wiederherstellung ausgeschlossen und niemals durchsuchbar. Es gibt keine API, um rechtliche Sperren anzulegen oder aufzuheben. Wenden Sie sich an Ihren Didit-Ansprechpartner, wenn Sie eine Anordnung erhalten, die gespeicherte Vorlagen betrifft.## Berechtigungen und AuthentifizierungDie Endpunkte für biometrische Templates akzeptieren ausschließlich API-Schlüssel der Anwendung (`x-api-key`). Benutzer-Tokens der Business Console werden mit `403` abgelehnt. Console-Benutzer verwalten Vorlagen über **Lists → Biometric templates** mit ihren `lists`-Berechtigungen.## Endpunkte| Endpunkt | Methode | Zweck |
| - | - | - |
| [`/v3/biometric-templates/`](https://docs.didit.me/de/management-api/biometric-templates/list) | GET | Paginierte Liste mit Filtern |
| [`/v3/biometric-templates/count/`](https://docs.didit.me/de/management-api/biometric-templates/count) | GET | Anzahl mit denselben Filtern |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/de/management-api/biometric-templates/get) | GET | Eine Vorlage |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/de/management-api/biometric-templates/purge) | DELETE | Eine Vorlage löschen |
| [`/v3/biometric-templates/delete/`](https://docs.didit.me/de/management-api/biometric-templates/batch-purge) | POST | Löschen nach ID-Liste oder nach Filter |## Verwandte Themen- [Sitzung löschen](https://docs.didit.me/de/sessions-api/delete-session.md)
- [Sitzungen im Batch löschen](https://docs.didit.me/de/management-api/sessions/batch-delete.md)
- [Datenaufbewahrung](https://docs.didit.me/de/console/data-retention.md#aufbewahrung-biometrischer-templates)
- [Gesichter und Biometrie](https://docs.didit.me/de/entities/users/faces-and-biometrics.md)


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