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

# Gesichtssuche & Sperrliste: Benutzerbiometrie

> Didit hängt Gesichtsbiometrie an Benutzer-Entitäten an: 1:N-Gesichtssuche, Duplikaterkennung, Sperrlisten-Durchsetzung und manueller Upload.



Prompt für Gesichtsbiometrie
        Prompt in die Zwischenablage kopieren



      
      

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



      
      

Einfügen in

Gesichtsbiometrie ist für jede Benutzer-Entität zentral. Didit erfasst während der [Liveness-Erkennung](https://docs.didit.me/de/core-technology/liveness/overview.md) ein Gesicht, erzeugt ein Vektor-Embedding und speichert es für vier nachgelagerte Funktionen: **1:N-Gesichtssuche**, **Duplikaterkennung**, **Durchsetzung der Sperrliste** und **erneute biometrische Authentifizierung**.> [!NOTE]
>
> Gespeicherte Gesichter dienen zugleich als Referenz für die [Biometrische Authentifizierung](https://docs.didit.me/de/core-technology/biometric-auth/overview.md). Erstellen Sie eine Sitzung für die biometrische Authentifizierung mit den `vendor_data` des Benutzers und lassen `portrait_image` weg, dann verwendet Didit das gespeicherte Gesicht automatisch (zuerst das genehmigte Liveness-Gesicht, dann das Foto aus dem ePassport-Chip, dann das Porträt aus dem Ausweisdokument und zuletzt ein manuell hinterlegtes Profilgesicht).## Wie Gesichter einem Benutzer zugeordnet werden**1. Während der Liveness-Erkennung erfasst**Wenn ein Benutzer eine Sitzung mit aktivierter Liveness-Erkennung durchläuft, nimmt Didit ein Selfie auf, führt eine passive Liveness-Erkennung durch, extrahiert das größte Gesicht und erzeugt ein Vektor-Embedding für die Suche.**2. Im Benutzerprofil gespeichert**Das Gesicht wird mit der Sitzung und der übergeordneten Benutzer-Entität verknüpft. Die Porträt-URL wird im Benutzerprofil als `portrait_image` angezeigt.**3. Für die Suche indexiert**Das Embedding wird dem Suchindex hinzugefügt. Nachfolgende Sitzungen können 1:N-Suchen gegen diesen Index ausführen.## Gesichtssuche (1:N)Mit der Gesichtssuche finden Sie einen Benutzer, indem Sie ein Bild hochladen und es mit allen registrierten Gesichtern in Ihrer Anwendung abgleichen.Anwendungsfälle:- **Duplikaterkennung** beim Onboarding: verhindern, dass dieselbe Person zwei Konten anlegt.
- **Umgekehrte Suche**: den Benutzer hinter einem CCTV-Standbild oder einem Bild in einer Betrugsuntersuchung identifizieren.
- **Wiedererkennung von Bestandskunden**: KYC für einen wiederkehrenden Kunden überspringen.Die Gesichtssuche läuft automatisch bei neuen Sitzungen, wenn in Ihrem Workflow die Duplikaterkennung aktiviert ist. Sie steht außerdem als eigenständige API zur Verfügung:- `POST /v3/face-search/`: [eigenständige Gesichtssuche](https://docs.didit.me/de/standalone-apis/face-search.md)## DuplikaterkennungJedes neue Gesicht kann mit bereits registrierten Gesichtern verglichen werden, um Duplikate aufzudecken. Didit weist jedem Gesicht einen `approved_duplicate_status` zu:| Status | Bedeutung |
| - | - |
| `NOT_DUPLICATED` | Keine Übereinstimmungen oberhalb des Ähnlichkeitsschwellenwerts gefunden |
| `DUPLICATED` | Das Gesicht stimmt mit einem oder mehreren Gesichtern aus einer bereits genehmigten Sitzung überein |Workflows lassen sich so konfigurieren, dass sie:- Sitzungen mit Duplikat-Kennzeichnung automatisch **ablehnen**.
- **zur Prüfung markieren**: an einen menschlichen Analysten weiterleiten.
- **nur warnen**: die Sitzung zulassen, aber ein Risiko-Tag hinzufügen.Konfigurieren Sie dies in der Konsole unter *Workflows → \[Ihr Workflow] → Face Match / Liveness → Duplicate detection*.## Sperrliste für GesichterWenn Sie eine Sitzung ablehnen, wird das Gesicht nicht in eine Sperrliste aufgenommen. Um künftige Sitzungen mit demselben Gesicht abzulehnen, sperren Sie es selbst: fügen Sie es über die [Sperrlisten-Seite](https://docs.didit.me/de/console/blocklist-users.md) oder mit der [Lists API](https://docs.didit.me/de/management-api/lists/overview.md) hinzu. Eine neue Sitzung, deren Liveness-Selfie zu diesem Eintrag passt, wird automatisch abgelehnt.## Ein importiertes Gesicht einem Benutzerprofil hinzufügenWenn Sie von einem anderen KYC-Anbieter migrieren, können Sie zuerst den Benutzer anlegen und anschließend ein vertrauenswürdiges Gesichtsbild diesem Profil zuordnen. Der Benutzer wird weiterhin über Ihr `vendor_data` identifiziert, der Endpoint zum Hochladen des Gesichts verwendet jedoch die interne Benutzer-ID von Didit (`didit_internal_id`), damit das Ziel eindeutig ist.**1. Benutzer anlegen oder abrufen**Rufen Sie [`POST /v3/users/create/`](https://docs.didit.me/de/management-api/users/create) mit Ihrem stabilen `vendor_data` auf oder rufen Sie `GET /v3/users/{vendor_data}/` auf, wenn der Benutzer bereits existiert.**2. didit\_internal\_id auslesen**Die Benutzerantwort enthält `didit_internal_id`. Verwenden Sie in Ihrem eigenen System weiterhin `vendor_data`; verwenden Sie `didit_internal_id` nur für die Endpoints zum Anhängen an Profile.**3. Gesicht hochladen**Rufen Sie [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](https://docs.didit.me/de/management-api/users/upload-face) mit einem Base64-kodierten Gesichtsbild auf.```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"
  }'
```Importierte Profilgesichter werden in denselben Gesichtsindex aufgenommen, der für Duplikaterkennung und Gesichtssuche verwendet wird. Sie werden nicht automatisch gesperrt. Um einen bekannten Täter zu sperren, laden Sie das Gesicht stattdessen in eine Liste vom Typ Gesicht hoch.> [!WARNING]
>
> Laden Sie nur Gesichter hoch, deren Verarbeitung nach Ihrer eigenen Datenschutzerklärung und Migrationsvereinbarung zulässig ist. Hinterlegen Sie Kennungen des Quellanbieters nur dann in `metadata` oder `comment`, wenn sie Ihren Compliance-Beauftragten offengelegt werden dürfen.### So erfolgt die Sperrung| Auslöser | Aktion |
| - | - |
| Sitzung `DECLINED` | Nichts wird zu einer Sperrliste hinzugefügt; der Benutzer bleibt `ACTIVE` |
| Analyst sperrt ein Gesicht manuell in der Konsole | Gesicht wird hinzugefügt, Benutzerstatus wird gemäß Richtlinie aktualisiert |
| Programmatisches Hinzufügen über die Lists API | Laden Sie das Gesichtsbild in eine Sperrliste vom Typ Gesicht hoch |### Ein Gesicht in die Sperrliste hochladenUm einen Benutzer programmatisch anhand seines Gesichts zu sperren, laden Sie das Gesichtsbild über den eigens dafür vorgesehenen Endpoint [Gesicht in Liste hochladen](https://docs.didit.me/de/management-api/lists/upload-face.md) in eine Sperrliste vom Typ Gesicht hoch. Didit extrahiert das biometrische Embedding und fügt es dem passenden Index hinzu. Jede künftige Sitzung, deren Liveness-Selfie übereinstimmt, wird automatisch abgelehnt.> [!NOTE]
>
> Das Hochladen eines Profilgesichts und das Hochladen in eine Gesichts-Sperrliste sind unterschiedliche Vorgänge. Verwenden Sie den Profil-Upload, um einem Benutzer ein vertrauenswürdiges importiertes Gesicht als Nachweis, zur Duplikaterkennung und Gesichtssuche zuzuordnen. Verwenden Sie die [Lists API](https://docs.didit.me/de/management-api/lists/overview.md), um ein Gesicht zu sperren, damit passende künftige Sitzungen abgelehnt werden.### Ein Gesicht aus der Sperrliste entfernenEntfernen Sie den Eintrag in der Konsole unter *Blocklist → Faces → Zeilenaktionen → Remove* oder verwenden Sie den Endpoint [Eintrag löschen](https://docs.didit.me/de/management-api/lists/delete-entry.md).## Aufbewahrte biometrische Templates nach dem Löschen einer SitzungBeim Löschen einer Sitzung werden das Gesichtsbild und standardmäßig auch das Gesichts-Embedding gelöscht. Die Person fällt damit aus der Duplikatserkennung und der Gesichtssuche heraus. Wenn Sie Sitzungen kurz nach der Genehmigung löschen, aber dennoch wiederholte Registrierungen erkennen müssen, aktivieren Sie die [Aufbewahrung biometrischer Templates](https://docs.didit.me/de/console/data-retention.md#aufbewahrung-biometrischer-templates) für die Anwendung oder senden Sie `retain_face_embeddings: true` beim Löschaufruf.Didit löscht danach die Sitzung und alle zugehörigen Daten wie gewohnt und behält ein separat verwaltetes, bildfreies biometrisches Gesichts-Template, das mit dem Benutzer verknüpft ist:- Es enthält nur das numerische Gesichts-Template und Aufbewahrungsmetadaten. Es enthält niemals das Gesichtsbild, das Liveness-Video, Dokumentdaten, extrahierte Identitätsfelder, die Entscheidung oder die ID der gelöschten Sitzung.
- Es nimmt an der Duplikatserkennung, der Gesichtssuche, der biometrischen Authentifizierung und Ihren Gesichtslisten genauso teil wie das Gesicht einer aktiven Sitzung. Treffer werden mit `source: "retained_template"`, dem `vendor_user_id` und `vendor_data` des Benutzers sowie einer `biometric_template_id` gemeldet.
- Es handelt sich um biometrische Daten mit einem endlichen `expires_at`. Das Template wird entfernt, wenn der Benutzer gelöscht wird, wenn eine Sitzung dieses Benutzers mit `deletion_instruction: "privacy_erasure"` gelöscht wird, wenn es abläuft oder wenn Sie es unter **Lists → Biometric templates** oder über die [Biometric Templates API](https://docs.didit.me/de/management-api/biometric-templates/overview.md) entfernen.
- Eine Sitzung, die ohne `vendor_data` erstellt wurde, hat keinen Benutzer, mit dem ein Template verknüpft werden könnte. Beim Löschen wird `ineligible_no_vendor_user` gemeldet, und das Embedding wird zusammen mit der Sitzung gelöscht.
- Aufbewahrte Templates werden niemals auf die Sperrliste gesetzt. Ein Eintrag in der Gesichts-Sperrliste, der aus der gelöschten Sitzung erstellt wurde, behält seinen eigenen, unabhängigen biometrischen Eintrag und Lebenszyklus.Mit einem Benutzer verknüpfte Templates erscheinen im Benutzerprofil unter **Biometric templates** mit einer Aktion zum Entfernen.## Zusammenfassung des Gesichts-Lebenszyklus```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
```## Ein Gesicht über die Konsole hochladenCompliance-Mitarbeitende können Gesichter manuell hochladen:1) Navigieren Sie zu *Users → \[user] → Actions → Upload face*.
2) Wählen Sie ein Bild aus; Didit extrahiert das größte Gesicht und speichert einen neuen Gesichtseintrag, der mit dem Benutzer verknüpft ist.
3) Das Gesicht wird für Profilnachweise, Duplikatserkennung und Gesichtssuche registriert. Verwenden Sie den Bereich Sperrliste, wenn künftige passende Sitzungen abgelehnt werden sollen.Das ist nützlich, wenn:- Sie ein bekanntes Porträt eines Kunden haben, das über einen Offline-Kanal verifiziert wurde.
- Sie eine Sperrliste mit bekannten Betrügern aus Ihrer Betrugsdatenbank vorbefüllen möchten.## Datenschutz und Aufbewahrung- Gesichts-Embeddings sind numerische Vektoren, keine Bilder. Die Bilder selbst werden in verschlüsseltem Objektspeicher mit Zugriff über signierte URLs gespeichert. Ein Gesichts-Embedding stellt biometrische Daten dar.
- Die Aufbewahrung richtet sich nach der [Datenaufbewahrung](https://docs.didit.me/de/console/data-retention.md) Ihrer Anwendung. Aufbewahrte biometrische Templates folgen dem strengeren, endlichen Aufbewahrungszeitraum der [Aufbewahrung biometrischer Templates](https://docs.didit.me/de/console/data-retention.md#aufbewahrung-biometrischer-templates).
- Beim Löschen einer Sitzung werden das Bild und standardmäßig das Embedding gelöscht. Wenn Ihre Anwendung die Aufbewahrung biometrischer Templates aktiviert hat, bleibt beim Löschen einer Sitzung ein bildfreies Template erhalten, bis es abläuft oder entfernt wird.
- Bei einer Anfrage gemäß GDPR/CCPA zum Recht auf Vergessenwerden löschen Sie die Sitzungen der Person mit `deletion_instruction: "privacy_erasure"` oder löschen Sie den Benutzer. Beides entfernt auch alle aufbewahrten Templates. Von Ihnen verwaltete Einträge in der Gesichts-Sperrliste bleiben bestehen, bis Sie sie entfernen.## Nächste Schritte> [card] [Gesichtssuche](https://docs.didit.me/de/core-technology/face-search/overview.md)
>
> Wie die 1:N-Gesichtssuche funktioniert.> [card] [Liveness](https://docs.didit.me/de/core-technology/liveness/overview.md)
>
> Liveness-Erkennung, die das Gesicht erfasst.> [card] [Sperrlisten-API](https://docs.didit.me/de/management-api/lists/upload-face.md)
>
> Ein Gesicht in eine Sperrliste hochladen.> [card] [Biometrische Templates](https://docs.didit.me/de/management-api/biometric-templates/overview.md)
>
> Nach dem Löschen einer Sitzung aufbewahrte Templates.> [card] [Benutzer-Sperrliste](https://docs.didit.me/de/entities/users/blocklist.md)
>
> Wie das Hinzufügen eines Benutzers zur Sperrliste funktioniert.


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