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

デフォルトでは、認証セッションを削除すると、そのセッションの顔検索1:Nと重複検知に使われていた顔エンベディングも削除されます。セッション削除後も重複検知を継続する必要があるアプリケーションは、生体認証テンプレートの保持をオプトインで有効にできます。この場合、Diditは通常どおりセッションとそのすべてのデータを削除したうえで、セッションのユーザーに紐づけた、画像を含まない顔の生体認証テンプレートを1件、別途管理して保持します。生体認証テンプレートAPIを使うと、アプリケーションが保持しているテンプレート、その保持理由と保持期限を正確に確認でき、いつでもパージできます。すべてのテンプレートは、Business ConsoleのLists → Biometric templatesと、紐づくユーザーのプロフィールでも確認できます。

保持された生体認証テンプレートは生体データです。匿名ではなく、一時的なものでもなく、セッションとともに削除されることもありません。予定された有効期限、適用法令上それより早い期限、ユーザーの削除、プライバシーに関する削除リクエスト、明示的なパージのいずれかまで保持され続けます。保持を有効にするのは、データ管理者からの指示とプライバシー通知がこれを対象としている場合に限ってください。

テンプレートが作成される仕組み

トリガー	`source_type`	指示の出どころ
オプトイン済みのアプリケーションでセッションを削除した場合、またはセッションの削除やセッションの一括削除で`retain_face_embeddings: true`を送信した場合	`session_delete`	`instruction_source: api`または`console`
アプリケーション全般のデータ保持期間により、オプトイン済みのアプリケーションでセッションが期限切れになった場合	`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`	操作者のメールアドレス

テンプレートはテナント単位で分離され、お客様のアプリケーション内で、お客様の指示がある場合にのみ使用されます。用途は、顔の重複と複数アカウントの検知、生体認証、お客様独自の顔リストです。モデルの学習、分析、組織をまたいだ照合、ネットワークの共有シグナル、Diditによる独自の不正対策処理に使われることは一切ありません。

テンプレートオブジェクト

{
  "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、生体認証、およびお客様の顔リストです。保持テンプレートでのヒットは、source: "retained_template"、所有するユーザーのvendor_user_idとvendor_data、そしてbiometric_template_idとともに報告されます。その顔を生成したセッションはすでに存在しないため、ヒットにセッションID、照合画像、本人情報、ステータスが含まれることはありません。詳しくは顔検索レポートを参照してください。保持テンプレートがブロックリストに登録されることはありません。削除されたセッションの顔が顔ブロックリストに登録されていた場合、そのブロックリストのエントリーは、独立した生体情報エントリーと独自のライフサイクルを維持します。リストのエントリーを削除するとブロックリストのエントリーは削除され、テンプレートを消去してもリストのエントリーには影響しません。

消去ポイント

以下のいずれの場合も、テンプレートは照合から除外され、保存されたテンプレートは削除されます。

消去ポイント	方法
明示的な消去	`DELETE /v3/biometric-templates/{uuid}/`または`POST /v3/biometric-templates/delete/`、あるいはConsoleのLists → Biometric templates
ユーザーの削除	`POST /v3/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/`	GET	フィルター付きのページネーション一覧
`/v3/biometric-templates/count/`	GET	同じフィルターでの件数
`/v3/biometric-templates/{template_uuid}/`	GET	1件のテンプレート
`/v3/biometric-templates/{template_uuid}/`	DELETE	1件のテンプレートを消去
`/v3/biometric-templates/delete/`	POST	IDリストまたはフィルターで消去

​テンプレートが作成される仕組み

​テンプレートに含まれる内容

​テンプレートオブジェクト

​ステータス

​照合でのテンプレートの利用方法

​消去ポイント

​監査証跡

​リーガルホールド

​権限と認証

​エンドポイント

​関連ページ