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

# Gesichtssuche 1:N: Bericht & Treffer-Ergebnisse (JSON)

> Didits 1:N-Gesichtssuche-Bericht liefert gefundene Sitzungs-IDs, Ähnlichkeitswerte, Sperrlisten-Flags und Benutzerdetails zur Betrugsanalyse.

## Übersicht

Die Gesichtssuche ist eine biometrische **1:N**-Suche: Didit nimmt das größte erkannte Gesicht in Ihrem `user_image` und gleicht es mit dem Gesichtssuchindex Ihrer Anwendung ab – Gesichter, die aus Verifizierungssitzungen, gespeicherten eigenständigen API-Aufrufen, direkt in Benutzerprofile hochgeladenen Gesichtern und Ihren Sperr-/Freigabelisten registriert wurden. Sie unterscheidet sich vom Gesichtsabgleich, der **1:1** erfolgt – der Gesichtsabgleich vergleicht ein Selfie mit dem Porträt auf einem bestimmten Dokument, während die Gesichtssuche die Frage stellt: „Haben wir diese Person schon einmal irgendwo gesehen?“.

Zwei Verhaltensweisen sollten Sie verstehen, bevor Sie den Bericht auswerten:

* **Nur Treffer auf der Sperrliste führen zu einer Ablehnung.** `face_search.status` ist nur dann `Declined`, wenn eine Warnung vom Typ `FACE_IN_BLOCKLIST` oder `POSSIBLE_FACE_IN_BLOCKLIST` ausgelöst wird. Reine Duplikat-Treffer geben `Approved` zurück – prüfen Sie daher `matches` und `warnings`, nicht nur den `status`.
* **Optionale Persistierung und Registrierung.** Wenn `save_api_request=true` gesetzt ist (Standardeinstellung), wird der Aufruf als Sitzung vom Typ API persistiert und das gesuchte Gesicht wird in Ihren Gesichtssuchindex aufgenommen. Gesichter, die durch Gesichtssuche-Aufrufe registriert wurden, sind **von zukünftigen Gesichtssuchergebnissen ausgeschlossen**, sodass wiederholte Suchanfragen nie miteinander übereinstimmen. Übergeben Sie `save_api_request=false` für eine einmalige Abfrage: Es wird nichts gespeichert und das Gesicht wird nicht registriert.

## Wo die Ergebnisse erscheinen

Die Gesichtssuche ist eine eigenständige API. Die Suchergebnisse werden **ausschließlich synchron in der Antwort auf `POST /v3/face-search/`** als einzelnes `face_search`-Objekt auf oberster Ebene zurückgegeben:

```text theme={null}
POST /v3/face-search/  ──▶  { "request_id": …, "face_search": { … }, "vendor_data": …, "metadata": …, "created_at": … }
```

Es gibt an keiner Stelle ein plurales `face_searches[]`-Array – die Plural-Array-Konvention, die von `id_verifications[]`, `aml_screenings[]` und `liveness_checks[]` auf dem Sitzungsentscheidungs-Endpoint verwendet wird, gilt hier nicht.

Wenn `save_api_request=true` gesetzt ist (Standardeinstellung), wird der Aufruf zusätzlich als Sitzung vom Typ API persistiert:

* **Business-Konsole** – die Sitzung erscheint in Ihrer Sitzungsliste mit dem Suchbild, den Treffern und den Warnungen.
* **`GET /v3/session/{sessionId}/decision/`** – abrufbar unter Verwendung der zurückgegebenen `request_id` als Sitzungs-ID. Die persistierten Daten erscheinen als `FACE_SEARCH`-Eintrag in `features[]` sowie als Element in `liveness_checks[]`, das die gespeicherten `matches` (mit frisch signierten `match_image_url`-Werten) und `warnings` enthält – **nicht** als `face_search`-Objekt.

Wenn `save_api_request=false` übergeben wird, ist die `request_id` eine flüchtige Korrelations-UUID: Die Sitzung wird nie gespeichert und kann daher weder über die Konsole noch über den Entscheidungs-Endpoint abgerufen werden.

## Schema

