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

# ユーザーの生体認証：顔検索とブロックリスト

> Diditは顔の生体認証データをベンダーのユーザーエンティティに紐付けます。1:N顔検索、重複検出、顔のブロックリスト適用、手動アップロードについて解説します。



顔生体認証プロンプト
        プロンプトをクリップボードにコピー



      
      

\<pre>

\````# Goal — search, blocklist, and act on User face biometrics

Faces are captured automatically during liveness inside a verification session, and can also be uploaded to an existing User profile when you are migrating users from another provider. You interact with biometrics through three action surfaces: **profile face upload** (attach an imported face to a User), **face search** (find a user by face), and the **Lists API** (blocklist a face so future sessions are auto-declined).

\## 1) Upload a face to an imported User profile

Use this when you already created or imported a User with `vendor_data` and have a trusted face image from your previous provider.

\```bash
\# 1. Get the Didit internal User id from vendor_data
curl https://verification.didit.me/v3/users/user-42/ \
-H "x-api-key: $DIDIT_API_KEY"

\# 2. Upload a base64-encoded face to that profile
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "comment": "Imported from previous KYC provider"}'
\```

Limits: max 5 faces per User, max 2 MB per image, and the image must contain a detectable face. This enrolls the face for profile evidence and future duplicate/face-search matching. It does not blocklist the face.

\## 2) Face search — 1:N

Use to detect duplicate accounts, identify a face from a CCTV frame, or recognise a returning customer before running new KYC.

\```bash
curl -X POST https://verification.didit.me/v3/face-search/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "user_image=@./selfie.jpg"
\```

Response includes match candidates with similarity scores. Wire your workflow (in the console) to auto-decline / flag / warn on duplicate hits, or call this endpoint directly from your backend before creating a session.

\## 3) Face blocklist — block a user by face

To block a known bad actor going forward, upload their face to a **face-type list** in your application. Any future session whose liveness selfie matches the embedding is auto-declined.

\```bash
\# Upload a face directly to a face-type list (no session needed)
curl -X POST https://verification.didit.me/v3/lists/$LIST_UUID/entries/face-upload/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "reason": "confirmed_fraud"}'
\```

If the face you want to block came from an existing session, use `POST /v3/lists/{list_uuid}/entries/` with `reference_session_id` instead — the backend extracts the biometric and links the entry back to the session.

Remove a face from the list with the Delete entry endpoint:

\```bash
curl -X DELETE https://verification.didit.me/v3/lists/$LIST_UUID/entries/$ENTRY_UUID/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

The Lists API supports face, document, email, phone, and IBAN list types. See /management-api/lists/overview for the full catalog.

\## 4) Auto-blocklist from declines

When a session is `DECLINED` and your workflow has auto-blocklist enabled, the associated face is added to the system face list automatically and the User entity transitions to `BLOCKED` per policy. No manual call needed.

\## 5) Where the face lives on the User

\- `portrait_image` on the User entity is a signed URL to the latest approved selfie.
\- Manually uploaded profile faces are listed under the User profile face collection and returned by the profile face list endpoint.
\- `approved_duplicate_status` on each face is one of `NOT_DUPLICATED` / `DUPLICATED`.
\- Embeddings (numeric vectors) are stored separately from the image. Deleting a session deletes the image and, by default, the embedding. An application that opted in to biometric-template retention keeps one image-free template anchored to the User after the session is deleted; it has a finite expiry and is purged on User deletion, a privacy-erasure deletion (deletion_instruction: "privacy_erasure"), or an explicit purge via /v3/biometric-templates/ (see /management-api/biometric-templates/overview).

\## Failure modes

\- `400` from face-search / upload-face — image has no detectable face, multiple faces, or is too low-quality. Re-capture and retry.
\- `404` on Lists API — wrong `list_id` or list deleted.
\- `403` — your role lacks permission on the `lists` resource.
\- `429` — rate-limited.

\## Response shape

See /standalone-apis/face-search and /management-api/lists/upload-face for full schemas. Match objects use `similarity` (0–1) and reference the linked User `vendor_data` when known.

\## Sources of truth

\- /management-api/users/upload-face — attach an imported face to a User profile
\- /standalone-apis/face-search — face search request / response
\- /management-api/lists/upload-face — face blocklist upload
\- /management-api/lists/delete-entry — remove from list
\- /management-api/biometric-templates/overview — templates retained after session deletion
\- /core-technology/face-search/overview — search behaviour
\- /core-technology/liveness/overview — face capture during sessions
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

貼り付け先

顔の生体情報は、すべてのユーザーエンティティの中核です。Diditは[ライブネス検知](https://docs.didit.me/ja/core-technology/liveness/overview.md)の際に顔を撮影し、ベクトルエンベディングを生成して保存します。保存した顔は、**1:N顔検索**、**重複検出**、**ブロックリストの適用**、**生体認証による再認証**という4つの後続機能で使われます。> [!NOTE]
>
> 保存された顔は[生体認証](https://docs.didit.me/ja/core-technology/biometric-auth/overview.md)の参照画像も兼ねます。ユーザーの`vendor_data`を指定し、`portrait_image`を省略して生体認証セッションを作成すると、Diditは保存済みの顔を自動的に再利用します。優先順位は、承認済みのライブネスチェックで取得した顔、ePassportチップの写真、本人確認書類の顔写真、手動で登録したプロフィールの顔の順です。## 顔がユーザーに紐付く仕組み**1. ライブネス検知中に撮影**ユーザーがライブネスを有効にしたセッションを開始すると、Diditはセルフィーを撮影し、パッシブライブネス検知を実行します。続いて最も大きく写っている顔を抽出し、検索用のベクトルエンベディングを生成します。**2. ユーザープロフィールに保存**顔はセッションと、その親であるユーザーエンティティに紐付けられます。顔写真のURLは、ユーザープロフィール上で`portrait_image`として表示されます。**3. 検索用にインデックス化**エンベディングは検索インデックスに追加されます。以降のセッションでは、このインデックスに対して1:N検索を実行できます。## 顔検索 (1:N)顔検索では、画像をアップロードし、アプリケーションに登録されているすべての顔と照合することでユーザーを見つけられます。ユースケース:- オンボーディング時の**重複検出**：同一人物が2つのアカウントを作成するのを防ぎます。
- **逆引き検索**：防犯カメラの映像のフレームや、不正調査で得た画像に写っているユーザーを特定します。
- **リピーターの識別**：再訪した顧客のKYCを省略します。ワークフローで重複検出が有効になっている場合、新しいセッションでは顔検索が自動的に実行されます。単体のAPIとしても提供しています。- `POST /v3/face-search/`：[単体の顔検索](https://docs.didit.me/ja/standalone-apis/face-search.md)## 重複検出新しい顔はそれぞれ、登録済みの顔と比較することで重複を検出できます。Diditは各顔に`approved_duplicate_status`を割り当てます。| ステータス | 意味 |
| - | - |
| `NOT_DUPLICATED` | 類似度のしきい値を超える一致は見つかりませんでした |
| `DUPLICATED` | すでに承認済みのセッションにある1つ以上の顔と一致しています |ワークフローでは次のいずれかを設定できます。- 重複フラグが付いたセッションを自動的に**却下**する。
- **レビュー対象としてフラグ付け**する：アナリストによる手動レビューに回します。
- **警告のみ**：通過させたうえでリスクタグを付与します。この設定はコンソールの *Workflows → \[対象のワークフロー] → Face Match / Liveness → Duplicate detection* で行います。## 顔ブロックリストセッションが却下されると(ルール、アナリスト、ワークフロー設定のいずれによる場合も)、関連する顔はアプリケーションの**顔ブロックリスト**に自動的に追加されます。以降、顔が一致するセッションは拒否されます。## インポートした顔をユーザープロフィールにアップロードする別のKYCプロバイダーから移行する場合は、先にユーザーを作成してから、信頼できる顔画像をそのプロフィールに添付できます。ユーザーは引き続き`vendor_data`をキーとして管理されますが、顔のアップロード用エンドポイントでは対象を一意に特定するため、Didit内部のユーザーID(`didit_internal_id`)を使用します。**1. ユーザーを作成または取得する**安定した`vendor_data`を指定して[`POST /v3/users/create/`](https://docs.didit.me/ja/management-api/users/create)を呼び出します。ユーザーがすでに存在する場合は`GET /v3/users/{vendor_data}/`を呼び出します。**2. didit\_internal\_idを読み取る**ユーザーのレスポンスには`didit_internal_id`が含まれます。自社システムでは引き続き`vendor_data`を使用し、`didit_internal_id`はプロフィールへの添付用エンドポイントでのみ使用してください。**3. 顔をアップロードする**base64でエンコードした顔画像を指定して、[`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](https://docs.didit.me/ja/management-api/users/upload-face)を呼び出します。```bash theme={null}
# 1. Create or retrieve the User keyed by your vendor_data
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "previous_provider": "legacy-kyc-vendor" }
  }'

