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

# 顔検索1:Nレポート：一致結果のJSON

> Didit顔検索1:Nレポートのリファレンス。一致したセッションID、類似度（%）、ブロックリストのフラグ、不正調査に使うユーザー情報を確認できます。

## 概要

顔検索は**1:N**の生体認証検索です。Diditは`user_image`内で検出された最も大きな顔を取り出し、アプリケーションの顔検索インデックスと照合します。このインデックスには、認証セッション、保存されたスタンドアロンAPI呼び出し、ユーザープロフィールへ直接アップロードされた顔、ブロックリストと許可リストから登録された顔が含まれます。顔検索は**1:1**の顔照合とは異なります。顔照合はセルフィーを特定の書類の顔写真と比較しますが、顔検索は「この人物を以前どこかで見たことがあるか」を調べます。

レポートを解析する前に、次の2つの動作を理解しておく必要があります。

* **却下になるのはブロックリストとの一致のみです。** `face_search.status`が`Declined`になるのは、`FACE_IN_BLOCKLIST`または`POSSIBLE_FACE_IN_BLOCKLIST`警告が発生した場合のみです。重複一致だけの場合は`Approved`が返されます。`status`だけでなく、`matches`と`warnings`も確認してください。
* **永続化と登録は任意です。** `save_api_request=true`（デフォルト）の場合、呼び出しはAPIタイプのセッションとして永続化され、検索された顔は顔検索インデックスに登録されます。顔検索の呼び出しで登録された顔は**以降の顔検索結果から除外される**ため、繰り返し行った検索同士が一致することはありません。単発のクエリにするには`save_api_request=false`を渡してください。何も保存されず、顔も登録されません。

## 結果が表示される場所

顔検索はスタンドアロンAPIです。検索結果は**同期的に、`POST /v3/face-search/`のレスポンスでのみ**返されます。レスポンスのトップレベルにある単数形の`face_search`オブジェクトに含まれます。

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

複数形の`face_searches[]`配列はどこにも存在しません。セッション判定エンドポイントの`id_verifications[]`、`aml_screenings[]`、`liveness_checks[]`で使われている複数形配列の規則は適用されません。

`save_api_request=true`（デフォルト）の場合、呼び出しはAPIタイプのセッションとしても永続化されます。

* **Business Console**：セッションがセッション一覧に表示され、検索画像、一致結果、警告を確認できます。
* **`GET /v3/session/{sessionId}/decision/`**：返された`request_id`をセッションIDとして使うと取得できます。永続化されたデータは、`features[]`内の`FACE_SEARCH`エントリとして表示されます。また、保存された`matches`（新たに署名された`match_image_url`値を含む）と`warnings`を持つ`liveness_checks[]`項目としても表示されます。`face_search`オブジェクトとしては**表示されません**。

`save_api_request=false`の場合、`request_id`は一時的な相関用UUIDです。セッションは一切保存されないため、コンソールからも判定エンドポイントからも取得できません。

## スキーマ

