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

# Recherche faciale 1:N : rapport et résultats JSON

> Rapport de Recherche faciale 1:N Didit : ID de session, similarité, alertes de liste de blocage et données utilisateur contre la fraude.

## Vue d'ensemble

La Recherche faciale est une recherche biométrique **1:N** : Didit extrait le plus grand visage détecté dans votre champ `user_image` et le recherche dans l'index de recherche faciale de votre application — les visages enrôlés à partir de sessions de vérification, d'appels API autonomes sauvegardés, d'ajouts directs de visages sur des profils utilisateurs et de vos listes de blocage ou d'autorisation. Elle est distincte de Correspondance faciale, qui est **1:1** — Correspondance faciale compare un selfie avec la photo d'un document spécifique, tandis que Recherche faciale pose la question : « avons-nous déjà vu cette personne auparavant ? ».

Deux comportements essentiels sont à comprendre avant d'analyser le rapport :

* **Seules les correspondances avec la liste de blocage entraînent un refus.** Le champ `face_search.status` prend la valeur `Declined` uniquement lorsqu'un avertissement `FACE_IN_BLOCKLIST` ou `POSSIBLE_FACE_IN_BLOCKLIST` est déclenché. Les correspondances en double retournent à elles seules le statut `Approved` — inspectez `matches` et `warnings`, pas seulement `status`.
* **Persistance et enrôlement optionnels.** Lorsque `save_api_request=true` (valeur par défaut), l'appel est conservé en tant que session de type API et le visage recherché est enrôlé dans votre index de recherche faciale. Les visages enrôlés par des appels de Recherche faciale sont **exclus des futurs résultats de Recherche faciale**, de sorte que des recherches répétées ne correspondent jamais entre elles. Transmettez `save_api_request=false` pour une requête ponctuelle : rien n'est stocké et le visage n'est pas enrôlé.

## Où apparaissent les résultats

Recherche faciale est une API autonome. Les résultats de recherche sont renvoyés **de manière synchrone, uniquement dans la réponse à `POST /v3/face-search/`**, sous la forme d'un objet unique `face_search` au niveau racine :

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

Il n'y a pas de tableau au pluriel `face_searches[]` — la convention de tableau au pluriel utilisée par `id_verifications[]`, `aml_screenings[]` et `liveness_checks[]` sur l'endpoint de décision de session ne s'applique pas ici.

Lorsque `save_api_request=true` (valeur par défaut), l'appel est également conservé sous forme de session de type API :

* **Business Console** — la session apparaît dans votre liste de sessions avec l'image recherchée, les correspondances et les avertissements.
* **`GET /v3/session/{sessionId}/decision/`** — récupérable en utilisant le `request_id` renvoyé comme identifiant de session. Les données conservées apparaissent sous la forme d'une entrée `FACE_SEARCH` dans `features[]` et d'un élément `liveness_checks[]` contenant les correspondances `matches` stockées (avec des valeurs `match_image_url` nouvellement signées) et les `warnings` — **et non** sous la forme d'un objet `face_search`.

Lorsque `save_api_request=false`, le champ `request_id` est un UUID de corrélation éphémère : la session n'est jamais stockée, elle ne peut donc pas être récupérée depuis la Console ou l'endpoint de décision.

## Schéma

