> ## 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-Bericht: Ähnlichkeitswert als JSON > Didits 1:1-Gesichtsabgleich-Bericht liefert Status, Ähnlichkeitswert, Bild-URLs und Warnungen direkt in den API-Antworten. ## Übersicht Der **Bericht zum Gesichtsabgleich** erfasst einen biometrischen 1:1-Abgleich zwischen dem während der Liveness-Erkennung aufgenommenen Live-Selfie und einem Referenzbild – meist das aus dem Ausweisdokument extrahierte Porträt. Er gibt einen einzelnen Ähnlichkeits-Score von 0–100, signierte URLs für die beiden verglichenen Bilder, die Quellsitzung für das Referenzbild sowie alle durch den Abgleich ausgelösten Warnungen zurück. Der Bericht wird erstellt, nachdem der Benutzer sowohl den Liveness-Schritt als auch den Dokumentenschritt in einem Workflow abgeschlossen hat (oder bei porträtbasierten Workflows wie der biometrischen Authentifizierung nach der Liveness-Erkennung allein) oder direkt über die eigenständige [Gesichtsabgleich-API](https://docs.didit.me/de/standalone-apis/face-match.md), wenn Sie selbst zwei beliebige Gesichtsbilder übergeben. Jeder Bericht enthält einen eigenen `status` – unabhängig vom Gesamtsitzungsstatus –, der widerspiegelt, wie der Schritt des Gesichtsabgleichs allein abgeschlossen wurde: * **Genehmigt** — `score` liegt über dem Prüfschwellenwert und es wurde keine Warnung zur automatischen Ablehnung ausgelöst. * **In Prüfung** — `score` liegt zwischen dem Ablehnungs- und dem Prüfschwellenwert, oder es konnte kein Score berechnet werden und `face_match_not_computed_action` ist `REVIEW`. * **Abgelehnt** — `score` liegt bei oder unter dem Ablehnungsschwellenwert, `NO_REFERENCE_IMAGE` wurde ausgelöst oder es konnte kein Score berechnet werden und `face_match_not_computed_action` ist `DECLINE`. * **Erneute Einreichung angefordert** — ein Prüfer hat über die Konsole angefordert, dass der Benutzer diesen Schritt erneut einreicht. * **Nicht abgeschlossen** — der Schritt des Gesichtsabgleichs hat noch kein Ergebnis geliefert (einschließlich während der Benutzer eine fehlgeschlagene Erfassung wiederholt). ## Wo er in API-Antworten erscheint Der Bericht zum Gesichtsabgleich wird im Array `face_matches[]` geliefert – **immer als JSON-Array**, niemals als einzelnes `face_match`-Objekt. Er ist `null`, bis mindestens ein Schritt des Gesichtsabgleichs Daten erzeugt hat, und mehrere Einträge erscheinen, wenn ein Workflow den Gesichtsabgleich mehr als einmal ausführt. Ein Workflow für die [Adaptive Age Verification](https://docs.didit.me/de/core-technology/age-estimation/overview.md#adaptive-altersschätzung) füllt ihn ebenfalls aus, wenn der Fallback zur Ausweisverifizierung ausgeführt wird: Dieser Eintrag gibt den Altersschätzungs-Knoten als seine `node_id` an, da der Workflow keinen eigenen Gesichtsabgleich-Knoten besitzt. * **Sitzungsentscheidungs-API** — `GET /v3/session/{sessionId}/decision/` gibt `face_matches[]` auf oberster Ebene zurück. Siehe [Sitzungsentscheidung abrufen](https://docs.didit.me/de/sessions-api/retrieve-session.md). * **Webhooks** — `session.status.updated`-Payloads enthalten dasselbe `face_matches[]`-Array, sobald der Schritt Daten erzeugt hat. Siehe [Webhooks](https://docs.didit.me/de/integration/webhooks.md). * **Eigenständige Gesichtsabgleich-API** — für direkte 1:1-Abgleiche siehe [Eigenständige Gesichtsabgleich-API](https://docs.didit.me/de/standalone-apis/face-match.md). > [!NOTE] > > Lesen Sie `response.face_matches[0]` aus und iterieren Sie über das Array – die singuläre `face_match`-Struktur, auf die in einigen älteren Tutorials verwiesen wurde, existiert am v3-Entscheidungs-Endpoint nicht. ## Schema Das kanonische Schema für jedes Feld befindet sich auf der Referenzseite [Datenmodelle](https://docs.didit.me/de/reference/data-models.md#gesichtsabgleich). Die folgenden Felder spiegeln dieses kanonische Schema wider. | Feld | Typ | Beschreibung | | - | - | - | | `status` | `"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"` | Status des Gesichtsabgleich-Schritts (`FeatureStatusChoices`). | | `node_id` | string \| null | Workflow-Graphknoten, der diesen Bericht erzeugt hat. | | `score` | number 0–100 \| null | Biometrischer Ähnlichkeits-Score, gerundet auf 2 Dezimalstellen. `null`, wenn kein Abgleich möglich war. | | `source_image_session_id` | string \| null | UUID der Sitzung, deren gespeichertes Porträt das Referenzbild (Quellbild) geliefert hat – gesetzt bei porträtbasierten Abläufen (biometrische Authentifizierung oder ein bei der Sitzungserstellung übergebenes Porträt). `null`, wenn das Referenzbild das in derselben Sitzung aufgenommene Dokumentenporträt ist. | | `source_image` | string (signierte URL) | Das Referenzbild (üblicherweise das Dokumentenporträt). Kurzlebige signierte URL – zeitnah herunterladen, niemals die URL dauerhaft speichern. | | `target_image` | string (signierte URL) | Das Zielbild (üblicherweise das Liveness-Selfie). Kurzlebige signierte URL – zeitnah herunterladen, niemals die URL dauerhaft speichern. | | `warnings[]` | array | Warnungen auf Modulebene. Jeder Eintrag enthält `feature` (immer `"FACEMATCH"`), `risk`, `additional_data`, `log_type`, `short_description`, `long_description` und `node_id` – siehe [Warnungen beim Gesichtsabgleich](https://docs.didit.me/de/core-technology/face-match/warnings-face-match.md). | ## Statuswerte | Status | Bedeutung | Nachgelagerte Auswirkung | | - | - | - | | `Approved` | Score liegt über dem Prüfschwellenwert und es wurde keine Warnung zur automatischen Ablehnung ausgelöst. | Zählt als erfolgreicher Gesichtsabgleich. | | `In Review` | Score liegt über dem Ablehnungsschwellenwert, aber bei oder unter dem Prüfschwellenwert, oder es konnte kein Score berechnet werden (`FACE_MATCH_NOT_COMPUTED`, beispielsweise nach einer nicht dokumentbasierten Abfrage, bei der keine Referenz vorhanden war), wobei `face_match_not_computed_action` auf `REVIEW` gesetzt ist. | Die Sitzung wechselt ebenfalls zu `In Review`, bis ein Prüfer eingreift. | | `Declined` | Score liegt bei oder unter dem Ablehnungsschwellenwert, `NO_REFERENCE_IMAGE` wurde ausgelöst oder es konnte kein Score berechnet werden, wobei `face_match_not_computed_action` auf `DECLINE` gesetzt ist. | Die Sitzung wird abgelehnt, es sei denn, eine andere genehmigte Verzweigung erfüllt den Workflow. | | `Resub Requested` | Ein Prüfer hat über die Konsole eine erneute Einreichung dieses Schritts angefordert. | Der Benutzer wird aufgefordert, die Aufnahme erneut durchzuführen. | | `Not Finished` | Der Schritt des Gesichtsabgleichs hat kein Ergebnis geliefert (eine Eingabe fehlte, der Workflow hat den Vergleichsschritt nie erreicht oder der Benutzer befindet sich noch in der Wiederholungsschleife für die Erfassung). | Die Verzweigung wurde nicht abgeschlossen. | Fehlschläge aufgrund geringer Ähnlichkeit werden wiederholt, bevor der Status festgelegt wird: Der Benutzer kann bis zu `face_match_max_attempts` Erfassungsversuche durchführen (standardmäßig 3), und nur der Score des letzten Versuchs wird angewendet. Benutzerdefinierte Statusregeln, die am Workflow-Knoten konfiguriert sind, können den resultierenden Status weiter anpassen und ihn mit dem aus dem Score abgeleiteten Status gemäß der Rangfolge `Declined` > `In Review` > `Approved` kombinieren. ## Beispiele ### Genehmigt – eindeutige Übereinstimmung ```json theme={null} { "face_matches": [ { "status": "Approved", "node_id": "feature_face_match_1", "score": 96.42, "source_image_session_id": null, "source_image": "https:///source-image.jpg", "target_image": "https:///target-image.jpg", "warnings": [] } ] } ``` ### In Prüfung – grenzwertige Ähnlichkeit ```json theme={null} { "face_matches": [ { "status": "In Review", "node_id": "feature_face_match_1", "score": 65.43, "source_image_session_id": null, "source_image": "https:///source-image.jpg", "target_image": "https:///target-image.jpg", "warnings": [ { "feature": "FACEMATCH", "risk": "LOW_FACE_MATCH_SIMILARITY", "additional_data": null, "log_type": "warning", "short_description": "Low face match similarity", "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.", "node_id": "feature_face_match_1" } ] } ] } ``` ### Abgelehnt – kein Referenzbild für den Abgleich vorhanden ```json theme={null} { "face_matches": [ { "status": "Declined", "node_id": "feature_face_match_1", "score": null, "source_image_session_id": null, "source_image": null, "target_image": "https:///target-image.jpg", "warnings": [ { "feature": "FACEMATCH", "risk": "NO_REFERENCE_IMAGE", "additional_data": null, "log_type": "error", "short_description": "No source image found for performing face match", "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.", "node_id": "feature_face_match_1" } ] } ] } ``` ## Sicherheitshinweis Die signierten URLs für `source_image` und `target_image` stellen biometrische Daten dar und laufen nach einem kurzen Gültigkeitsfenster ab. Behandeln Sie sie als kurzlebig: Cachen Sie sie nicht und stellen Sie sie nicht öffentlich bereit. In der Regel benötigt Ihre Anwendung lediglich `status` und `score` – speichern Sie so wenig wie möglich, um die Menge biometrischer Daten auf Ihren Servern zu minimieren. ## Verwandte Themen * [Warnungen beim Gesichtsabgleich](https://docs.didit.me/de/core-technology/face-match/warnings-face-match.md) — Vollständiges Warnungs-Enum, Ursachen und Behebung. * [Liveness-Bericht](https://docs.didit.me/de/core-technology/liveness/report-liveness.md) — Der vorgelagerte Schritt, der das Zielbild erfasst. * [Webhooks](https://docs.didit.me/de/integration/webhooks.md) — Auf `session.status.updated` lauschen, um den Bericht zu empfangen. * [Datenmodelle – Gesichtsabgleich](https://docs.didit.me/de/reference/data-models.md#gesichtsabgleich) — Kanonisches Schema mit allen Feldern. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.