> ## 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. # Liveness-Bericht: Score, Methode & Treffer > Der Liveness-Bericht von Didit liefert Status, Konfidenzwert, Erkennungsmethode, Altersschätzung und sitzungsübergreifenden Gesichtsabgleich. ## Übersicht Der **Liveness-Bericht** erfasst alles, was Didit während der Überprüfung beobachtet hat, um zu bestätigen, dass sich eine echte, lebende Person vor der Kamera befand – kein ausgedrucktes Foto, keine Bildschirmwiedergabe oder kein Deepfake. Er umfasst die Liveness-Methode, einen Konfidenzwert von 0–100, das Referenz-Selfie und das Aufnahmevideo, eine optionale Altersschätzung, Qualitätsmetriken für passive Liveness sowie sitzungsübergreifende Gesichtsabgleiche mit dem Verlauf und der Sperrliste Ihrer Anwendung. Der Bericht wird erstellt, nachdem der Benutzer den Liveness-Schritt in einem Workflow abgeschlossen hat (oder den eigenständigen Gesichts-Endpoint aufgerufen hat). Didit führt eine von drei Liveness-Methoden aus (aktives 3D, Flashing oder passiv), bewertet die Aufnahme, prüft auf bekannte Spoofing-Muster und vergleicht das Gesicht biometrisch mit jedem anderen Gesicht, das in Ihrer Anwendung erfasst wurde. Jeder Bericht enthält seinen eigenen `status` – unabhängig vom allgemeinen Sitzungsstatus –, der widerspiegelt, wie der Liveness-Schritt allein abgeschlossen wurde: * **Genehmigt** – Gesicht erkannt, Liveness-Score liegt über dem Schwellenwert für die Überprüfung, keine Warnung für automatische Ablehnung ausgelöst. * **In Prüfung** – eine oder mehrere Warnungen ausgelöst, die zur Prüfung weitergeleitet wurden, oder der Score liegt auf oder unter dem Schwellenwert für die Überprüfung, aber über dem Ablehnungsschwellenwert. * **Abgelehnt** – eine Bedingung für eine automatische Ablehnung wurde ausgelöst (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST` oder die Altersrisiken bei Abläufen mit Altersschätzung), eine konfigurierbare Warnung wurde zur Ablehnung weitergeleitet oder der Score liegt auf oder unter dem Ablehnungsschwellenwert. * **Nicht abgeschlossen** – der Benutzer hat den Liveness-Schritt nicht abgeschlossen. ## Wo er in API-Antworten erscheint Der Liveness-Bericht erscheint als `liveness_checks[]` in `GET /v3/session/{sessionId}/decision/` – **immer als JSON-Array**, niemals als einzelnes `liveness`-Objekt. Mehrere Einträge erscheinen, wenn ein Workflow die Liveness-Prüfung mehr als einmal ausführt (beispielsweise eine primäre Prüfung plus eine erneute Aufnahme). * **Sitzungsentscheidungs-API** – `GET /v3/session/{sessionId}/decision/` gibt `liveness_checks[]` auf oberster Ebene zurück. Siehe [Sitzungsentscheidung abrufen](https://docs.didit.me/de/sessions-api/retrieve-session.md). * **Webhooks** – Payloads von `session.status.updated` enthalten dasselbe `liveness_checks[]`-Array, sobald der Schritt Daten geliefert hat. Siehe [Webhooks](https://docs.didit.me/de/integration/webhooks.md). * **Eigenständige Liveness-API** – siehe [Eigenständige Liveness-API](https://docs.didit.me/de/standalone-apis/passive-liveness.md). > [!NOTE] > > Lesen Sie `response.liveness_checks[0]` und iterieren Sie über das Array – die einzelne `liveness`-Struktur, auf die in einigen älteren Tutorials verwiesen wurde, existiert im v3-Entscheidungs-Endpoint nicht. ## Schema Das kanonische Feld-für-Feld-Schema befindet sich auf der Referenzseite [Datenmodelle](https://docs.didit.me/de/reference/data-models.md#liveness-prüfung). Die nachfolgenden Felder spiegeln dieses kanonische Schema wider. | Feld | Typ | Beschreibung | | - | - | - | | `status` | `"Approved" \| "Declined" \| "In Review" \| "Not Finished" \| "Resub Requested"` | Status des Liveness-Schritts (siehe unten). | | `node_id` | string \| null | Knoten des Workflow-Graphen, der diesen Bericht erzeugt hat. | | `method` | `"ACTIVE_3D" \| "FLASHING" \| "PASSIVE"` | Die Liveness-Methode, mit der diese Erfassung durchgeführt wurde. | | `score` | number 0–100 \| null | Liveness-Konfidenzwert, gerundet auf 2 Dezimalstellen. | | `reference_image` | string (signierte URL) \| null | Aus der Erfassung extrahiertes Referenz-Selfie. Signierte URL mit zeitlich begrenzter Gültigkeit. | | `video_url` | string (signierte URL) \| null | Vollständiges Video der Liveness-Erfassung (aktive Methoden). Signierte URL mit zeitlich begrenzter Gültigkeit. | | `age_estimation` | number \| null | Geschätztes Alter in Jahren des größten Gesichts im Referenzbild. | | `face_quality` | number 0–100 \| null | Gesichtsqualität bei passiver Liveness, normalisiert als Prozentsatz. Wird nur ausgefüllt, wenn `method = "PASSIVE"`. | | `face_luminance` | number 0–100 \| null | Gesichtshelligkeit bei passiver Liveness, normalisiert von 0–255 auf einen Prozentsatz. Wird nur ausgefüllt, wenn `method = "PASSIVE"`. | | `matches[]` | array | Sitzungsübergreifende Gesichtsabgleiche (siehe unten). | | `warnings[]` | array | Warnungen auf Modulebene – siehe [Liveness-Warnungen](https://docs.didit.me/de/core-technology/liveness/warnings-liveness.md). Jeder Eintrag entspricht der Struktur des [Warning-Objekts](https://docs.didit.me/de/reference/data-models.md#warnungsobjekt) (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`). | ### Sitzungsübergreifende Gesichtsabgleiche `matches[]` listet die Gesichter aus dem Verlauf Ihrer Anwendung auf, die den Schwellenwert für die biometrische Ähnlichkeit im Vergleich zu diesem Selfie überschritten haben – bis zu 5 Einträge, Gesichter auf Sperr- und Zulassungslisten zuerst, danach in absteigender Reihenfolge nach Ähnlichkeit. Als Kandidaten kommen Gesichter auf Sperrlisten, Gesichter auf Zulassungslisten, Gesichter aus Sitzungen mit dem Status `Approved` sowie für Ihre Vendor-Benutzer importierte Gesichter infrage. Gesichter, die demselben Benutzer gehören (gleiche `vendor_data` oder derselbe Vendor-Benutzer, sofern verfügbar), werden von der **gesamten** Suche ausgeschlossen – sowohl von der Duplikaterkennung als auch vom Sperrlisten-Screening. Jeder Eintrag enthält: | Feld | Typ | Beschreibung | | - | - | - | | `session_id` | string (UUID) \| null | Die übereinstimmende Sitzung. `null`, wenn `source` den Wert `imported` oder `list_entry` hat. | | `session_number` | number \| null | Fortlaufende Sitzungsnummer der übereinstimmenden Sitzung. `null` für Quellen, die keine Sitzungen sind. | | `similarity_percentage` | number 0–100 | Biometrischer Ähnlichkeitswert, begrenzt auf 0–100. | | `vendor_data` | string \| null | Ihre Referenzdaten aus der übereinstimmenden Sitzung (oder vom Vendor-Benutzer bei importierten Gesichtern). | | `verification_date` | string (ISO 8601) \| null | Zeitpunkt, zu dem die übereinstimmende Sitzung (oder das importierte Gesicht) erstellt wurde. | | `user_details` | object \| null | `{ full_name, document_type, document_number }` aus dem KYC der übereinstimmenden Sitzung. Bei importierten Gesichtern wird nur `full_name` ausgefüllt (die beiden Dokumentenfelder sind `null`); `null`, wenn keine Details hinterlegt sind. | | `match_image_url` | string (signierte URL) \| null | Referenzgesicht aus der übereinstimmenden Sitzung, dem importierten Gesicht oder dem Listeneintrag. | | `status` | string \| null | Status der übereinstimmenden Sitzung (z. B. `"Approved"`). `null` für Quellen, die keine Sitzungen sind. | | `is_blocklisted` | boolean | `true`, wenn sich das übereinstimmende Gesicht auf Ihrer Gesichts-Sperrliste befindet. | | `is_allowlisted` | boolean | `true`, wenn sich das übereinstimmende Gesicht auf Ihrer Gesichts-Zulassungsliste befindet (Aktionen für doppelte Gesichter werden übersprungen). | | `api_service` | string \| null | Wird gesetzt, wenn das übereinstimmende Gesicht aus einem eigenständigen API-Aufruf stammt (z. B. `"PASSIVE_LIVENESS"`); `null` für Workflow-Sitzungen und Quellen, die keine Sitzungen sind. | | `source` | `"session" \| "imported" \| "list_entry"` | Herkunft des übereinstimmenden Gesichts: eine andere Verifizierungssitzung, ein für einen Vendor-Benutzer hochgeladenes Gesicht oder ein von der Organisation verwaltetes Gesicht auf einer Zulassungs-/Sperrliste. | ## Statuswerte Die Statuswerte stammen aus dem gemeinsamen Funktionsstatus-Enum (`FeatureStatusChoices`). | Status | Bedeutung | Nachgelagerte Auswirkung | | - | - | - | | `Approved` | Gesicht erkannt, Liveness-Score über dem Schwellenwert für eine Prüfung, keine Warnung zur automatischen Ablehnung ausgelöst. | Zählt als erfolgreiche Liveness-Prüfung. | | `In Review` | Score liegt auf dem Prüfungs-Schwellenwert oder darunter, aber über dem Ablehnungs-Schwellenwert, oder eine Warnung wurde ausgelöst, die zur Prüfung weiterleitet. | Die Sitzung wechselt ebenfalls zu `In Review`, bis ein Prüfer eine Aktion vornimmt. | | `Declined` | Ein Risiko mit automatischer Ablehnung wurde ausgelöst (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST` oder die Altersrisiken bei Abläufen zur Altersschätzung), eine konfigurierbare Warnung wurde auf Ablehnung gesetzt, oder der Score liegt auf dem Ablehnungs-Schwellenwert oder darunter. | Die Sitzung wird abgelehnt, es sei denn, eine andere genehmigte Verzweigung erfüllt den Workflow. | | `Not Finished` | Der Benutzer hat den Liveness-Schritt abgebrochen (oder ein wiederholbarer Erfassungsfehler wartet auf einen weiteren Versuch). | Die Liveness-Verzweigung hat kein Ergebnis geliefert. | | `Resub Requested` | Ein Prüfer hat über die Konsole eine erneute Einreichung dieses Schritts angefordert. | Vorübergehend – dieser Status wird ersetzt, sobald der Benutzer die Erfassung erneut durchführt. | ## Beispiele ### Genehmigt – Einwandfreie Active-3D-Erfassung ```json theme={null} { "liveness_checks": [ { "status": "Approved", "node_id": "liveness_primary", "method": "ACTIVE_3D", "score": 92.4, "reference_image": "https:///.../reference.jpg?signature=...", "video_url": "https:///.../liveness.mp4?signature=...", "age_estimation": 24.3, "face_quality": null, "face_luminance": null, "matches": [], "warnings": [] } ] } ``` ### In Prüfung – Passive Liveness, Erfassung mit geringer Qualität und mögliches Duplikat ```json theme={null} { "liveness_checks": [ { "status": "In Review", "node_id": "liveness_primary", "method": "PASSIVE", "score": 76.1, "reference_image": "https:///.../reference.jpg?signature=...", "video_url": null, "age_estimation": 31.0, "face_quality": 12.4, "face_luminance": 18.7, "matches": [ { "session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f", "session_number": 123, "similarity_percentage": 96.8, "vendor_data": "user-555", "verification_date": "2024-07-15T10:23:45Z", "user_details": { "full_name": "John Smith", "document_type": "Passport", "document_number": "SAMPLE-DOC-12345" }, "match_image_url": "https:///.../matched.jpg?signature=...", "status": "Approved", "is_blocklisted": false, "is_allowlisted": false, "api_service": null, "source": "session" } ], "warnings": [ { "feature": "LIVENESS", "risk": "LOW_FACE_QUALITY", "additional_data": null, "log_type": "warning", "short_description": "Low face quality", "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.", "node_id": "liveness_primary" }, { "feature": "LIVENESS", "risk": "LOW_FACE_LUMINANCE", "additional_data": null, "log_type": "warning", "short_description": "Low face luminance", "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.", "node_id": "liveness_primary" }, { "feature": "LIVENESS", "risk": "POSSIBLE_DUPLICATED_FACE", "additional_data": { "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f", "duplicated_session_number": 123, "api_service": null }, "log_type": "warning", "short_description": "Possible duplicated face from other approved session", "long_description": "The system identified a possible duplicate face from another approved session, requiring further investigation.", "node_id": "liveness_primary" } ] } ] } ``` In diesem Fall liegt die Gesichtsqualität (12.4) unter dem standardmäßigen Prüfungs-Schwellenwert (15), die Helligkeit (18.7) liegt unter dem standardmäßigen Mindestwert (20) und die Aktion des Workflows für doppelte Gesichter ist auf Prüfung eingestellt. Daher tragen alle drei Warnungen den Wert `log_type: "warning"` und das Ergebnis des Berichts lautet `In Review`. ## Sicherheitshinweis Liveness-Videos und -Selfies sind biometrische Daten – die signierten URLs sind temporär und laufen ab (standardmäßig nach 4 Stunden). Behandeln Sie sie als kurzlebig: Speichern Sie sie nicht im Cache und machen Sie sie nicht öffentlich zugänglich. In der Regel benötigt Ihre Anwendung lediglich `status`, `score` und die Warnungen – speichern Sie so wenig wie möglich, um die Menge an biometrischen Daten auf Ihren Servern zu minimieren. ## Verwandte Themen * [Liveness-Warnungen](https://docs.didit.me/de/core-technology/liveness/warnings-liveness.md) — vollständiges Enum der Warnungen, Ursachen und Behebung. * [Webhooks](https://docs.didit.me/de/integration/webhooks.md) — auf `session.status.updated` lauschen, um den Bericht zu erhalten. * [Datenmodelle – Liveness-Prüfung](https://docs.didit.me/de/reference/data-models.md#liveness-prüfung) — kanonisches Schema mit allen Feldern. * [Gesichtsabgleich-Bericht](https://docs.didit.me/de/core-technology/face-match/report-face-match.md) — der zugehörige 1:1-Gesichtsabgleich mit dem Porträtfoto aus dem Dokument. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.