> ## 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 API - 重複アカウントの検知

> Diditの顔検索は、確認済みの全ユーザーから顔を検索し、重複アカウントとブロックリスト登録済みの不正行為者を検知します。本人確認に無料で含まれ、応答は2秒未満です。

顔検索は、承認済みの本人確認セッション全体から特定の顔を検索できる強力な機能です。重複アカウントの特定、不正の防止、セキュリティ対策の強化に役立ちます。

顔検索の連携プロンプト
        Copy prompt to clipboard



      
      

\<pre>

\````# Goal
Integrate Didit Face Search (1:N — search a face across your enrolled users + blocklist) into your app.

\# Delivery mode
Face Search is a **standalone API**. It runs against the face index your application has enrolled through prior verifications (sessions with save_api_request=true or Passive Liveness with save_api_request=true), faces uploaded to User profiles, your face lists, and any image-free biometric templates the application retained after deleting sessions (opt-in, see /management-api/biometric-templates/overview). There is no separate Face Search workflow feature.

POST https://verification.didit.me/v3/face-search/
multipart/form-data — x-api-key: YOUR_API_KEY

Required: `user_image` (jpg/jpeg/png/tiff/webp, max 5 MB; PDFs not accepted). The image must contain at least one detectable face (largest bbox wins when multiple).

Optional: `search_type` = "most_similar" (default — dedupe / returning-user) | "blocklisted_or_approved" (blocklist screening).

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/face-search/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'search_type=most_similar' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```

\# Response shape (singular)
Unlike most features, Face Search returns a **singular** `face_search` object — not a plural array:
\{ request_id, face_search: { status, total_matches, matches: [{ session_id, session_number, similarity_percentage, source, vendor_data, vendor_user_id, biometric_template_id, verification_date, user_details, match_image_url, status, is_blocklisted, is_allowlisted, api_service }], user_image: {entities}, warnings: [...] } }

match.source is "session", "imported", "list_entry", or "retained_template". A retained_template hit comes from an image-free biometric template kept after the source session was deleted: session_id, session_number, status, api_service, match_image_url, and user_details are null; vendor_data and vendor_user_id identify the User; biometric_template_id is the template you can inspect or purge via /v3/biometric-templates/{id}/.

\`status` is "Declined" only when at least one blocklist match is found. Pure duplicate matches return "Approved" (informational) — apply your own dedupe policy in app logic.

\# Warnings
Face Search emits risk codes from the LogWarningChoices.FACEMATCH bucket plus blocklist/duplicate semantics:
FACE_IN_BLOCKLIST, POSSIBLE_FACE_IN_BLOCKLIST, DUPLICATED_FACE, POSSIBLE_DUPLICATED_FACE, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/face-search/warnings-face-search.

\# Failure modes to handle
\- HTTP 400 — no face detected in user_image. Ask the user to retake.
\- HTTP 403 — out of credits.
\- status="Declined" with FACE_IN_BLOCKLIST — definitive blocklist hit; reject.
\- POSSIBLE_FACE_IN_BLOCKLIST — borderline match below the hard threshold; route to manual review.
\- DUPLICATED_FACE — user already verified under a different vendor_data; merge or block according to policy.

\# See also
\- Canonical schema: /reference/data-models#face-search
\- Per-feature report: /core-technology/face-search/report-face-search
\- Risk catalogue: /core-technology/face-search/warnings-face-search
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

Paste into

