Liveness-Bericht: Score, Methode & Treffer

Ü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.
Webhooks – Payloads von session.status.updated enthalten dasselbe liveness_checks[]-Array, sobald der Schritt Daten geliefert hat. Siehe Webhooks.
Eigenständige Liveness-API – siehe Eigenständige Liveness-API.

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. 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. Jeder Eintrag entspricht der Struktur des Warning-Objekts (`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

{
  "liveness_checks": [
    {
      "status": "Approved",
      "node_id": "liveness_primary",
      "method": "ACTIVE_3D",
      "score": 92.4,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": "https://<media-host>/.../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

{
  "liveness_checks": [
    {
      "status": "In Review",
      "node_id": "liveness_primary",
      "method": "PASSIVE",
      "score": 76.1,
      "reference_image": "https://<media-host>/.../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://<media-host>/.../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.

Authentifizierung

Verifizierung

Überwachung

Plattform

Liveness-Bericht: Score, Methode & Treffer

Übersicht

Wo er in API-Antworten erscheint

Schema

Sitzungsübergreifende Gesichtsabgleiche

Statuswerte

Beispiele

Genehmigt – Einwandfreie Active-3D-Erfassung

In Prüfung – Passive Liveness, Erfassung mit geringer Qualität und mögliches Duplikat

Sicherheitshinweis

Verwandte Themen

​Übersicht

​Wo er in API-Antworten erscheint

​Schema

​Sitzungsübergreifende Gesichtsabgleiche

​Statuswerte

​Beispiele

​Genehmigt – Einwandfreie Active-3D-Erfassung

​In Prüfung – Passive Liveness, Erfassung mit geringer Qualität und mögliches Duplikat

​Sicherheitshinweis

​Verwandte Themen

Übersicht

Wo er in API-Antworten erscheint

Schema

Sitzungsübergreifende Gesichtsabgleiche

Statuswerte

Beispiele

Genehmigt – Einwandfreie Active-3D-Erfassung

In Prüfung – Passive Liveness, Erfassung mit geringer Qualität und mögliches Duplikat

Sicherheitshinweis

Verwandte Themen