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

# Gesichtsabgleich 1:1-API: Selfie- und Ausweisabgleich

> Didit vergleicht Selfies mit Ausweisfotos via KI: $0.05/Aufruf, $10 gratis/Monat, Übereinstimmungswert in sub-2s für KYC und Onboarding.

Didit Face Match vergleicht zwei Gesichter im 1:1-Vergleich – üblicherweise das Selfie aus einer Liveness-Erkennung mit dem Porträt auf dem Ausweisdokument des Benutzers – und liefert einen Übereinstimmungswert von 0 bis 100 zurück. Die von Ihnen festgelegten Schwellenwerte bestimmen, ob die Prüfung bestanden wird; die eigenständige API `POST /v3/face-match/` lehnt standardmäßig einen Wert von 30 oder weniger ab.In der Academy-Lektion zum Lesen von Verifizierungsergebnissen behandelt das Kapitel bei Minute 6:16 die Gesichtsabgleich-Prüfung innerhalb einer echten Sitzung.[Face match — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=376\&rel=0\&playsinline=1)

Prompt zur Gesichtsabgleich-Integration
        Prompt in die Zwischenablage kopieren



      
      

\<pre>

\````# Goal
Integrate Didit Face Match (1:1 — compare two faces) into your app. Pick ONE mode.

\# Mode A — Session-based
Use this when the user goes through a hosted Didit flow. Face Match runs alongside ID Verification (uses the document portrait as ref) and Liveness (uses the live selfie as user_image).

1\. Add the FACE_MATCH feature to a workflow that also runs ID_VERIFICATION + LIVENESS (Business Console or POST /v3/workflows/).
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open session.url for the user (or mount the Web/Mobile SDK).
4\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

Decision surface: `face_matches[]` array on the decision payload.

\# Mode B — Standalone API (server-to-server)
Use when you already have two images and want a one-shot 1:1 similarity score.

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