Academyの「検証結果の読み方」のレッスンでは、6:53から顔検索とブロックリストを取り上げます。[顔検索とブロックリスト — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=413\&rel=0\&playsinline=1)![重複とブロックリストの検知のため、ライブネスと連携するDiditの顔検索1:Nフロー](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/face-search-liveness.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=0cb5738f8ceaae7891cf13631485c400)## 自動顔検索の連携> 顔検索は、本人確認セッションのライブネスチェック中に自動で実行され、重複ユーザーの検知と、ブロックリストに登録された顔との照合を行います。### 自動の重複検知ユーザーが本人確認中にライブネスチェックを完了すると、次のことが行われます。- 顔の生体情報が、確認済みのすべての過去のユーザーと自動的に比較されます
- 顔の類似度に基づいて、重複している可能性のあるアカウントを特定します
- 設定した類似度のしきい値に従って、一致にフラグが付けられます
- 重複の可能性があるユーザーを確認し、対応できます### ブロックリストとの連携顔検索は、[ブロックリスト機能](https://docs.didit.me/management-api/lists/overview.md)とシームレスに連携します。- 本人確認中に、顔が自動的にブロックリストと照合されます
- ブロックリストに登録された顔との一致が見つかった場合、本人確認は自動的に拒否されます
- これにより、過去に問題が特定されたユーザーが新しいアカウントを作成するのを防ぎます
- 本人確認プロセスの信頼性の維持に役立ちます### 書類撮影中に撮る自撮りユーザーが書類を撮影している間、フロントカメラが本人の自撮りを撮影します(サイレントキャプチャ)。書類が評価されるたびに、その自撮りはライブネスの自撮りと同じ1:N検索にかけられます。- ライブネス検索と同じ類似度のしきい値と同じ優先順位で、顔のブロックリスト、およびアプリケーションで承認済みのユーザーと比較されます。
- ブロックリストに一致すると、`FRONT_CAMERA_FACE_IN_BLOCKLIST`(常に拒否)または`POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST`(常にレビュー)が発生します。承認済みユーザーに一致すると、`FRONT_CAMERA_DUPLICATED_FACE`または`POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE`が発生します。さらに、その承認済みユーザーが別の氏名で認証されていた場合は`FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH`、そのユーザーの本人確認書類の生年月日が異なる場合は`FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH`が発生します。[本人確認の警告](https://docs.didit.me/core-technology/id-verification/warnings-id-verification.md)をご覧ください。
- 一致結果は、セッション詳細の本人確認カードに一覧表示され、[セッションの判定](https://docs.didit.me/sessions-api/retrieve-session.md)の`id_verifications[].document_selfie_face_matches`で返されます。形式は`liveness_checks[].matches`のエントリと同じです。このフィールドは、古いセッションや検索が実行されなかった場合は`null`、実行されて何も見つからなかった場合は空配列になります。`match_image_url`は有効期限のある署名付きURLです。
- 使われるのは自撮りの中で最大の顔のみで、検出器が顔であると確信した場合に限ります。書類1件につき自撮り1枚が検索されます。表面の自撮り、または表面の自撮りに鮮明な顔がない場合は裏面の自撮りです。
- 自撮りは比較されるだけです。生体テンプレートが保存されることはないため、後のセッションがそれと照合されることはありません。セッションの自撮りから本人を排除するには、セッションページから、その自撮りを顔のブロックリストに追加してください。この検索には、**本人確認**ステップの**ルール**タブ(**サイレントキャプチャ顔検索**)に専用のスイッチと専用のアクションがあります。または、[ワークフロー機能の設定](https://docs.didit.me/management-api/workflows/feature-configs.md#ocr-/-id-verification)の`document_selfie_face_search_enabled`と`document_selfie_duplicated_face_*`アクションでも設定できます。デフォルトではオンです。重複した顔のアクションのデフォルトは承認(警告は引き続き報告されます)で、氏名と書類のクロスチェックのデフォルトは、ライブネスの対応するものと同様にレビューです。この検索には自撮りが必要なため、サイレントキャプチャがオンのときにのみ実行されます。ライブネスチェックステップの顔検索をオフにすると、この検索もオフになります。このオプトアウトは本人の顔についての選択であり、セッションのすべての自撮りが対象になるためです。### 書類不一致ルール**書類の不一致**ルール(ライブネスの自撮りでは`DUPLICATED_FACE_DOCUMENT_MISMATCH`、サイレントキャプチャでは`FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH`)は、一致したユーザーの本人確認書類の生年月日が異なる場合にのみ、重複した顔にフラグを付けます。
たとえば、IDカードの後にパスポートを提示するなど、同じ人物が別の書類を提示してもフラグは付きません。
更新された書類にもフラグは付きません。
同じ国で同じ書類番号を共有する2つのセッションに、フラグが付くことはありません。### 自動顔検索をオフにする自動顔検索は、すべてのライブネスステップでデフォルトでオンです。プライバシー上の方針で必要な場合は、ビジネスコンソール(シンプルモードおよびアドバンスドモード)の**ライブネスチェック**ステップの**ルール**タブから、ワークフローごとにオフにできます。または、[ワークフロー機能の設定](https://docs.didit.me/management-api/workflows/feature-configs.md#liveness)の`LIVENESS`または`AGE_ESTIMATION`ノードで`face_search_enabled: false`を指定します。スイッチをオフにしても、ライブネスの自撮りはライブネスのスコア算出と、顔照合での書類の顔写真との1:1比較の対象になりますが、顔インデックスには登録されません。- 検索が実行されないため、セッションには重複、ブロックリスト、許可リストの判定が付かず、`liveness_checks[].matches`は空のままです。**重複した顔**、**氏名の不一致**、**書類の不一致**、組織をまたぐ顔のルールは、対象がなくなるため、コンソールで非表示になります。
- 自撮りの生体テンプレートが保存されないため、後のセッションをこのセッションと照合することはできず、セッション削除後に[生体テンプレートの保持](https://docs.didit.me/ja/console/data-retention.md#生体認証テンプレートの保持)が保持するものもありません。
- 組織をまたぐチェックのために、自撮りが共有の生体人物を解決するのに使われることはありません。
- 書類撮影中に撮る自撮りも検索されません(`FRONT_CAMERA_*`のブロックリストや重複のリスクは発生しません)。オプトアウトは、セッションのすべての自撮りが対象です。本人確認ステップ独自のスイッチ(上記参照)でも、その検索だけをオフにできます。**スイッチが属するステップ。** スイッチは自撮りを撮影するステップにあるため、**ライブネスチェック**または**年齢推定**ステップは、それぞれ自身で管理します。**顔照合**ステップには独自のスイッチがありません。たとえば、そのステップの再提出を求めたあとなどに、ユーザーがそこで自撮りを撮り直す場合、撮り直しはライブネスチェックステップの設定に従うため、オプトアウトしていれば、新しい自撮りもインデックスに入りません。ワークフローが複数のライブネスチェックステップに分岐する場合、適用される設定は、セッションが実際に通過した分岐のものであり、組織をまたぐ顔の読み取りも同じステップに従います。既存のワークフローは、オプトアウトするまで現在の動作のままです。変更は、ワークフローを保存したあとに開始されたセッションに適用されます。以前のセッションが保存したテンプレートは、それらのセッションが削除または消去されるまでインデックスに残ります。このスイッチは、明示的に呼び出す、スタンドアロンの[顔検索API](https://docs.didit.me/standalone-apis/face-search.md)には影響しません。> [!WARNING]
>
> ブロックリストは、本人確認中に同じ1:N検索によって適用されます。ライブネスチェックステップの顔検索をオフにすると、ブロックリストに登録された人物は、そのステップでも、書類撮影中に撮る自撮りでも検知されません。本人確認ステップの「サイレントキャプチャ顔検索」をオフにした場合は、その自撮りで検知されません。### APIアクセス顔検索の機能は[API](https://docs.didit.me/standalone-apis/face-search.md)からも利用でき、次のことができます。- プログラムから顔検索を送信する
- 顔照合機能を自社のアプリケーションに組み込む
- カスタムの不正検知ワークフローを構築する
- 重複検知の自動化システムを構築する## 主な機能- **高精度**: 高度な生体認証アルゴリズムが、信頼できる一致結果を提供します
- **設定可能なしきい値**: リスク許容度に応じて一致の感度をカスタマイズできます
- **包括的なスキャン**: 確認済みの全ユーザーを対象に検索します
- **迅速な結果**: 大規模なユーザーデータベースでも検索を素早く処理します
- **プライバシー重視**: 照合には、お客様のアプリケーションに限定された数値の顔テンプレートを使用します。インデックスがお客様のテナントの外に出ることはありません### 設定可能なしきい値類似度スコアに異なるしきい値を設定することで、検索の感度をカスタマイズできます。> [!NOTE]
>
> これらのしきい値は、リスク許容度やセキュリティ要件に応じて調整できます。## 仕組み**1. 顔の抽出**検索が開始されると、システムは基準画像を処理します。| 処理 | 説明 |
| - | - |
| **特徴抽出** | 基準画像から顔の特徴を分離します |
| **正規化** | 一貫した比較ができるよう、顔データを標準化します |
| **品質検証** | 画像の品質と顔の鮮明さを確認します |
| **ベクトルエンコード** | 顔を数学的なベクトルで表現します |**2. 比較アルゴリズム**システムは、確認済みセッションのデータベース全体を検索します。- 基準となる顔ベクトルを、**アプリケーションに登録されているすべての顔**(セッションの顔、ユーザープロファイルにアップロードされた顔、顔リスト、保持されている生体テンプレート)と比較します
- 速度と精度に最適化された高度なニューラルネットワークアーキテクチャを採用しています
- **類似度順**(ランキング)と**ブロックリストまたは承認済み**(ステータスで絞り込み)の2つの検索モードに対応します
- 最適化されたインデックスにより、大規模なデータベースも迅速に処理します**3. 類似度のスコアリング**比較のたびに、類似度のパーセンテージが生成されます。| スコアの範囲 | 解釈 |
| :-: | - |
| **90%+** | 強い一致 — 同一人物である可能性が非常に高い |
| **70–89%** | 一致の可能性あり — 手動レビューが必要な場合があります |
| **70%未満** | 別人である可能性が高い |設定した一致のしきい値によって、フラグが付く結果が決まります。**4. 結果の提供**システムは包括的な結果セットを返します。- 類似度スコア順に並べた、一致候補の**ランキングリスト**
- セッションID、認証日、ベンダーデータを含む**一致の詳細**
- 各一致の**類似度のパーセンテージ**
- 目視で確認できる**一致画像**
- 一致した顔がブロックリストに登録されているかを示す**ブロックリストのステータス**## 削除されたセッションと保持される生体テンプレートセッションを削除すると、デフォルトではその顔の埋め込みも削除されるため、その人物はインデックスから外れ、重複フラグなしで再度認証できます。承認後すぐにセッションを削除しつつ、繰り返しのサインアップも検知したいアプリケーションでは、[生体テンプレートの保持](https://docs.didit.me/ja/console/data-retention.md#生体認証テンプレートの保持)を有効にできます。この場合Diditは、セッション削除後も、ユーザーに紐付けた画像なしの生体テンプレートを1つ保持し、そのテンプレートは、有効なセッションの顔とまったく同じように、顔検索と自動の重複検知の対象になります。保持されたテンプレートへのヒットは、`source: "retained_template"`、所有ユーザーの`vendor_user_id`と`vendor_data`、`biometric_template_id`とともに報告されます。顔を生成したセッションがもう存在しないため、セッションID、一致画像、本人情報、セッションのステータスは含まれません。保持されたテンプレートがブロックリストに登録されることはなく、顔のブロックリストのエントリは、それぞれ独立した生体エントリを持ちます。テンプレートは、予定された有効期限、ユーザーの削除、プライバシー消去の要求、または[生体テンプレートAPI](https://docs.didit.me/management-api/biometric-templates/overview.md)やコンソールの**リスト → 生体認証テンプレート**による明示的な消去まで残ります。## 類似度のパーセンテージ類似度のパーセンテージは、一致の可能性を判断するための中核的な指標です。- **高いパーセンテージ(通常90%以上)**: 顔が同一人物のものである可能性が高いことを示します。
- **中程度のパーセンテージ(70-89%)**: 一致の可能性があり、さらなる確認が必要な場合があることを示します。
- **低いパーセンテージ(70%未満)**: 別人である可能性が高いことを示します。何を「一致」とみなすかの具体的なしきい値は、セキュリティ要件に応じて設定できます。しきい値を上げると誤検知は減りますが、見逃しが増える可能性があります。## ユースケース- **不正防止**: 複数のアカウントを作成しようとするユーザーを特定します
- **KYCの強化**: KYCプロセスに追加の確認レイヤーを加えます
- **規制へのコンプライアンス**: 重複アカウントを検知するという要件を満たします
- **アクセス制御**: 高いセキュリティが求められる場所で、ユーザーの真正性を確認します
- **法執行**: 権限のある機関による、関係者の特定を支援します


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