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

# 生体認証テンプレートAPI：保持された顔テンプレートの管理

> Didit APIで、セッション削除後もアプリケーションに保持される画像なしの顔の生体認証テンプレートを一覧表示・件数取得・フィルター・詳細確認・完全削除できます。



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



      
      

\<pre>

\`Manage the biometric templates my Didit application retains after deleting verification sessions.

What a biometric template is:
When an application opts in (face_retention_policy: "retain_until_user_deleted", or retain_face_embeddings: true on a delete call), deleting a KYC session deletes the session and all of its data but keeps ONE image-free face biometric template anchored to the session's User. The template keeps duplicate-face, multi-account, biometric-authentication, and list matching working for that person. It contains the numeric face template plus retention metadata only — never the face image, liveness video, document data, extracted identity fields, the decision, or the deleted session's id. It is biometric data: not anonymous, not transient, and not deleted with the session. It has a finite expires_at.

Endpoints (base https://verification.didit.me, header x-api-key: YOUR_API_KEY; API keys only — Console user tokens get 403):
\- GET  /v3/biometric-templates/            — paginated list (limit/offset). Filters: vendor_data (substring, case-insensitive), vendor_user_uuid, status, source_type, retained_from, retained_to (ISO 8601), ordering (retained_at | -retained_at | expires_at | -expires_at; default -retained_at). Purged templates are not listed.
\- GET  /v3/biometric-templates/count/      — {"count": n} with the same filters.
\- GET  /v3/biometric-templates/{uuid}/     — one template.
\- DELETE /v3/biometric-templates/{uuid}/   — purge one template. 200 {"uuid": "...", "outcome": "purged" | "already_purged"}.
\- POST /v3/biometric-templates/delete/     — bulk purge. Body: {"template_uuids": ["..."]} OR {"delete_all": true} plus optional filters (vendor_data, vendor_user_uuid, status, source_type, retained_from, retained_to) that narrow delete_all. 200 {"results": [{"uuid": "...", "outcome": "purged" | "already_purged"}]}.

Template object:
\{
"uuid": "<template id>",
"vendor_user_uuid": "<User id>",
"vendor_data": "<the User's current vendor_data, resolved live>",
"source_type": "session_delete" | "automatic_retention" | "backfill",
"provenance_reference": "<opaque UUID, not the deleted session id>",
"retention_policy": "delete_with_session" | "retain_until_user_deleted",
"retention_override": true | false | null,
"retained_at": "<ISO 8601>",
"expires_at": "<ISO 8601>",
"retained_by": "<principal id: application UUID for API keys, Console member id, or service:...>",
"retained_by_type": "API_KEY" | "CONSOLE_USER" | "SYSTEM",
"instruction_class": "operational_session_delete" | "privacy_erasure",
"instruction_source": "api" | "console" | "automatic_retention" | "backfill" | "privacy_erasure" | "explicit_template_purge" | "vendor_user_delete" | "expiry" | "reconciliation" | "migration" | "system",
"instruction_id": "<your instruction_id or a Didit-generated one>",
"held_out_of_use": false,
"status": "pending" | "active" | "expired" | "held_out_of_use" | "purge_pending" | "purge_failed" | "purged",
"purged_at": null | "<ISO 8601>"
}
Only status "active" templates that are not held_out_of_use, not past expires_at, and whose User still exists take part in matching.

Purge points (all remove the template from matching and delete the stored template):
\- DELETE /v3/biometric-templates/{uuid}/ or POST /v3/biometric-templates/delete/
\- POST /v3/users/delete/ for the owning User
\- any session deletion for that User sent with deletion_instruction: "privacy_erasure"
\- automatic expiry at expires_at
Switching the application policy back to delete_with_session does NOT purge existing templates — purge them explicitly.

Failure modes:
\- 400 — {"template_uuids": ["This field is required unless delete_all is true."]} on bulk purge without a selector; invalid filter values.
\- 403 — {"detail": "You do not have permission to perform this action."} (Console user token, or key not allowed).
\- 404 — {"detail": "Biometric template not found."} on GET of an unknown or purged template.
\- 503 — {"detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable."} The template moves to status purge_failed and is already excluded from matching; repeat the purge.

Every retain and purge attempt, including failures, is recorded on Didit's audit trail with the acting principal, instruction class, instruction_source, instruction_id, and outcome.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`

\</pre>



      
      

貼り付け先