正式なフィールド表については、[データモデルリファレンスの顔検索](https://docs.didit.me/ja/reference/data-models.md#顔検索)を参照してください。以下の構造は、エンドポイントが実行時に実際に返す内容を反映しています。

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

フィールドの補足：

* **`matches[]`は最大5件**です。類似度の下限を上回るエントリが、類似度の降順で並びます。`search_type=blocklisted_or_approved`の場合は、ブロックリストのエントリ、許可リストのエントリ、類似度の順に並びます。
* **`source`**は、一致した顔がどこから登録されたかを示します。値は次のとおりです。`session`は認証セッションまたは保存されたスタンドアロンAPI呼び出しです。`imported`はユーザープロフィールに直接アップロードされた顔です。`list_entry`はいずれかのリストに紐付けられた顔です。`retained_template`は、アプリケーションが元のセッションを削除した後に保持した、画像を含まない[生体認証テンプレート](https://docs.didit.me/ja/management-api/biometric-templates/overview.md)です。`imported`、`list_entry`、`retained_template`の一致では、`session_id`、`session_number`、`status`、`api_service`は`null`になります。
* **`retained_template`の一致**には`vendor_user_id`、`vendor_data`、`biometric_template_id`が含まれます。一方で、`match_image_url`、`user_details`およびセッション関連のすべての項目は常に`null`です。その顔が生成されたセッションはすでに存在せず、テンプレートは画像も本人情報も保持していないためです。保持テンプレートの`is_blocklisted`は常に`false`です。ブロックリストに登録された顔は、`list_entry`の一致として別に報告されます。テンプレートを削除するには`DELETE /v3/biometric-templates/{biometric_template_id}/`を使用します。
* **`api_service`**は、一致したセッションのスタンドアロンAPIの種類です。大文字で表記されます（例：`PASSIVE_LIVENESS`）。一致した顔が通常のワークフローの認証セッションに由来する場合は`null`になります。
* **`user_details`**は、一致したセッションの書類認証から取得されます。`source: imported`の一致では、代わりにユーザープロフィールから値が設定されます。この場合、`full_name`には値が入り、`document_type`/`document_number`はnullになります。本人情報が存在しない場合は`null`です（例：ライブネスのみのセッション）。
* **警告の構造はワークフローの警告より簡略化されています。** `node_id`はありません。文書化されたレスポンス仕様（`FaceSearchResponseSerializer`）では、`risk`、`additional_data`、`log_type`、`short_description`、`long_description`の5つのフィールドが宣言されています。実行時のペイロードにはこれに加えて`feature`が含まれ、ここでは常に`"LIVENESS"`です。[顔検索の警告](https://docs.didit.me/ja/core-technology/face-search/warnings-face-search.md)を参照してください。
* **同一ユーザーとの一致は除外されません。** ワークフローの重複検出とは異なり、スタンドアロンエンドポイントは同じ`vendor_data`を持つ過去のセッションを除外しません。そのため、再訪した正当なユーザーは自身の過去のセッションと一致します。

## ステータス値

トップレベルの`face_search.status`は`warnings[]`から導出されます。一致ごとの`status`は**一致したセッションの**認証結果を表すもので、トップレベルのステータスとは無関係です。

| 値 | 表示される条件 |
| - | - |
| `Approved` | ブロックリストの警告が発生しなかった場合です。重複一致が見つかった場合も含みます。重複は参考情報としてのシグナルであり、却下の理由にはなりません。 |
| `Declined` | `FACE_IN_BLOCKLIST`または`POSSIBLE_FACE_IN_BLOCKLIST`警告が発生した場合です。検索画像が顔ブロックリスト内の顔と一致したことを示します。 |

注：検索画像に検出可能な顔が含まれていない場合、APIは`face_search`オブジェクトを構築する**前に**、HTTP `400`と`{"error": "No face detected in the image"}`を返します。このケースに対応する`Declined`ステータスはありません。クレジットが不足している場合は、画像処理の前にHTTP `403`が返されます。

## 例

### 承認済み (重複一致、ブロックリスト一致なし)

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

### 却下 (ブロックリスト一致)

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

## 関連ページ

* [顔検索の警告](https://docs.didit.me/ja/core-technology/face-search/warnings-face-search.md)：検索で発生しうるすべての警告コード
* [顔検索APIリファレンス](https://docs.didit.me/ja/standalone-apis/face-search.md)：リクエストパラメーターと`search_type`モード
* [データモデル：顔検索](https://docs.didit.me/ja/reference/data-models.md#顔検索)：正式なスキーマ
* [Webhook](https://docs.didit.me/ja/integration/webhooks.md)：保存されたセッションの`status.updated`ペイロード

> [!NOTE]
>
> `save_api_request=true`の場合、`match_image_url`の値は署名付きの短時間だけ有効なURLです。新しいURLを取得するには、返された`request_id`を使ってセッション判定エンドポイントを再度呼び出してください。`save_api_request=false`の場合、これらの値は内部ストレージのパスであり、直接ダウンロードすることはできません。自社側には一致したセッションID、ステータス、`similarity_percentage`のみを保存し、元の生体画像は保持しないでください。


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