Consultez [Recherche faciale dans la référence des modèles de données](https://docs.didit.me/fr/reference/data-models.md#recherche-faciale) pour consulter les tableaux de champs faisant autorité. La structure ci-dessous reflète ce que l'endpoint renvoie réellement à l'exécution.

```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;
}
```

Notes sur les champs :

* **`matches[]` est limité à 5** entrées au-dessus du seuil de similarité minimal, classées par ordre décroissant de similarité (`search_type=blocklisted_or_approved` classe d'abord les entrées sur liste de blocage, puis sur liste d'autorisation, puis selon la similarité).
* **`source`** indique l'origine de l'enrôlement du visage correspondant : `session` — une session de vérification ou un appel API autonome sauvegardé ; `imported` — un visage importé directement sur un profil utilisateur ; `list_entry` — un visage rattaché à l'une de vos listes ; `retained_template` — un [gabarit biométrique](https://docs.didit.me/fr/management-api/biometric-templates/overview.md) sans image que l'application a conservé après la suppression de la session source. `session_id`, `session_number`, `status` et `api_service` sont à `null` pour les correspondances de type `imported`, `list_entry` et `retained_template`.
* **Les correspondances `retained_template`** contiennent `vendor_user_id`, `vendor_data` et `biometric_template_id` ; `match_image_url`, `user_details` et tous les éléments liés à une session valent toujours `null` : la session à l'origine du visage n'existe plus et le gabarit ne contient aucune image ni donnée d'identité. Le champ `is_blocklisted` est toujours à `false` pour un gabarit conservé ; un visage sur liste de blocage est signalé séparément comme une correspondance de type `list_entry`. Vous pouvez purger le gabarit avec `DELETE /v3/biometric-templates/{biometric_template_id}/`.
* **`api_service`** correspond au type d'API autonome de la session trouvée (en majuscules, par exemple `PASSIVE_LIVENESS`) et est à `null` lorsque le visage correspondant provient d'une session de vérification de workflow standard.
* **`user_details`** provient de la vérification de document de la session correspondante. Pour les correspondances `source: imported`, ce champ est renseigné à partir du profil utilisateur (`full_name` renseigné, `document_type`/`document_number` à null) ; il est à `null` si aucune donnée d'identité n'existe (par exemple pour des sessions de détection du vivant uniquement).
* **Les avertissements utilisent une structure simplifiée** par rapport aux avertissements de workflow : il n'y a pas de champ `node_id`. Le contrat de réponse documenté (`FaceSearchResponseSerializer`) déclare les cinq champs `risk`, `additional_data`, `log_type`, `short_description`, `long_description` ; le payload d'exécution contient en plus `feature`, qui vaut toujours `"LIVENESS"` ici. Consultez les [avertissements de Recherche faciale](https://docs.didit.me/fr/core-technology/face-search/warnings-face-search.md).
* **Les correspondances pour un même utilisateur ne sont pas exclues** — contrairement à la détection de doublons dans les workflows, l'endpoint autonome ne filtre pas les sessions antérieures ayant le même `vendor_data`. Ainsi, un utilisateur légitime récurrent correspondra à ses propres sessions précédentes.

## Valeurs de statut

La valeur `face_search.status` au niveau racine est calculée à partir de `warnings[]`. Le `status` au niveau de la correspondance reflète le résultat de vérification de la **session correspondante** et fonctionne de manière indépendante.

| Valeur | Quand elle apparaît |
| - | - |
| `Approved` | Aucun avertissement lié à une liste de blocage n'a été déclenché. Inclut le cas où des doublons ont été trouvés — les doublons sont des signaux informatifs, pas des motifs de refus. |
| `Declined` | Un avertissement `FACE_IN_BLOCKLIST` ou `POSSIBLE_FACE_IN_BLOCKLIST` a été déclenché — l'image recherchée correspond à un visage présent dans votre liste de blocage des visages. |

Remarque : lorsque l'image recherchée ne contient aucun visage détectable, l'API renvoie une erreur HTTP `400` avec `{"error": "No face detected in the image"}` **avant** qu'un objet `face_search` ne soit créé — aucun statut `Declined` n'est attribué dans ce cas. En cas de crédits insuffisants, l'API renvoie une erreur HTTP `403` avant tout traitement de l'image.

## Exemples

### Approuvé — correspondance en doublon, pas de liste de blocage

```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"
}
```

### Refusé — correspondance avec la liste de blocage

```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"
}
```

## Ressources associées

* [Avertissements de Recherche faciale](https://docs.didit.me/fr/core-technology/face-search/warnings-face-search.md) — tous les codes d'avertissement que la recherche peut émettre
* [Référence de l'API de recherche faciale](https://docs.didit.me/fr/standalone-apis/face-search.md) — paramètres de requête et modes `search_type`
* [Modèles de données — Recherche faciale](https://docs.didit.me/fr/reference/data-models.md#recherche-faciale) — schéma canonique
* [Webhooks](https://docs.didit.me/fr/integration/webhooks.md) — payloads `status.updated` pour les sessions persistantes

> [!NOTE]
>
> Lorsque `save_api_request=true`, les valeurs de `match_image_url` sont des URL signées à courte durée de vie — appelez à nouveau l'endpoint de décision de la session avec le `request_id` renvoyé pour en obtenir de nouvelles. Lorsque `save_api_request=false`, il s'agit de chemins de stockage internes non téléchargeables directement. Ne conservez de votre côté que l'ID de la session correspondante, le statut et `similarity_percentage` — ne conservez pas l'image biométrique sous-jacente.


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