デフォルトでは、認証セッションを削除すると、そのセッションの[顔検索1:N](https://docs.didit.me/ja/core-technology/face-search/overview.md)と重複検知に使われていた顔エンベディングも削除されます。セッション削除後も重複検知を継続する必要があるアプリケーションは、**生体認証テンプレートの保持**をオプトインで有効にできます。この場合、Diditは通常どおりセッションとそのすべてのデータを削除したうえで、セッションの[ユーザー](https://docs.didit.me/ja/entities/users/overview.md)に紐づけた、画像を含まない顔の生体認証テンプレートを1件、別途管理して保持します。生体認証テンプレートAPIを使うと、アプリケーションが保持しているテンプレート、その保持理由と保持期限を正確に確認でき、いつでもパージできます。すべてのテンプレートは、Business Consoleの**Lists → Biometric templates**と、紐づくユーザーのプロフィールでも確認できます。> [!WARNING]
>
> 保持された生体認証テンプレートは生体データです。匿名ではなく、一時的なものでもなく、セッションとともに削除されることもありません。予定された有効期限、適用法令上それより早い期限、ユーザーの削除、プライバシーに関する削除リクエスト、明示的なパージのいずれかまで保持され続けます。保持を有効にするのは、データ管理者からの指示とプライバシー通知がこれを対象としている場合に限ってください。## テンプレートが作成される仕組み| トリガー | `source_type` | 指示の出どころ |
| - | - | - |
| オプトイン済みのアプリケーションでセッションを削除した場合、または[セッションの削除](https://docs.didit.me/ja/sessions-api/delete-session.md)や[セッションの一括削除](https://docs.didit.me/ja/management-api/sessions/batch-delete.md)で`retain_face_embeddings: true`を送信した場合 | `session_delete` | `instruction_source: api`または`console` |
| アプリケーション全般の[データ保持期間](https://docs.didit.me/ja/console/data-retention.md)により、オプトイン済みのアプリケーションでセッションが期限切れになった場合 | `automatic_retention` | `instruction_source: automatic_retention` |
| オプトイン前に削除されたセッションを対象として、お客様の指示によりDiditが実施するバックフィル | `backfill` | `instruction_source: backfill` |保持にはユーザーへの紐づけが必要です。`vendor_data`なしで作成されたセッションにはユーザーが存在しないため、テンプレートを保持できません。この場合、削除時に`ineligible_no_vendor_user`が報告され、エンベディングはセッションとともに削除されます。## テンプレートに含まれる内容| 保持されるもの | 保持されないもの |
| - | - |
| 照合に使われる数値形式の顔テンプレート | 顔画像、ライブネス動画、書類画像、顔写真の切り抜き、その他すべてのメディア |
| 新たにランダム生成されたテンプレートの`uuid`と、不透明な`provenance_reference` | 削除されたセッションのID、番号、判定、抽出された本人情報フィールド、特徴量のペイロード |
| 所有するユーザー(`vendor_user_uuid`)。`vendor_data`はテンプレートの取得時にユーザーから取得され、コピーされることはありません | ブロックリストの状態、過去の一致、不正ラベル、組織間のアイデンティティクレーム |
| `retained_at`、`expires_at`、`retention_policy`、`retention_override`、`instruction_class`、`instruction_source`、`instruction_id`、`retained_by`、`retained_by_type` | 操作者のメールアドレス |テンプレートはテナント単位で分離され、お客様のアプリケーション内で、お客様の指示がある場合にのみ使用されます。用途は、顔の重複と複数アカウントの検知、[生体認証](https://docs.didit.me/ja/core-technology/biometric-auth/overview.md)、お客様独自の顔リストです。モデルの学習、分析、組織をまたいだ照合、[ネットワーク](https://docs.didit.me/ja/console/networks.md)の共有シグナル、Diditによる独自の不正対策処理に使われることは一切ありません。## テンプレートオブジェクト```json theme={null}
{
  "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b",
  "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f",
  "vendor_data": "user-42",
  "source_type": "session_delete",
  "provenance_reference": "6b1e8d2f-4a3c-4f9e-8c7d-1a2b3c4d5e6f",
  "retention_policy": "retain_until_user_deleted",
  "retention_override": null,
  "retained_at": "2026-08-28T10:15:42.318402Z",
  "expires_at": "2027-08-28T10:15:42.318402Z",
  "retained_by": "3c9e2b1f-7d4a-4e8b-9c1d-5f6a7b8c9d0e",
  "retained_by_type": "API_KEY",
  "instruction_class": "operational_session_delete",
  "instruction_source": "api",
  "instruction_id": "post-approval-cleanup-2026-08",
  "held_out_of_use": false,
  "status": "active",
  "purged_at": null
}
```| フィールド | 型 | 説明 |
| - | - | - |
| `uuid` | UUID | テンプレートID。ランダムに生成され、削除されたセッションやその顔から導出されたものではありません。 |
| `vendor_user_uuid` | UUID | 所有するユーザー。 |
| `vendor_data` | stringまたはnull | テンプレートの取得時点における、ユーザーの現在の`vendor_data`。 |
| `source_type` | enum | `session_delete`、`automatic_retention`、`backfill`のいずれか。 |
| `provenance_reference` | UUID | テンプレートを監査証跡に結びつける不透明な参照。削除されたセッションのIDではなく、API経由でそのセッションを特定することもできません。 |
| `retention_policy` | enum | 保持時点のアプリケーションポリシー。`delete_with_session`または`retain_until_user_deleted`。 |
| `retention_override` | booleanまたはnull | 削除時に送信された`retain_face_embeddings`の値。ポリシーが適用された場合は`null`。 |
| `retained_at` | datetime | テンプレートが作成された日時。 |
| `expires_at` | datetime | テンプレートが期限切れとなり、自動的にパージされる日時。常に設定されます。 |
| `retained_by` | string | 指示を行った主体。APIキーの場合はアプリケーションID、Console操作の場合はConsoleメンバーID、自動保持の場合は`service:`識別子です。メールアドレスになることはありません。 |
| `retained_by_type` | enum | `API_KEY`、`CONSOLE_USER`、`SYSTEM`のいずれか。 |
| `instruction_class` | enum | `operational_session_delete`または`privacy_erasure`。 |
| `instruction_source` | enum | `api`、`console`、`automatic_retention`、`backfill`、`privacy_erasure`、`explicit_template_purge`、`vendor_user_delete`、`expiry`、`reconciliation`、`migration`、`system`のいずれか。 |
| `instruction_id` | string | 削除時に送信した`instruction_id`。省略した場合はDiditが生成したID。 |
| `held_out_of_use` | boolean | リーガルホールドが適用されている間のみ`true`。ホールド中のテンプレートはすべての照合から除外されます。[リーガルホールド](#リーガルホールド)を参照してください。 |
| `status` | enum | ライフサイクルのステータス。以下を参照してください。 |
| `purged_at` | datetimeまたはnull | テンプレートがパージされた日時。 |### ステータス| `status` | 意味 | 照合に使われるか |
| - | - | - |
| `pending` | テンプレートを作成中です。テンプレートの作成元となった削除が`503`を返した場合は、削除を再度実行して完了させてください。 | いいえ |
| `active` | `expires_at`までテンプレートが照合に使われます。 | はい。ただし`held_out_of_use`が`true`の場合、または`expires_at`を過ぎた場合を除きます |
| `expired` | `expires_at`を過ぎ、自動パージが進行中です。 | いいえ |
| `held_out_of_use` | リーガルホールドが適用されています。 | いいえ |
| `purge_pending` | パージが進行中です。 | いいえ |
| `purge_failed` | 生体データストアが利用できなかったため、パージを完了できませんでした。パージを再度実行してください。その間、テンプレートは引き続き照合から除外されます。 | いいえ |
| `purged` | テンプレートは削除済みです。パージのレスポンスで`already_purged`としてのみ確認できます。パージ済みのテンプレートは一覧に表示されず、詳細の取得では`404`が返されます。 | いいえ |## 照合でのテンプレートの利用方法`active`テンプレートは、ライブセッションの顔と同じ方法で照合に使用されます。対象は、新しいセッション中の自動重複検知、単体の[顔検索API](https://docs.didit.me/ja/standalone-apis/face-search.md)、[生体認証](https://docs.didit.me/ja/core-technology/biometric-auth/overview.md)、およびお客様の顔リストです。保持テンプレートでのヒットは、`source: "retained_template"`、所有するユーザーの`vendor_user_id`と`vendor_data`、そして`biometric_template_id`とともに報告されます。その顔を生成したセッションはすでに存在しないため、ヒットにセッションID、照合画像、本人情報、ステータスが含まれることはありません。詳しくは[顔検索レポート](https://docs.didit.me/ja/core-technology/face-search/report-face-search.md)を参照してください。保持テンプレートがブロックリストに登録されることはありません。削除されたセッションの顔が顔ブロックリストに登録されていた場合、そのブロックリストのエントリーは、独立した生体情報エントリーと独自のライフサイクルを維持します。リストのエントリーを削除するとブロックリストのエントリーは削除され、テンプレートを消去してもリストのエントリーには影響しません。## 消去ポイント以下のいずれの場合も、テンプレートは照合から除外され、保存されたテンプレートは削除されます。| 消去ポイント | 方法 |
| - | - |
| 明示的な消去 | [`DELETE /v3/biometric-templates/{uuid}/`](https://docs.didit.me/ja/management-api/biometric-templates/purge)または[`POST /v3/biometric-templates/delete/`](https://docs.didit.me/ja/management-api/biometric-templates/batch-purge)、あるいはConsoleの**Lists → Biometric templates** |
| ユーザーの削除 | [`POST /v3/users/delete/`](https://docs.didit.me/ja/management-api/users/delete)は、ユーザーを削除する前に、そのユーザーに紐づくすべてのテンプレートを消去します |
| プライバシー消去 | `deletion_instruction: "privacy_erasure"`を指定して送信されたそのユーザーのセッションの削除では、いずれの場合も、アプリケーションのポリシーにかかわらず、そのユーザーに紐づくすべてのテンプレートを消去します |
| 有効期限切れ | `expires_at`を過ぎると、Diditがテンプレートを自動的に消去します |アプリケーションのポリシーを`delete_with_session`に戻すと新しいテンプレートは作成されなくなりますが、既存のテンプレートは消去**されません**。既存のテンプレートは明示的に消去してください。消去処理では、まず保存されたテンプレートを削除し、その後で初めてテンプレートを消去済みとしてマークします。そのため、消去リクエストが`503`を返した場合、テンプレートは`purge_failed`の状態になりますが、すでに照合からは除外されており、安全に再実行できます。すでに消去済みのテンプレートに対して消去を繰り返すと、`already_purged`が返されます。## 監査証跡保持と消去の試行はすべて、失敗や対象外となった結果も含めて、実行したプリンシパル（`retained_by` / 消去を行ったプリンシパルとその種別）、`instruction_class`、`instruction_source`、`instruction_id`、`provenance_reference`、および結果とともに記録されます。削除時には独自の`instruction_id`を送信し、Diditの監査証跡と自社の消去ログを照合できるようにしてください。監査エントリーに画像、ベクトル、本人情報フィールド、メールアドレスが含まれることはありません。## リーガルホールドリーガルホールドは例外であり、保持モードではありません。Diditが自らの判断でホールドを設定することはありません。ホールドは、お客様とのデータ処理契約に基づく文書化された指示、または管轄当局による拘束力のある命令に基づいてのみ設定されます。ホールドが適用されている間、テンプレートは`held_out_of_use`としてマークされます。テンプレートはあらゆる種類の照合と通常の復旧から除外され、検索対象になることは一切ありません。ホールドを作成または解除するAPIはありません。保持されているテンプレートに影響する命令を受けた場合は、Diditの担当者にお問い合わせください。## 権限と認証生体認証テンプレートのエンドポイントは、アプリケーションのAPIキー（`x-api-key`）のみを受け付けます。Business Consoleのユーザートークンは`403`で拒否されます。Consoleユーザーは、`lists`権限を使って**Lists → Biometric templates**からテンプレートを管理します。## エンドポイント| エンドポイント | メソッド | 用途 |
| - | - | - |
| [`/v3/biometric-templates/`](https://docs.didit.me/ja/management-api/biometric-templates/list) | GET | フィルター付きのページネーション一覧 |
| [`/v3/biometric-templates/count/`](https://docs.didit.me/ja/management-api/biometric-templates/count) | GET | 同じフィルターでの件数 |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/ja/management-api/biometric-templates/get) | GET | 1件のテンプレート |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/ja/management-api/biometric-templates/purge) | DELETE | 1件のテンプレートを消去 |
| [`/v3/biometric-templates/delete/`](https://docs.didit.me/ja/management-api/biometric-templates/batch-purge) | POST | IDリストまたはフィルターで消去 |## 関連ページ- [セッションの削除](https://docs.didit.me/ja/sessions-api/delete-session.md)
- [セッションの一括削除](https://docs.didit.me/ja/management-api/sessions/batch-delete.md)
- [データ保持](https://docs.didit.me/ja/console/data-retention.md#生体認証テンプレートの保持)
- [顔と生体情報](https://docs.didit.me/ja/entities/users/faces-and-biometrics.md)


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