Gesichtsabgleich-Bericht: Ähnlichkeitswert als JSON

Ü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, 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 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.
Webhooks — session.status.updated-Payloads enthalten dasselbe face_matches[]-Array, sobald der Schritt Daten erzeugt hat. Siehe Webhooks.
Eigenständige Gesichtsabgleich-API — für direkte 1:1-Abgleiche siehe Eigenständige Gesichtsabgleich-API.

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

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

{
  "face_matches": [
    {
      "status": "Approved",
      "node_id": "feature_face_match_1",
      "score": 96.42,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": []
    }
  ]
}

In Prüfung – grenzwertige Ähnlichkeit

{
  "face_matches": [
    {
      "status": "In Review",
      "node_id": "feature_face_match_1",
      "score": 65.43,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/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

{
  "face_matches": [
    {
      "status": "Declined",
      "node_id": "feature_face_match_1",
      "score": null,
      "source_image_session_id": null,
      "source_image": null,
      "target_image": "https://<media-host>/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.

Authentifizierung

Verifizierung

Überwachung

Plattform

Gesichtsabgleich-Bericht: Ähnlichkeitswert als JSON

Übersicht

Wo er in API-Antworten erscheint

Schema

Statuswerte

Beispiele

Genehmigt – eindeutige Übereinstimmung

In Prüfung – grenzwertige Ähnlichkeit

Abgelehnt – kein Referenzbild für den Abgleich vorhanden

Sicherheitshinweis

Verwandte Themen

​Übersicht

​Wo er in API-Antworten erscheint

​Schema

​Statuswerte

​Beispiele

​Genehmigt – eindeutige Übereinstimmung

​In Prüfung – grenzwertige Ähnlichkeit

​Abgelehnt – kein Referenzbild für den Abgleich vorhanden

​Sicherheitshinweis

​Verwandte Themen

Übersicht

Wo er in API-Antworten erscheint

Schema

Statuswerte

Beispiele

Genehmigt – eindeutige Übereinstimmung

In Prüfung – grenzwertige Ähnlichkeit

Abgelehnt – kein Referenzbild für den Abgleich vorhanden

Sicherheitshinweis

Verwandte Themen