Biometrische Templates API

Standardmäßig wird beim Löschen einer Verifizierungssitzung auch das Gesichts-Embedding gelöscht, das die Gesichtssuche 1:N 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 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.

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 oder Batch-Sitzungen löschen	`session_delete`	`instruction_source: api` oder `console`
Der allgemeine Datenaufbewahrungszeitraum 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 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 oder für die eigenständige Betrugsverarbeitung durch Didit verwendet.

Vorlagenobjekt

{
  "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.
`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 werden

Eine 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, an der Biometrischen Authentifizierung 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. 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öschpunkte

Alle 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}/` oder `POST /v3/biometric-templates/delete/` oder Lists → Biometric templates in der Console
Löschung des Benutzers	`POST /v3/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-Trail

Jeder 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 Sperren

Eine 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 Authentifizierung

Die 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/`	GET	Paginierte Liste mit Filtern
`/v3/biometric-templates/count/`	GET	Anzahl mit denselben Filtern
`/v3/biometric-templates/{template_uuid}/`	GET	Eine Vorlage
`/v3/biometric-templates/{template_uuid}/`	DELETE	Eine Vorlage löschen
`/v3/biometric-templates/delete/`	POST	Löschen nach ID-Liste oder nach Filter

​Wie eine Vorlage erstellt wird

​Was eine Vorlage enthält

​Vorlagenobjekt

​Status

​Wie Vorlagen beim Abgleich verwendet werden

​Löschpunkte

​Audit-Trail

​Rechtliche Sperren

​Berechtigungen und Authentifizierung

​Endpunkte

​Verwandte Themen