Die kanonischen Feldtabellen finden Sie unter [Gesichtssuche in der Datenmodell-Referenz](https://docs.didit.me/de/reference/data-models.md#gesichtssuche). Die nachfolgende Struktur entspricht dem, was der Endpoint zur Laufzeit tatsächlich zurückgibt.

```typescript theme={null}
interface FaceSearchResponse {
  request_id: string;            // UUID — the persisted session id when save_api_request=true
  face_search: {
    status: 'Approved' | 'Declined';
    total_matches: number;       // 0-5, length of matches[]
    matches: FaceSearchMatch[];  // capped at 5, ordered by similarity
    user_image: {                // always present
      entities: {
        bbox: [number, number, number, number];
        confidence: number;      // 0-1, one entry per detected face
      }[];
      best_angle: 0 | 90 | 180 | 270;
    };
    warnings: Warning[];
  };
  vendor_data: string | null;    // echoed from the request
  metadata: object | null;       // echoed from the request
  created_at: string;            // ISO 8601, e.g. "2026-06-12T01:04:42.763237+00:00"
}

interface FaceSearchMatch {
  session_id: string | null;     // UUID of the matched session; null for non-session matches
  session_number: number | null; // Console-friendly number; null for non-session matches
  similarity_percentage: number; // 0-100
  source: 'session' | 'imported' | 'list_entry' | 'retained_template';
  vendor_data: string | null;    // the matched session's, imported profile's, or retained template's User vendor_data
  vendor_user_id: string | null; // UUID of the linked User; null for list_entry matches and sessions without a User
  biometric_template_id: string | null; // set only for retained_template matches
  verification_date: string | null;  // "YYYY-MM-DDThh:mm:ssZ"; null for list_entry matches; the retention date for retained_template matches
  user_details: {
    full_name: string | null;
    document_type: string | null;
    document_number: string | null;
  } | null;                      // null when the matched session has no document data
  match_image_url: string | null; // signed URL when save_api_request=true; raw storage path otherwise; null for retained_template matches
  status: 'Approved' | 'Declined' | 'In Review' | null;  // the matched session's status
  is_blocklisted: boolean;
  is_allowlisted: boolean;
  api_service: 'ID_VERIFICATION' | 'FACE_MATCH' | 'AGE_ESTIMATION' | 'POA' | 'AML'
             | 'PASSIVE_LIVENESS' | 'DATABASE_VALIDATION' | 'PHONE_VERIFICATION'
             | 'EMAIL_VERIFICATION' | null;  // null when the match comes from a workflow session
}

interface Warning {
  risk: string;
  feature: 'LIVENESS';           // always LIVENESS on this endpoint
  additional_data: object | null;
  log_type: 'error' | 'warning' | 'information';
  short_description: string;
  long_description: string;
}
```

Hinweise zu den Feldern:

* **`matches[]` ist auf maximal 5** Einträge oberhalb des Ähnlichkeitsschwellenwerts begrenzt, sortiert nach absteigender Ähnlichkeit (`search_type=blocklisted_or_approved` ordnet gesperrte Einträge zuerst ein, danach freigegebene und anschließend nach Ähnlichkeit).
* **`source`** gibt an, woher das übereinstimmende Gesicht stammt: `session` – eine Verifizierungssitzung oder ein gespeicherter eigenständiger API-Aufruf; `imported` – ein direkt in ein Benutzerprofil hochgeladenes Gesicht; `list_entry` – ein Gesicht, das einer Ihrer Listen zugeordnet ist; `retained_template` – ein bildfreies [biometrisches Template](https://docs.didit.me/de/management-api/biometric-templates/overview.md), das die Anwendung nach dem Löschen der ursprünglichen Sitzung beibehalten hat. `session_id`, `session_number`, `status` und `api_service` sind für Treffer mit `imported`, `list_entry` und `retained_template` jeweils `null`.
* **`retained_template`-Treffer** enthalten `vendor_user_id`, `vendor_data` und `biometric_template_id`, während `match_image_url`, `user_details` und alle sitzungsbezogenen Felder stets `null` sind: Die Sitzung, aus der das Gesicht hervorging, existiert nicht mehr und das Template enthält weder Bild- noch Identitätsdaten. `is_blocklisted` ist bei einem beibehaltenen Template immer `false`; ein gesperrtes Gesicht wird separat als `list_entry`-Treffer gemeldet. Löschen Sie das Template mit `DELETE /v3/biometric-templates/{biometric_template_id}/`.
* **`api_service`** ist der eigenständige API-Typ der zugeordneten Sitzung (in Großbuchstaben, z. B. `PASSIVE_LIVENESS`) und `null`, wenn das übereinstimmende Gesicht aus einer regulären Workflow-Verifizierungssitzung stammt.
* **`user_details`** stammt aus der Dokumentenprüfung der zugeordneten Sitzung. Bei Treffern mit `source: imported` wird das Feld stattdessen aus dem Benutzerprofil befüllt (`full_name` ist gesetzt, `document_type`/`document_number` sind null); es ist `null`, wenn keine Identitätsdaten vorliegen (beispielsweise bei reinen Liveness-Sitzungen).
* **Warnungen verwenden eine reduzierte Struktur** im Vergleich zu Workflow-Warnungen: Es gibt keine `node_id`. Der dokumentierte Antwortvertrag (`FaceSearchResponseSerializer`) deklariert die fünf Felder `risk`, `additional_data`, `log_type`, `short_description`, `long_description`; die Laufzeit-Payload enthält zusätzlich `feature`, das hier immer `"LIVENESS"` lautet. Siehe [Warnungen bei der Gesichtssuche](https://docs.didit.me/de/core-technology/face-search/warnings-face-search.md).
* **Treffer desselben Benutzers werden nicht ausgeschlossen** – anders als bei der Duplikaterkennung im Workflow filtert der eigenständige Endpoint frühere Sitzungen mit denselben `vendor_data` nicht heraus, sodass ein wiederkehrender legitimer Benutzer mit seinen eigenen früheren Sitzungen übereinstimmt.

## Statuswerte

Der übergeordnete `face_search.status` wird aus `warnings[]` abgeleitet. Der `status` auf Trefferebene spiegelt das Verifizierungsergebnis der **übereinstimmenden Sitzung** wider und ist davon unabhängig.

| Wert | Wann er auftritt |
| - | - |
| `Approved` | Es wurde keine Sperrlisten-Warnung ausgelöst. Dies schließt den Fall ein, dass Duplikat-Treffer gefunden wurden – Duplikate sind Informationssignale und führen nicht zur Ablehnung. |
| `Declined` | Eine Warnung vom Typ `FACE_IN_BLOCKLIST` oder `POSSIBLE_FACE_IN_BLOCKLIST` wurde ausgelöst – das Suchbild stimmte mit einem Gesicht auf Ihrer Gesichts-Sperrliste überein. |

Hinweis: Wenn das Suchbild kein erkennbares Gesicht enthält, gibt die API HTTP `400` mit `{"error": "No face detected in the image"}` zurück, **bevor** ein `face_search`-Objekt erstellt wird – für diesen Fall gibt es keinen `Declined`-Status. Bei unzureichenden Credits wird HTTP `403` zurückgegeben, bevor eine Bildverarbeitung stattfindet.

## Beispiele

### Approved — Duplikat-Treffer, keine Sperrliste

```json theme={null}
{
  "request_id": "5e0c3a1f-7b2d-4c8e-9f10-2a3b4c5d6e7f",
  "face_search": {
    "status": "Approved",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
        "session_number": 1024,
        "similarity_percentage": 87.42,
        "source": "session",
        "vendor_data": "user-9",
        "verification_date": "2025-11-20T09:15:00Z",
        "user_details": {
          "full_name": "Jane Marie Doe",
          "document_type": "Passport",
          "document_number": "X1234567"
        },
        "match_image_url": "https://<media-host>/face/9c8b7a6d/reference.jpg?signature=...",
        "status": "Approved",
        "is_blocklisted": false,
        "is_allowlisted": false,
        "api_service": null
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [40, 40, 120, 120],
          "confidence": 0.732973
        }
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "DUPLICATED_FACE",
        "feature": "LIVENESS",
        "additional_data": {
          "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
          "duplicated_session_number": 1024,
          "api_service": null
        },
        "log_type": "information",
        "short_description": "Duplicated face from other approved session",
        "long_description": "The system identified a duplicated face from another approved session, requiring further investigation."
      }
    ]
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}
```

### Declined — Sperrlisten-Treffer

```json theme={null}
{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "face_search": {
    "status": "Declined",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "session_number": 323442,
        "similarity_percentage": 99.99,
        "source": "session",
        "vendor_data": "user-1",
        "verification_date": "2025-01-01T00:00:00Z",
        "user_details": {
          "full_name": "Jane Marie Doe",
          "document_type": "ID",
          "document_number": "X1234567"
        },
        "match_image_url": "https://<media-host>/face/3f6a1c2e/reference.jpg?signature=...",
        "status": "Approved",
        "is_blocklisted": true,
        "is_allowlisted": false,
        "api_service": "PASSIVE_LIVENESS"
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [40, 40, 120, 120],
          "confidence": 0.732973
        }
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "FACE_IN_BLOCKLIST",
        "feature": "LIVENESS",
        "additional_data": {
          "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
          "blocklisted_session_number": 323442,
          "api_service": "PASSIVE_LIVENESS"
        },
        "log_type": "error",
        "short_description": "Face in blocklist",
        "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified."
      }
    ]
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}
```

## Verwandte Themen

* [Warnungen der Gesichtssuche](https://docs.didit.me/de/core-technology/face-search/warnings-face-search.md) – alle Warnungscodes, die die Suche ausgeben kann
* [API-Referenz zur Gesichtssuche](https://docs.didit.me/de/standalone-apis/face-search.md) – Anfrageparameter und `search_type`-Modi
* [Datenmodelle – Gesichtssuche](https://docs.didit.me/de/reference/data-models.md#gesichtssuche) – kanonisches Schema
* [Webhooks](https://docs.didit.me/de/integration/webhooks.md) – `status.updated`-Payloads für persistierte Sitzungen

> [!NOTE]
>
> Wenn `save_api_request=true` gilt, sind die `match_image_url`-Werte signierte, kurzlebige URLs – rufen Sie den Endpoint für die Sitzungsentscheidung mit der zurückgegebenen `request_id` erneut ab, um neue URLs zu erhalten. Wenn `save_api_request=false` gilt, handelt es sich um interne Speicherpfade, die nicht direkt herunterladbar sind. Speichern Sie auf Ihrer Seite nur die übereinstimmende Sitzungs-ID, den Status und `similarity_percentage` – bewahren Sie das zugrunde liegende biometrische Bild nicht auf.


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