# Response includes:
# { "didit_internal_id": "11111111-2222-3333-4444-555555555555", ... }

# 2. Upload the imported face to the User profile
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/11111111-2222-3333-4444-555555555555/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'
```インポートしたプロフィールの顔は、重複検出と顔検索で使用されるものと同じ顔インデックスに登録されます。自動的にブロックリストに追加されることはありません。既知の不正行為者をブロックするには、代わりに顔タイプのリストに顔をアップロードしてください。> [!WARNING]
>
> アップロードしてよいのは、自社のプライバシーポリシーと移行契約のもとで処理が認められている顔のみです。移行元プロバイダーの識別子を`metadata`または`comment`に保持するのは、それをコンプライアンス担当者に開示しても問題ない場合に限ってください。### ブロックリストへの追加が行われる仕組み| トリガー | アクション |
| - | - |
| セッションが`DECLINED`となり、自動ブロックリストが有効になっている | 顔がシステムの顔リストに追加され、ユーザーステータスが`BLOCKED`に変わります |
| アナリストがコンソールから手動で顔をブロックリストに追加する | 顔が追加され、ユーザーステータスはポリシーに従って更新されます |
| Lists APIを使ってプログラムから追加する | 顔画像を顔タイプのブロックリストにアップロードします |### ブロックリストに顔をアップロードするプログラムから顔によってユーザーをブロックするには、専用の[リストへの顔のアップロード](https://docs.didit.me/ja/management-api/lists/upload-face.md)エンドポイントを使い、顔タイプのブロックリストに顔画像をアップロードします。Diditは顔エンベディングを抽出して照合用インデックスに登録します。以降、ライブネスのセルフィーが一致したセッションはすべて自動的に却下されます。> [!NOTE]
>
> プロフィールへの顔のアップロードと、顔ブロックリストへのアップロードは別の操作です。信頼できるインポート済みの顔を、証跡、重複検出、顔検索のためにユーザーへ添付するには、プロフィールへのアップロードを使用します。顔をブロックし、以降に一致したセッションを拒否するには、[Lists API](https://docs.didit.me/ja/management-api/lists/overview.md)を使用します。### ブロックリストから顔を削除するコンソールの *Blocklist → Faces → 行のアクション → Remove* からエントリーを削除するか、[エントリーの削除](https://docs.didit.me/ja/management-api/lists/delete-entry.md)エンドポイントを使用します。## セッション削除後に保持される生体認証テンプレートセッションを削除すると顔画像が削除され、デフォルトでは顔エンベディングも削除されます。そのため、その人物は重複検知と顔検索の対象から外れます。承認後すぐにセッションを削除しつつ、重複登録は引き続き検出したい場合は、アプリケーションで[生体認証テンプレートの保持](https://docs.didit.me/ja/console/data-retention.md#生体認証テンプレートの保持)を有効にするか、削除呼び出しで`retain_face_embeddings: true`を送信してください。この場合、Diditは通常どおりセッションとそのすべてのデータを削除し、ユーザーに紐づけて、画像を含まない顔の生体認証テンプレートを1件、別途管理して保持します。- このテンプレートに含まれるのは、数値化された顔テンプレートと保持に関するメタデータのみです。顔画像、ライブネス動画、書類データ、抽出された本人情報のフィールド、判定、削除されたセッションのIDは一切含まれません。
- このテンプレートは、通常のセッションの顔とまったく同じように、重複検知、顔検索、生体認証、および顔リストの対象になります。一致は`source: "retained_template"`、ユーザーの`vendor_user_id`と`vendor_data`、および`biometric_template_id`とともに報告されます。
- このテンプレートは有限の`expires_at`を持つ生体データです。ユーザーが削除されたとき、そのユーザーのいずれかのセッションが`deletion_instruction: "privacy_erasure"`で削除されたとき、有効期限に達したとき、または**Lists → 生体認証テンプレート**や[生体認証テンプレートAPI](https://docs.didit.me/ja/management-api/biometric-templates/overview.md)で削除したときに完全に削除されます。
- `vendor_data`なしで作成されたセッションには、テンプレートを紐づけるユーザーが存在しません。このセッションを削除すると`ineligible_no_vendor_user`が報告され、エンベディングはセッションとともに削除されます。
- 保持されたテンプレートがブロックリストに登録されることはありません。削除されたセッションから作成された顔ブロックリストのエントリは、独自の生体認証エントリとライフサイクルを持ちます。ユーザーに紐づけられたテンプレートは、ユーザープロフィールの**生体認証テンプレート**に削除アクションとともに表示されます。## 顔のライフサイクルの概要```mermaid theme={null}
stateDiagram-v2
    [*] --> Enrolled: Face captured during liveness
    Enrolled --> Approved: Session approved
    Enrolled --> Declined: Session declined
    Declined --> Blocklisted: Auto-blocklist enabled
    Enrolled --> Duplicated: 1:N search finds match
    Duplicated --> Approved: Allowed by workflow
    Duplicated --> Declined: Rejected by workflow
    Blocklisted --> [*]: Manually removed
    Approved --> [*]: Session deleted (default)
    Approved --> RetainedTemplate: Session deleted with retention enabled
    RetainedTemplate --> [*]: Expiry, User deletion, privacy erasure, or purge
