> ## 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 1:N-API: Duplikaterkennung

> Gesichter verifizierter Nutzer nach Duplikaten und Betrügern durchsuchen. Kostenlos mit Didit-Verifizierung, Antwortzeit unter 2 Sekunden.

Die Gesichtssuche ist eine leistungsstarke Funktion, mit der Sie nach einem bestimmten Gesicht über alle Ihre genehmigten Identitätsverifizierungssitzungen hinweg suchen können. Diese Funktion hilft dabei, doppelte Konten zu identifizieren, Betrug zu verhindern und Ihre Sicherheitsmaßnahmen zu verbessern.

Prompt zur Integration der Gesichtssuche
        Prompt in die Zwischenablage kopieren



      
      

\<pre>

\````# Goal
Integrate Didit Face Search (1:N — search a face across your enrolled users + blocklist) into your app.

\# Delivery mode
Face Search is a **standalone API**. It runs against the face index your application has enrolled through prior verifications (sessions with save_api_request=true or Passive Liveness with save_api_request=true), faces uploaded to User profiles, your face lists, and any image-free biometric templates the application retained after deleting sessions (opt-in, see /management-api/biometric-templates/overview). There is no separate Face Search workflow feature.

POST https://verification.didit.me/v3/face-search/
multipart/form-data — x-api-key: YOUR_API_KEY

Required: `user_image` (jpg/jpeg/png/tiff/webp, max 5 MB; PDFs not accepted). The image must contain at least one detectable face (largest bbox wins when multiple).

Optional: `search_type` = "most_similar" (default — dedupe / returning-user) | "blocklisted_or_approved" (blocklist screening).

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/face-search/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'search_type=most_similar' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```

\# Response shape (singular)
Unlike most features, Face Search returns a **singular** `face_search` object — not a plural array:
\{ request_id, face_search: { status, total_matches, matches: [{ session_id, session_number, similarity_percentage, source, vendor_data, vendor_user_id, biometric_template_id, verification_date, user_details, match_image_url, status, is_blocklisted, is_allowlisted, api_service }], user_image: {entities}, warnings: [...] } }

match.source is "session", "imported", "list_entry", or "retained_template". A retained_template hit comes from an image-free biometric template kept after the source session was deleted: session_id, session_number, status, api_service, match_image_url, and user_details are null; vendor_data and vendor_user_id identify the User; biometric_template_id is the template you can inspect or purge via /v3/biometric-templates/{id}/.

\`status` is "Declined" only when at least one blocklist match is found. Pure duplicate matches return "Approved" (informational) — apply your own dedupe policy in app logic.

\# Warnings
Face Search emits risk codes from the LogWarningChoices.FACEMATCH bucket plus blocklist/duplicate semantics:
FACE_IN_BLOCKLIST, POSSIBLE_FACE_IN_BLOCKLIST, DUPLICATED_FACE, POSSIBLE_DUPLICATED_FACE, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/face-search/warnings-face-search.

\# Failure modes to handle
\- HTTP 400 — no face detected in user_image. Ask the user to retake.
\- HTTP 403 — out of credits.
\- status="Declined" with FACE_IN_BLOCKLIST — definitive blocklist hit; reject.
\- POSSIBLE_FACE_IN_BLOCKLIST — borderline match below the hard threshold; route to manual review.
\- DUPLICATED_FACE — user already verified under a different vendor_data; merge or block according to policy.

\# See also
\- Canonical schema: /reference/data-models#face-search
\- Per-feature report: /core-technology/face-search/report-face-search
\- Risk catalogue: /core-technology/face-search/warnings-face-search
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

Einfügen in

