> ## 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 管理会话删除后保留的无图人脸生物特征模板，可列出、计数、筛选、查看和清除。



Biometric Templates API Prompt
        将提示词复制到剪贴板



      
      

\<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/zh/core-technology/face-search/overview.md)和重复检测提供支持的人脸特征向量。需要在会话删除后仍保持重复检测正常工作的应用，可以选择启用**生物特征模板保留**。启用后，Didit 会照常删除会话及其全部数据，但会保留一个单独管理、不含图像的人脸生物特征模板，并将其关联到该会话所属的[用户](https://docs.didit.me/zh/entities/users/overview.md)。Biometric Templates API 让您可以准确查看应用持有哪些模板、保留原因和保留期限，并可随时清除这些模板。每个模板也可在 Business Console 的 **Lists → Biometric templates** 中查看，并会显示在所属用户的个人资料中。> [!WARNING]
>
> 被保留的生物特征模板属于生物特征数据。它不是匿名数据，不是临时数据，也不会随会话一并删除。它将一直保留，直到预定到期时间、适用法律规定的更早期限、用户被删除、提出隐私擦除请求或被明确清除。仅当您的控制者指令和隐私声明涵盖模板保留时，才应启用该功能。## 模板的创建方式| 触发条件 | `source_type` | 指令来源 |
| - | - | - |
| 您在已启用保留的应用上删除会话，或在[删除会话](https://docs.didit.me/zh/sessions-api/delete-session.md)或[批量删除会话](https://docs.didit.me/zh/management-api/sessions/batch-delete.md)中发送 `retain_face_embeddings: true` | `session_delete` | `instruction_source: api` 或 `console` |
| 您应用的常规[数据保留期限](https://docs.didit.me/zh/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、编号、决策结果、提取的身份信息字段或特征 payload |
| 所属用户（`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/zh/core-technology/biometric-auth/overview.md)，以及您自己的人脸名单。模板绝不用于模型训练、分析、跨组织比对、[网络](https://docs.didit.me/zh/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` | 字符串或 null | 用户当前的 `vendor_data`，在您读取模板时解析。 |
| `source_type` | 枚举 | `session_delete`、`automatic_retention` 或 `backfill`。 |
| `provenance_reference` | UUID | 不透明引用，用于将模板与其审计追踪关联。它不是已删除会话的 ID，也无法通过 API 解析为该会话。 |
| `retention_policy` | 枚举 | 保留时适用的应用策略：`delete_with_session` 或 `retain_until_user_deleted`。 |
| `retention_override` | 布尔值或 null | 删除请求中发送的 `retain_face_embeddings` 值；若适用的是策略，则为 `null`。 |
| `retained_at` | 日期时间 | 模板的创建时间。 |
| `expires_at` | 日期时间 | 模板到期并被自动清除的时间。始终有值。 |
| `retained_by` | 字符串 | 发出指令的主体：API 密钥对应应用 ID，控制台操作对应控制台成员 ID，自动保留对应 `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` | 字符串 | 您在删除请求中发送的 `instruction_id`；若您未提供，则为 Didit 生成的 ID。 |
| `held_out_of_use` | 布尔值 | 仅在法律保全适用期间为 `true`。被暂停使用的模板会被排除在所有比对之外。参见[法律保全](#法律保全)。 |
| `status` | 枚举 | 生命周期状态，见下文。 |
| `purged_at` | 日期时间或 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/zh/standalone-apis/face-search.md)、[生物识别认证](https://docs.didit.me/zh/core-technology/biometric-auth/overview.md)，以及您的人脸名单。命中已保留模板时，结果会以 `source: "retained_template"`、所属用户的 `vendor_user_id` 和 `vendor_data`，以及 `biometric_template_id` 进行报告。结果中绝不包含会话 ID、比对图像、身份信息或状态，因为产生该人脸的会话已不复存在。参见[人脸搜索报告](https://docs.didit.me/zh/core-technology/face-search/report-face-search.md)。已保留的模板绝不会被加入黑名单。如果已删除会话中的人脸曾位于人脸黑名单中，该黑名单条目会保有自己独立的生物识别条目和生命周期：移除名单条目会删除黑名单条目，而清除模板不会影响名单。## 清除时机以下所有操作都会将模板移出比对范围，并删除已存储的模板：| 清除时机 | 方式 |
| - | - |
| 显式清除 | [`DELETE /v3/biometric-templates/{uuid}/`](https://docs.didit.me/zh/management-api/biometric-templates/purge) 或 [`POST /v3/biometric-templates/delete/`](https://docs.didit.me/zh/management-api/biometric-templates/batch-purge)，或在控制台中进入 **Lists → Biometric templates** |
| 用户删除 | [`POST /v3/users/delete/`](https://docs.didit.me/zh/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`）。商业控制台用户令牌会被拒绝，并返回 `403`。控制台用户需具备其 `lists` 权限，才能通过 **Lists → Biometric templates** 管理模板。## 端点| 端点 | 方法 | 用途 |
| - | - | - |
| [`/v3/biometric-templates/`](https://docs.didit.me/zh/management-api/biometric-templates/list) | GET | 带筛选条件的分页列表 |
| [`/v3/biometric-templates/count/`](https://docs.didit.me/zh/management-api/biometric-templates/count) | GET | 使用相同筛选条件统计数量 |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/zh/management-api/biometric-templates/get) | GET | 获取单个模板 |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/zh/management-api/biometric-templates/purge) | DELETE | 清除单个模板 |
| [`/v3/biometric-templates/delete/`](https://docs.didit.me/zh/management-api/biometric-templates/batch-purge) | POST | 按 ID 列表或筛选条件清除 |## 相关内容- [删除会话](https://docs.didit.me/zh/sessions-api/delete-session.md)
- [批量删除会话](https://docs.didit.me/zh/management-api/sessions/batch-delete.md)
- [数据保留](https://docs.didit.me/zh/console/data-retention.md#生物特征模板保留)
- [人脸与生物识别](https://docs.didit.me/zh/entities/users/faces-and-biometrics.md)


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