```## コンソールから顔をアップロードコンプライアンス担当者は、顔を手動でアップロードできます。1) *Users → \[user] → Actions → Upload face*に移動します。
2) 画像を選択します。Diditは最も大きな顔を抽出し、ユーザーに紐づく新しいFaceレコードとして保存します。
3) その顔は、プロフィールの証拠、重複検知、顔検索の対象として登録されます。今後照合で一致したセッションを却下することが目的の場合は、ブロックリストの画面を使用してください。これは次のような場合に役立ちます。- オフラインで認証済みの顧客の顔写真が手元にある場合。
- 不正対策データベースにある既知の不正行為者をブロックリストに事前登録したい場合。## プライバシーとデータ保持- 顔エンベディングは画像ではなく数値ベクトルです。画像そのものは暗号化されたオブジェクトストレージに保存され、署名付きURLでアクセスします。顔エンベディングは生体データです。
- 保持期間はアプリケーションの[データ保持](https://docs.didit.me/ja/console/data-retention.md)ポリシーに従います。保持された生体認証テンプレートには、より厳格で期限が定められた[生体認証テンプレートの保持](https://docs.didit.me/ja/console/data-retention.md#生体認証テンプレートの保持)期間が適用されます。
- セッションを削除すると画像が削除され、デフォルトではエンベディングも削除されます。アプリケーションで生体認証テンプレートの保持を有効にしている場合、セッションを削除しても、画像を含まないテンプレートが有効期限に達するか削除されるまで保持されます。
- GDPR / CCPAに基づく忘れられる権利の請求には、その人物のセッションを`deletion_instruction: "privacy_erasure"`で削除するか、ユーザーを削除してください。どちらの方法でも、保持されたテンプレートもすべて完全に削除されます。管理している顔ブロックリストのエントリは、削除するまで残ります。## 次のステップ> [card] [顔検索](https://docs.didit.me/ja/core-technology/face-search/overview.md)
>
> 1:Nの顔検索の仕組み。> [card] [ライブネス検知](https://docs.didit.me/ja/core-technology/liveness/overview.md)
>
> 顔を捉えるライブネス検知。> [card] [ブロックリストAPI](https://docs.didit.me/ja/management-api/lists/upload-face.md)
>
> 顔をブロックリストにアップロードします。> [card] [生体認証テンプレート](https://docs.didit.me/ja/management-api/biometric-templates/overview.md)
>
> セッション削除後に保持されるテンプレート。> [card] [ユーザーブロックリスト](https://docs.didit.me/ja/entities/users/blocklist.md)
>
> ユーザーをブロックリストに登録する仕組み。


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