Die Academy-Lektion zum Lesen eines Verifizierungsergebnisses behandelt die Gesichtssuche und Sperrlisten ab 6:53.[Gesichtssuche und Sperrlisten — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=413\&rel=0\&playsinline=1)![1:N-Ablauf der Didit-Gesichtssuche, integriert mit Liveness-Erkennung zur Erkennung von Duplikaten und zur Prüfung auf Sperrlisten](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/face-search-liveness.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=0cb5738f8ceaae7891cf13631485c400)## Automatische Integration der Gesichtssuche> Die Gesichtssuche wird während der Liveness-Prüfungen in Verifizierungssitzungen automatisch durchgeführt, um doppelte Benutzer zu erkennen und mit Gesichtern auf der Sperrliste abzugleichen.### Automatische DuplikaterkennungWenn ein Benutzer während der Identitätsverifizierung eine Liveness-Prüfung abschließt:- Werden seine biometrischen Gesichtsdaten automatisch mit allen zuvor verifizierten Benutzern verglichen
- Erkennt das System potenzielle doppelte Accounts auf Basis der Gesichtsähnlichkeit
- Werden Übereinstimmungen gemäß Ihren konfigurierten Ähnlichkeitsschwellenwerten markiert
- Können Sie potenzielle doppelte Benutzer überprüfen und entsprechende Maßnahmen ergreifen### Sperrlisten-IntegrationDie Gesichtssuche integriert sich nahtlos mit der [Sperrlisten-Funktion](https://docs.didit.me/de/management-api/lists/overview.md):- Während der Verifizierung werden Gesichter automatisch mit Ihrer Sperrliste abgeglichen
- Wird eine Übereinstimmung mit einem Gesicht auf der Sperrliste gefunden, wird die Verifizierung automatisch abgelehnt
- Dies verhindert, dass zuvor identifizierte problematische Benutzer neue Accounts erstellen
- Trägt dazu bei, die Integrität Ihres Verifizierungsprozesses aufrechtzuerhalten### Das bei der Dokumentenerfassung aufgenommene SelfieWährend der Benutzer sein Dokument fotografiert, nimmt die Frontkamera ein Selfie von ihm auf (Silent Capture). Jedes Mal, wenn das Dokument ausgewertet wird, durchläuft dieses Selfie dieselbe 1:N-Suche wie das Liveness-Selfie:- Es wird mit Ihrer Gesichtssperrliste und mit den in Ihrer Anwendung bereits genehmigten Benutzern verglichen – mit denselben Ähnlichkeitsschwellenwerten und derselben Priorität wie bei der Liveness-Suche.
- Ein Treffer auf der Sperrliste löst `FRONT_CAMERA_FACE_IN_BLOCKLIST` (immer abgelehnt) oder `POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST` (immer zur Prüfung) aus. Eine Übereinstimmung mit einem genehmigten Benutzer löst `FRONT_CAMERA_DUPLICATED_FACE` oder `POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE` aus, zusätzlich `FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH`, wenn dieser genehmigte Benutzer unter einem anderen Namen verifiziert wurde, und `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH`, wenn das Ausweisdokument dieses Benutzers ein anderes Geburtsdatum aufweist. Siehe [Warnungen zur Ausweisverifizierung](https://docs.didit.me/de/core-technology/id-verification/warnings-id-verification.md).
- Die Übereinstimmungen werden in den Sitzungsdetails auf der Karte für die Ausweisverifizierung aufgeführt und in `id_verifications[].document_selfie_face_matches` der [Sitzungsentscheidung](https://docs.didit.me/de/sessions-api/retrieve-session.md) zurückgegeben. Die Übereinstimmungen verwenden dasselbe Eintragsformat wie `liveness_checks[].matches`. Das Feld ist für ältere Sitzungen oder wenn die Suche nicht ausgeführt wurde `null`, und ein leeres Array, wenn sie ausgeführt wurde und nichts gefunden hat. `match_image_url` ist eine vorab signierte URL, die abläuft.
- Es wird nur das größte Gesicht im Selfie verwendet, und auch nur dann, wenn der Detektor sicher ist, dass es sich um ein Gesicht handelt. Pro Dokument wird ein Selfie durchsucht: das der Vorderseite oder das der Rückseite, wenn das Selfie der Vorderseite kein deutliches Gesicht enthält.
- Das Selfie wird nur verglichen. Sein biometrisches Template wird niemals gespeichert, sodass spätere Sitzungen niemals damit abgeglichen werden. Um eine Person anhand des Selfies einer Sitzung zu sperren, fügen Sie sie über die Sitzungsseite zu Ihrer Gesichtssperrliste hinzu.Die Suche verfügt über einen eigenen Schalter und eigene Aktionen im Schritt **Ausweisverifizierung**, auf dem Tab **Regeln** des Schritts (**Gesichtssuche bei stiller Aufnahme**), oder über `document_selfie_face_search_enabled` und die `document_selfie_duplicated_face_*`-Aktionen in der [Workflow-Funktionskonfiguration](https://docs.didit.me/de/management-api/workflows/feature-configs.md#ocr-/-ausweisverifizierung). Sie ist standardmäßig aktiviert; die Aktion bei doppelten Gesichtern ist standardmäßig auf Genehmigen gesetzt (die Warnung wird weiterhin gemeldet) und die Gegenprüfungen von Name und Dokument standardmäßig auf Prüfung, genau wie bei den entsprechenden Liveness-Prüfungen. Die Suche benötigt das Selfie, weshalb sie nur ausgeführt wird, wenn Silent Capture aktiviert ist. Wenn Sie die Gesichtssuche im Schritt **Liveness-Erkennung** deaktivieren, wird auch diese Suche deaktiviert: Dieses Opt-out ist eine Entscheidung bezüglich des Gesichts der Person und gilt daher für jedes Selfie der Sitzung.### Die Regel für DokumentenabweichungenDie Regel für **Dokumentenabweichungen** (`DUPLICATED_FACE_DOCUMENT_MISMATCH` für das Liveness-Selfie, `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` für Silent Capture) markiert ein doppeltes Gesicht nur dann, wenn das Ausweisdokument des übereinstimmenden Benutzers ein anderes Geburtsdatum aufweist.
Dieselbe Person, die ein anderes Dokument vorlegt, beispielsweise einen Reisepass nach einem Personalausweis, wird nicht markiert.
Ein erneuertes Dokument wird ebenfalls nicht markiert.
Zwei Sitzungen, die dieselbe Dokumentennummer aus demselben Land aufweisen, werden niemals markiert.### Automatische Gesichtssuche deaktivierenDie automatische Gesichtssuche ist standardmäßig für jeden Liveness-Erkennungs-Schritt aktiviert. Wenn Ihre Datenschutzanforderungen dies erfordern, können Sie sie pro Workflow über den Tab **Regeln** des Schritts **Liveness-Erkennung** in der Business Console (im einfachen und erweiterten Modus) oder mit `face_search_enabled: false` auf dem `LIVENESS`- oder `AGE_ESTIMATION`-Knoten in der [Workflow-Funktionskonfiguration](https://docs.didit.me/de/management-api/workflows/feature-configs.md#liveness) deaktivieren.Wenn der Schalter deaktiviert ist, wird das Liveness-Selfie weiterhin auf Liveness-Erkennung bewertet und im Gesichtsabgleich 1:1 mit dem Dokumentenporträt verglichen, gelangt jedoch niemals in den Gesichtsindex:- Es wird keine Suche ausgeführt, sodass die Sitzung kein Urteil bezüglich Duplikaten, Sperrlisten oder Positivlisten erhält und ihr `liveness_checks[].matches` leer bleibt. Die Regeln für **Doppeltes Gesicht**, **Namensabweichung**, **Dokumentenabweichung** sowie organisationsübergreifende Gesichtsregeln haben keine Grundlage und werden in der Console ausgeblendet.
- Für das Selfie wird kein biometrisches Template gespeichert, sodass spätere Sitzungen nicht mit diesem abgeglichen werden können und für die [Aufbewahrung biometrischer Templates](https://docs.didit.me/de/console/data-retention.md#aufbewahrung-biometrischer-templates) nach dem Löschen der Sitzung nichts verbleibt.
- Das Selfie wird nicht verwendet, um eine gemeinsame biometrische Person für organisationsübergreifende Prüfungen aufzulösen.
- Das bei der Dokumentenerfassung aufgenommene Selfie wird ebenfalls nicht durchsucht (kein `FRONT_CAMERA_*`-Sperrlisten- oder Duplikatsrisiko): Das Opt-out deckt jedes Selfie der Sitzung ab. Der eigene Schalter des Schritts **Ausweisverifizierung** (siehe oben) kann diese Suche auch separat deaktivieren.**Zu welchem Schritt der Schalter gehört.** Der Schalter befindet sich auf dem Schritt, der das Selfie erfasst, sodass ein Schritt für **Liveness-Erkennung** oder **Altersschätzung** für sich selbst gilt. Ein **Gesichtsabgleich**-Schritt hat keinen eigenen Schalter: Wenn ein Benutzer dort das Selfie wiederholt aufnimmt – beispielsweise nachdem Sie ihn aufgefordert haben, diesen Schritt erneut einzureichen –, richtet sich die erneute Aufnahme nach der Einstellung des Liveness-Erkennungs-Schritts, sodass ein Opt-out auch das neue Selfie aus dem Index heraushält. Wenn sich Ihr Workflow in mehr als einen Liveness-Erkennungs-Schritt verzweigt, gilt die Einstellung des Zweigs, den die Sitzung tatsächlich durchlaufen hat, und der organisationsübergreifende Gesichtsabgleich demselben Schritt folgt.Bestehende Workflows behalten das derzeitige Verhalten bei, bis Sie sich dagegen entscheiden (Opt-out). Die Änderung gilt für Sitzungen, die nach dem Speichern des Workflows gestartet werden; von früheren Sitzungen gespeicherte Vorlagen verbleiben im Index, bis diese Sitzungen gelöscht oder bereinigt werden. Die Umstellung hat keine Auswirkungen auf die eigenständige [Face Search API](https://docs.didit.me/de/standalone-apis/face-search.md), die Sie explizit aufrufen.> [!WARNING]
>
> Ihre Gesichts-Sperrliste wird während der Verifizierung durch dieselbe 1:N-Suche durchgesetzt. Wenn die Gesichtssuche beim Liveness-Schritt deaktiviert ist, wird eine auf der Sperrliste geführte Person weder bei diesem Schritt noch über das während der Dokumentenerfassung aufgenommene Selfie erkannt; ist die Gesichtssuche bei Silent Capture im Schritt Ausweisverifizierung deaktiviert, wird die Person auch über dieses Selfie nicht erkannt.### API-ZugriffDie Gesichtssuche ist auch über unsere [API](https://docs.didit.me/de/standalone-apis/face-search.md) verfügbar, sodass Sie:- Gesichtssuchen programmatisch übermitteln können
- Gesichtsabgleichsfunktionen in Ihre eigenen Anwendungen integrieren können
- Benutzerdefinierte Workflows zur Betrugserkennung erstellen können
- Automatisierte Systeme zur Duplikaterkennung aufbauen können## Hauptfunktionen- **Hohe Genauigkeit**: Fortschrittliche biometrische Algorithmen liefern zuverlässige Übereinstimmungsergebnisse
- **Konfigurierbare Schwellenwerte**: Passen Sie die Empfindlichkeit des Abgleichs entsprechend Ihrer Risikotoleranz an
- **Umfassender Scan**: Durchsuchen Sie alle Ihre verifizierten Benutzer
- **Schnelle Ergebnisse**: Verarbeiten Sie Suchen selbst bei großen Benutzerdatenbanken zügig
- **Datenschutzorientiert**: Der Abgleich verwendet numerische Gesichtsvorlagen, die auf Ihre Anwendung beschränkt sind; der Index verlässt niemals Ihren Mandanten### Konfigurierbare SchwellenwerteSie können die Suchempfindlichkeit anpassen, indem Sie verschiedene Schwellenwerte für Ähnlichkeitswerte festlegen:> [!NOTE]
>
> Diese Schwellenwerte können basierend auf Ihrer Risikotoleranz und Ihren Sicherheitsanforderungen angepasst werden.## Funktionsweise**1. Gesichtsextraktion**Wenn eine Suche initiiert wird, verarbeitet das System das Referenzbild:| Prozess | Beschreibung |
| - | - |
| **Merkmalextraktion** | Isoliert Gesichtsmerkmale aus dem Referenzbild |
| **Normalisierung** | Standardisiert Gesichtsdaten für einen konsistenten Vergleich |
| **Qualitätsprüfung** | Prüft Bildqualität und Gesichtsschärfe |
| **Vektorkodierung** | Erstellt eine mathematische Vektordarstellung des Gesichts |**2. Vergleichsalgorithmus**Das System durchsucht Ihre gesamte Datenbank verifizierter Sitzungen:- Vergleicht den Referenz-Gesichtsvektor mit **jedem in Ihrer Anwendung registrierten Gesicht**: Sitzungsgesichter, in Benutzerprofile hochgeladene Gesichter, Ihre Gesichtslisten und alle aufbewahrten biometrischen Templates
- Nutzt eine fortschrittliche neuronale Netzwerkarchitektur, die auf Geschwindigkeit und Genauigkeit optimiert ist
- Unterstützt zwei Suchmodi: **am ähnlichsten** (Rangliste) und **auf Sperrliste oder genehmigt** (nach Status gefiltert)
- Verarbeitet große Datenbanken dank optimierter Indizierung sehr schnell**3. Ähnlichkeitsbewertung**Für jeden Vergleich wird ein Ähnlichkeitsprozentsatz generiert:| Score-Bereich | Interpretation |
| :-: | - |
| **90%+** | Starke Übereinstimmung — sehr wahrscheinlich dieselbe Person |
| **70–89%** | Mögliche Übereinstimmung — erfordert möglicherweise eine manuelle Prüfung |
| **Unter 70%** | Wahrscheinlich unterschiedliche Personen |Ihre konfigurierten Übereinstimmungsschwellenwerte bestimmen, welche Ergebnisse gekennzeichnet werden.**4. Bereitstellung der Ergebnisse**Das System gibt einen umfassenden Ergebnissatz zurück:- **Rangliste** potenzieller Übereinstimmungen, sortiert nach Ähnlichkeitswert
- **Übereinstimmungsdetails** einschließlich Sitzungs-ID, Verifizierungsdatum und Anbieterdaten
- **Ähnlichkeitsprozentsatz** für jede Übereinstimmung
- **Übereinstimmungsbilder**, verfügbar für die visuelle Prüfung
- **Sperrlistenstatus**, der angibt, ob das übereinstimmende Gesicht auf der Sperrliste steht## Gelöschte Sitzungen und aufbewahrte biometrische TemplatesDas Löschen einer Sitzung löscht standardmäßig deren Gesichts-Embedding, sodass die Person aus dem Index herausfällt und sich erneut ohne Duplikatsmarkierung verifizieren kann. Anwendungen, die Sitzungen kurz nach der Genehmigung löschen, aber dennoch wiederholte Registrierungen erkennen müssen, können die [Aufbewahrung biometrischer Templates](https://docs.didit.me/de/console/data-retention.md#aufbewahrung-biometrischer-templates) aktivieren. Didit behält dann nach dem Löschen der Sitzung ein bildfreies biometrisches Template, das an den Benutzer gekoppelt ist, und dieses Template nimmt genau wie das Gesicht einer aktiven Sitzung an der Gesichtssuche und der automatischen Duplikatserkennung teil.Ein Treffer auf ein aufbewahrtes Template wird mit `source: "retained_template"`, der `vendor_user_id` und den `vendor_data` des zugehörigen Benutzers sowie einer `biometric_template_id` gemeldet. Er enthält keine Sitzungs-ID, kein Übereinstimmungsbild, keine Identitätsdetails und keinen Sitzungsstatus, da die Sitzung, die das Gesicht erzeugt hat, nicht mehr existiert. Aufbewahrte Templates werden niemals auf eine Sperrliste gesetzt; Gesichts-Sperrlisteneinträge behalten ihren eigenen unabhängigen biometrischen Eintrag.Das Template bleibt bis zu seinem geplanten Ablauf, der Benutzerlöschung, einer Anfrage zur Löschung aus Datenschutzgründen oder einer expliziten Bereinigung über die [Biometric Templates API](https://docs.didit.me/de/management-api/biometric-templates/overview.md) oder **Lists → Biometric templates** in der Console bestehen.## ÄhnlichkeitsprozentsatzDer Ähnlichkeitsprozentsatz ist die zentrale Kennzahl zur Bestimmung potenzieller Übereinstimmungen:- **Hoher Prozentsatz (in der Regel 90% und mehr)**: Weist auf eine hohe Wahrscheinlichkeit hin, dass die Gesichter zur selben Person gehören.
- **Mittlerer Prozentsatz (70–89%)**: Weist auf mögliche Übereinstimmungen hin, die möglicherweise eine weitere Prüfung erfordern.
- **Niedriger Prozentsatz (unter 70%)**: Weist wahrscheinlich auf unterschiedliche Personen hin.Der genaue Schwellenwert dafür, was als „Übereinstimmung“ gilt, kann basierend auf Ihren Sicherheitsanforderungen konfiguriert werden. Eine Erhöhung des Schwellenwerts reduziert falsch-positive Ergebnisse, kann jedoch die Anzahl falsch-negativer Ergebnisse erhöhen.## Anwendungsfälle- **Betrugsprävention**: Identifizieren Sie Benutzer, die versuchen, mehrere Konten zu erstellen
- **Erweitertes KYC**: Fügen Sie Ihrem KYC-Prozess eine zusätzliche Verifizierungsebene hinzu
- **Regulierungskonformität**: Erfüllen Sie Anforderungen zur Erkennung doppelter Konten
- **Zugangskontrolle**: Überprüfen Sie die Authentizität von Benutzern für Hochsicherheitsbereiche
- **Strafverfolgung**: Unterstützen Sie autorisierte Behörden bei der Identifizierung von Personen von Interesse


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