Required: `user_image` (live capture) and `ref_image` (reference portrait). JPEG/PNG/WebP/TIFF, max 5 MB each.

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/face-match/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'ref_image=@./id_portrait.jpg' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```
Returns: { request_id, face_match: { status, score (0-100), user_image: {entities}, ref_image: {entities}, warnings: [...] } }. `status` is "Approved" when score > face_match_score_decline_threshold (default 30), else "Declined".

\# Status enum (per face_matches[].status / face_match.status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"

\# Warnings (LogWarningChoices.FACEMATCH)
warnings[] risk codes include:
LOW_FACE_MATCH_SIMILARITY, NO_REFERENCE_IMAGE, NO_FACE_DETECTED, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/face-match/warnings-face-match.

\# Failure modes to handle
\- HTTP 403 — out of credits.
\- HTTP 400 — missing user_image or ref_image, file too large, unsupported extension.
\- status="Declined" with LOW_FACE_MATCH_SIMILARITY — the two faces do not match; do not approve.
\- NO_REFERENCE_IMAGE / NO_FACE_DETECTED — capture problems; ask the user to retry.

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

\</pre>



      
      

Einfügen in

![Übersicht der Schritte zur Ausweisverifizierung](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/id-verification-steps.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=42c64546f3495000d7ea3b10c4b5fa50)## Wiederholungsversuche und umsetzbares FeedbackIn einer Didit-Sitzung führt ein Gesichtsabgleich, der aufgrund eines **behebbaren Aufnahmeproblems** fehlschlägt (das Selfie ist zu dunkel, unscharf, nicht zentriert oder die Übereinstimmung liegt im Grenzbereich), nicht sofort zu einer Ablehnung. Der Benutzer wird aufgefordert, **mit Hilfestellung einen neuen Versuch zu unternehmen**, bis zu einer konfigurierbaren Anzahl von Versuchen – dasselbe Modell wie bei [Liveness-Erkennung](https://docs.didit.me/de/core-technology/liveness/overview.md).* **Versuchsbudget** – `face_match_max_attempts` steuert die Gesamtzahl der Gesichtsabgleich-Übermittlungen pro Sitzung. Standardwert ist **3** (ein erster Versuch plus zwei Wiederholungsversuche), konfigurierbar pro Workflow-Knoten (Bereich 1–3).

* **Feedback bei Wiederholung** – solange noch Versuche verbleiben, hält ein Fehler, der einen Wiederholungsversuch zulässt, den Benutzer im jeweiligen Schritt und gibt `feedback_codes` zurück (die Web- und Mobile-SDKs zeigen diese automatisch als Hilfestellungen an):

  ```json theme={null}
  {
    "detail": "Make sure your face matches your document photo, improve lighting and try again.",
    "error": "LOW_FACE_MATCH_SIMILARITY",
    "feedback_codes": ["LOW_FACE_MATCH_SIMILARITY"],
    "attempts_used": 1,
    "max_attempts": 3
  }
  ```

* **Erschöpfung des Budgets** – sobald das Versuchsbudget aufgebraucht ist, wird der berechnete Status angewendet (`Declined` oder `In Review`).> [!NOTE]
>
> Wiederholungsversuche gelten nur für den **Sitzungsablauf**. Der eigenständige Endpoint `POST /v3/face-match/` ist zustandslos und erlaubt nur einen einzigen Versuch – er gibt den Übereinstimmungswert direkt ohne Versuchsbudget zurück.## So funktioniert es**1. Intelligente Erfassung**Starten Sie den Verifizierungsprozess mühelos mit unserem intuitiven, KI-gestützten Erfassungssystem.Benutzer laden ihre Ausweisdokumente hoch oder fotografieren sie mit Echtzeit-Unterstützung:| Funktion | Beschreibung |
| - | - |
| **Automatische Erkennung** | Identifiziert Dokumenttyp und Ausstellungsland automatisch |
| **Echtzeit-Anleitung** | Visuelle Hinweise für optimale Positionierung, Beleuchtung und Schärfe |
| **Intelligente Aufnahme** | Automatische Erfassung bei idealen Bedingungen – keine manuellen Wiederholungen erforderlich |
| **Breite Unterstützung** | Reisepässe, Führerscheine, Personalausweise und Aufenthaltstitel |> [!NOTE]
>
> *Warum es wichtig ist*: Unsere intelligente Erfassung reduziert Reibungsverluste für Benutzer und stellt hochwertige Aufnahmen beim ersten Versuch sicher, was die Konversionsrate und das Vertrauen steigert.**2. Erweiterte Datenverarbeitung**Extrahieren und validieren Sie Identitätsdaten mit unübertroffener Präzision.**Datenextraktion** – Modernste Technologie verarbeitet alle zentralen Felder:| Funktion | Details |
| - | - |
| **Feldextraktion** | Vollständiger Name, Geburtsdatum, Dokumentnummer, Ausstellungs-/Ablaufdatum, Staatsangehörigkeit und mehr |
| **OCR** | Hochpräzise optische Zeichenerkennung für Text |
| **MRZ-Parsing** | Auslesen der maschinenlesbaren Zone (MRZ) und Dekodierung von Barcodes |**Datenvalidierung**:* Gleicht Daten zwischen visuellen Zonen, MRZ und Barcodes auf Konsistenz ab
* Format- und Musterabgleich zur Erkennung von Anomalien
* Echtzeit-Abfragen bei staatlichen Datenbanken (sofern zulässig) für verbindliche Verifizierungen> [!NOTE]
>
> *Warum es wichtig ist*: Eine umfassende Datenverarbeitung gewährleistet Genauigkeit und eliminiert Fehler, sodass Sie sich auf jede Verifizierung verlassen können.**3. Erweiterte Analyse**Unser KI-gestütztes System führt umfassende Prüfungen durch:- Verifizierung der Dokumentenechtheit
- Manipulationserkennung und Bildintegritätsanalyse
- Validierung von Sicherheitsmerkmalen (Hologramme, Wasserzeichen etc.)
- Vorlagenabgleich mit einer zertifizierten Datenbank**Dokumenten-Liveness-Erkennung** verhindert Betrug durch:| Angriffsart | Beschreibung |
| - | - |
| **Bildschirmaufnahmen** | Digitale Dokumente, die von einem Bildschirm abfotografiert wurden |
| **Bildschirmwiedergabe** | Fotos von Dokumenten, die auf Bildschirmen angezeigt werden |
| **Gedruckte Kopien** | Physische Reproduktionen von Originaldokumenten |
| **Manipulierte Porträts** | Manipulierte Dokumente mit ausgetauschten oder bearbeiteten Fotos |**4. Nahtlose Ergebnisse und Integration**Erhalten Sie sofort umsetzbare Erkenntnisse mit flexiblen Bereitstellungsoptionen.**Echtzeitergebnisse**:| Kanal | Beschreibung |
| - | - |
| **Dashboard** | Sofortige Aktualisierungen über ein intuitives Dashboard |
| **Webhooks** | Sofortige Webhook-Benachrichtigungen für automatisierte Workflows |
| **REST-API** | Nahtlose Integration in Ihre bestehenden Systeme |**Umfassende Berichterstattung**:* Detaillierte PDF-Berichte mit Verifizierungsergebnissen und Nachweisen
* Audit-Logs für Compliance und Dokumentationspflichten
* Anpassbare Optionen zur Abstimmung auf Ihre betrieblichen Anforderungen> [!NOTE]
>
> *Warum es wichtig ist*: Schnelle, leicht zugängliche Ergebnisse ermöglichen es Ihrem Team, zügig zu handeln und gleichzeitig einen sicheren, revisionssicheren Prozess aufrechtzuerhalten.***## DokumentanforderungenFür einen optimalen Verifizierungserfolg müssen Dokumente die folgenden Standards erfüllen:#### Allgemeine Anforderungen- Behördlich ausgestellt und innerhalb des konfigurierten Gültigkeitszeitraums gültig
- Physisch unbeschädigt (keine Schäden, Kratzer oder Flecken, die Details verdecken)
- Alle wesentlichen Angaben (vollständiger Name, Geburtsdatum, MRZ etc.) deutlich lesbar
- Konsistente Daten über alle eingereichten Dokumente hinweg#### Bildanforderungen- Originales Echtzeitfoto (keine Screenshots, Scans oder digitalen Kopien)
- Unterstützte Formate: JPG, JPEG, PNG, PDF
- Maximale Dateigröße: 5MB
- Farbbild, auf dem alle Dokumentecken sichtbar sind
- Frei von Blendungen, Schatten, digitaler Bearbeitung oder Manipulationen
- Physische Dokumente erforderlich (digitale Ausweise werden nur in ausgewählten Regionen unterstützt, in denen sie offiziell anerkannt sind)## Zusätzliche Einstellungen nach Land und DokumenttypKonfigurieren Sie feingranulare Regeln pro Land und Dokumenttyp direkt in der Konsole. Mit diesen Steuerelementen passen Sie Akzeptanzkriterien und Transkriptionspräferenzen an Ihre Compliance-Anforderungen an.![Didit Gesichtsabgleich – Erweiterte Einstellungen für Ähnlichkeitsschwellenwerte und Akzeptanzregeln](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/id-additional-settings.jpeg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=4238b10a404795a61926fbdf1a3adc20)* **Ablaufmodus**: Wählen Sie, wie Dokumente mit abgelaufenem Ablaufdatum behandelt werden sollen.
  * **Abgelaufene ablehnen**: Liegt das Ablaufdatum des Dokuments vor dem heutigen Tag, wird es als abgelaufen markiert und abgelehnt.
  * **Abgelaufene zulassen**: Dokumente mit abgelaufenem Ablaufdatum werden weder markiert noch blockiert.
* **Bevorzugtes Zeichenformat**: Wählen Sie aus, wie extrahierte Namen und Felder normalisiert werden sollen.
  * **Lateinische Schriftzeichen bevorzugen (A–Z)**: Beispiel: "Mohammed"
  * **Ursprüngliches Schriftsystem bevorzugen (nicht-lateinisch)**: Beispiel: "محمد"
* **Regionale Unterstützung und Untertypen**: Aktivieren Sie Dokumente nach Region und legen Sie zulässige Untertypen fest, wenn ein Dokumenttyp viele Varianten umfasst.
  * Beispiel: Wählen Sie bei Führerscheinen aus den Vereinigten Staaten genau die Untertypen aus, die Sie akzeptieren (z. B. Arizona Commercial Driver License, Indiana Operator License (REAL ID), New York Enhanced Driver License usw.).
  * Verwenden Sie das Steuerelement "Akzeptierte Untertypen", um schnell viele Varianten einzuschließen oder auszuschließen (z. B. "128 ausgewählt").> Tipp: Diese Einstellungen gelten pro Land und Dokumenttyp, sodass Sie in bestimmten Märkten streng und in anderen permissiver vorgehen können.


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