> ## 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：GDPR 被遗忘权
> 通过 Didit 删除 KYC 或 KYB 会话及其全部数据。默认同时删除人脸特征向量；已选择加入的应用可保留不含图像的生物特征模板。
删除会话提示
将提示词复制到剪贴板
\
\`Delete a single Didit verification session and all of its data, and control what happens to the face biometric data.
Endpoint:
DELETE https://verification.didit.me/v3/session/{session_id}/delete/
Authentication:
Use the x-api-key header with your Didit API key. Privilege: delete:sessions.
Path parameter:
\- session_id (UUID) — works for both User Verification (KYC) and Business Verification (KYB) sessions. Didit resolves the id against both session types.
Optional JSON body (send Content-Type: application/json; omit the body entirely for the default behavior):
\- retain_face_embeddings (boolean | null) — override the application's face_retention_policy for this deletion. true keeps an image-free biometric template anchored to the session's User; false deletes the face embedding with the session; omit or null to follow the application policy.
\- face_retention_days (integer 1-3650) — finite retention duration for the template. Required when retaining unless the application already sets face_retention_days.
\- face_retention_deadline (ISO 8601 datetime, future) — optional hard expiry. The template expires at the earliest of face_retention_days, the application's data-retention window, and this deadline.
\- deletion_instruction ("operational_session_delete" default | "privacy_erasure") — privacy_erasure purges every retained biometric template for the session's User and never retains a new one, regardless of the application policy. Combining privacy_erasure with retain_face_embeddings: true is rejected with 400.
\- instruction_id (string, max 255) — your own durable reference for this deletion instruction (for example your erasure-ticket id). Stored on the audit trail and on any retained template.
curl examples:
Default (follow the application policy; delete_with_session unless you opted in):
curl -X DELETE https://verification.didit.me/v3/session//delete/ \
-H "x-api-key: "
Delete the session but keep an image-free biometric template for 365 days:
curl -X DELETE https://verification.didit.me/v3/session//delete/ \
-H "x-api-key: " \
-H "Content-Type: application/json" \
-d '{"retain_face_embeddings": true, "face_retention_days": 365}'
Right-to-erasure request (delete the session AND purge every retained template for that person):
curl -X DELETE https://verification.didit.me/v3/session//delete/ \
-H "x-api-key: " \
-H "Content-Type: application/json" \
-d '{"deletion_instruction": "privacy_erasure", "instruction_id": "dsar-2026-0142"}'
Response: 200 OK with a JSON body once the deletion has completed (this endpoint no longer returns 204):
\{
"session_id": "",
"session_number": 1024,
"face_retention_outcome": "deleted" | "retained_with_user" | "none" | "ineligible_no_vendor_user",
"biometric_template_uuid": "" | null,
"biometric_template_expires_at": "" | null,
"deleted_child_verifications": 0
}
\- deleted: the session and its face embedding are deleted (default behavior).
\- retained_with_user: the session is deleted; an image-free biometric template with the returned biometric_template_uuid stays anchored to the User until biometric_template_expires_at, User deletion, privacy erasure, or explicit purge. Manage it with GET/DELETE /v3/biometric-templates/{uuid}/.
\- none: the session had no face embedding (for example a KYB session or a document-only KYC session).
\- ineligible_no_vendor_user: retention was requested but the session has no linked User (no vendor_data), so nothing can anchor the template. The session and its embedding are deleted.
\- biometric_template_expires_at: when the retained template is deleted; null when no template is retained.
\- deleted_child_verifications: for a KYB session, how many verifications it created (its key people's KYC sessions and its corporate owners' KYB sessions, recursively) were deleted with it. Always 0 for a KYC session.
Behavior:
\- The session and every verification attempt it holds are deleted, including results a resubmission replaced: the decision, the extracted data, the associated feature records (ID verification, registry checks, documents, AML, IP, etc.), its reviews and activity log, and all stored files (document images, videos, portraits, selfies, POA documents, extra uploads, and E-signature documents, signed PDFs, evidence PDFs and signature images).
\- A KYB session is deleted together with the verifications it created for its key people and corporate owners. A verification it only links to (for example a reused, already approved KYC) is not deleted.
\- The session disappears immediately from /v3/sessions/ and /v3/session/{id}/decision/, and media URLs issued before the call stop resolving.
\- Webhook deliveries still queued for the session, and their retries, are dropped. Webhooks already delivered are not affected.
\- Ongoing AML monitoring and KYB registry monitoring started by the deleted verifications stop.
\- A retained biometric template never contains the face image, liveness video, document data, extracted identity fields, the decision, or the deleted session's id. It is biometric data, tenant-scoped, used only for your duplicate-face, multi-account, biometric-authentication, and list matching, and it is never used for model training or cross-customer fraud processing.
\- Share tokens issued for the session are NOT revoked, but there is nothing left for them to import: an import with one returns 400 {"share_token": ["Original session does not exist."]}.
\- Blocklist entries created from the session are NOT removed; manage those with the Lists endpoints.
\- Credits already consumed by the verification are NOT refunded.
\- The parent User or Business entity is NOT deleted; use POST /v3/users/delete/ or POST /v3/businesses/delete/ for those. Deleting the User also purges its retained biometric templates. If the User's profile portrait came from this session, the portrait is removed.
\- No webhook fires for the deletion itself.
Idempotency:
Idempotent in effect: the second call to the same session returns 404 because the session no longer exists. Deletion is permanent and cannot be undone.
Failure modes:
\- 400: {"retain_face_embeddings": ["Privacy erasure cannot retain biometric templates."]} or {"detail": "A finite biometric-template retention duration is required."} (retention requested without face_retention_days on the request or the application). Nothing is deleted.
\- 403: {"detail": "You do not have permission to perform this action."} when the key lacks delete:sessions.
\- 404: {"detail": "Not found."} when the session does not exist (or was already deleted).
\- 409: {"detail": "...", "code": "in_filed_report", "reports": [{"uuid": "...", "report_number": "SAR-0001", "report_type": "SAR", "case_uuid": "..."}]} when the session is part of a finalized regulatory report. Nothing is deleted. Delete the reports, then repeat the request.
\- 503: {"detail": "The session could not be deleted because a storage service or a monitoring provider is unavailable. The session is still in place; repeat the request to finish deleting it."} or {"detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable."} The session is still in place; repeat the same request until it returns 200. Some of its stored files or its face embedding may already be deleted. Retries converge on a single template.
Bulk delete:
For many KYC sessions at once, use POST /v3/sessions/delete/ with body {"session_numbers": ["1001", "1002"]} or {"delete_all": true}; it accepts the same retention and instruction fields. Up to 20 matching sessions return 200 with a per-session outcome; more return 202 with a job to poll at GET /v3/sessions/delete/{job_id}/.
Migration note:
Until this release the endpoint returned 204 No Content. It now returns 200 OK with the JSON body above. Update clients that assert on 204. The default deletion behavior is unchanged: existing applications stay on delete_with_session until you explicitly change the policy.
When to call:
\- Customer requests data erasure (GDPR Article 17): use deletion_instruction: "privacy_erasure".
\- Operational clean-up after approval while keeping duplicate detection: retain_face_embeddings: true with a finite face_retention_days.
\- Cleaning up test sessions from a staging application.
\- After exporting a decision PDF for long-term archival outside Didit.
For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`
\
粘贴到
## KYC 与 KYB 支持同时适用于 **用户验证（KYC）** 和 **企业验证（KYB）** 会话。`session_id` 会同时在两种会话类型中查找，删除行为相同。生物识别模板的保留仅适用于 KYC 会话，因为只有 KYC 会话包含人脸特征向量。## 行为- 会话及其包含的所有验证尝试都会被删除，包括被重新提交替换的结果：其决策、提取的数据、关联的功能记录（身份证件验证、登记机构查询、证件、AML、IP 分析等）、审核记录和活动日志，以及其所有已存储的文件。
- 删除 **企业验证（KYB）** 会话时，也会递归删除为其关键人员（KYC）和企业所有人（KYB）创建的验证。响应中的 `deleted_child_verifications` 会给出删除数量。仅与之关联而未创建的验证（例如其复用的已通过 KYC）不会被删除。
- 电子签名数据随之删除：待签署文档及其原始 Word 文件、已签署的 PDF、证据 PDF、签名图像以及所有字段值。其下载路径将返回 `404`。
- 会话会立即从列表和决策响应中消失，调用之前签发的媒体 URL 将停止解析。
- 仍在排队等待发送的会话 Webhook 投递及其重试都会被丢弃。
- 已删除验证所启动的持续 AML 监控和 KYB 注册信息监控将停止。
- 删除是永久且不可撤销的。不存在用于恢复的 endpoint，因此在调用之前，请导出您需要的内容，例如决策 PDF。
- 删除完成后才会返回 `200 OK` 响应，响应的 JSON 正文会报告该会话的人脸生物识别数据的处理结果。如果您的客户端仍然期望 `204`，请参阅[迁移指南](#从-204-响应迁移)。## 已定稿监管报告中的数据如果会话所属案件已有定稿的监管报告，请求将返回 `409`，且不会删除任何内容。响应使用 `code: in_filed_report`，并列出每份报告的名称：```json theme={null}
{
"detail": "This session is part of a finalized regulatory report, so it cannot be deleted.",
"code": "in_filed_report",
"reports": [
{
"uuid": "5ec00000-0000-4000-8000-000000000007",
"report_number": "SAR-0001",
"report_type": "SAR",
"case_uuid": "c1a5e000-0000-4000-8000-000000000001"
}
]
}
```使用 [删除报告](https://docs.didit.me/zh/management-api/regulatory-reports/delete.md) 删除每份报告，然后再次删除会话。删除报告并不会删除会话，在您再次调用此接口之前，会话仍会保留。## 人脸生物识别数据的删除或保留每个带活体自拍的 KYC 会话都包含一个人脸特征向量，它支持 [人脸搜索 1:N](https://docs.didit.me/zh/core-technology/face-search/overview.md) 和重复检测。默认情况下，该特征向量随会话一并删除（`face_retention_policy: delete_with_session`），因此您删除了其会话的用户可以再次验证，而不会被标记为重复。如果应用需要在会话删除后仍保留重复检测能力，可以选择启用**生物特征模板保留**。Didit 会照常删除会话及其全部数据，并保留一个独立管理、不含图像的人脸生物特征模板，该模板与会话所属的[用户](https://docs.didit.me/zh/entities/users/overview.md)绑定。> [!WARNING]
>
> 保留的生物特征模板属于生物识别数据。它不是匿名数据，不是临时数据，也不会随会话一并删除。它会一直保留，直到计划到期时间、更早的适用法律期限、用户被删除、隐私擦除请求或明确的清除操作为止。仅当您的控制者指令和隐私声明涵盖此项时，才启用保留功能。保留的模板包含什么，不包含什么：| 已保留 | 永不保留 |
| - | - |
| 用于比对的数值化人脸模板 | 人脸图像、活体视频、证件图像、人像裁剪图以及其他任何媒体文件 |
| 一个新的随机模板 ID 和一个不透明的 `provenance_reference` | 已删除会话的 ID、编号、决策、提取的身份字段或特征 payload |
| 所属用户（`vendor_user_uuid`、当前 `vendor_data`） | 黑名单状态、历史匹配记录、欺诈标签或跨机构身份声明 |
| 保留元数据：`retained_at`、`expires_at`、策略、覆盖设置、指令类别、`instruction_id` 以及执行操作的主体 ID | 操作人的电子邮件地址 |保留策略可在三个位置配置，按从宽到窄排列：1) **应用策略**，位于 **Business Console → App Settings → Data retention**，或通过 `PATCH /v3/webhook/` 设置（`face_retention_policy`、`face_retention_days`）。参见[数据保留](https://docs.didit.me/zh/console/data-retention.md#生物特征模板保留)。
2) **单次调用覆盖**，在本端点和[批量删除会话](https://docs.didit.me/zh/management-api/sessions/batch-delete.md)上使用 `retain_face_embeddings`。
3) **指令类别**，使用 `deletion_instruction`。`privacy_erasure` 指令始终优先：它会清除该用户的所有已保留模板，且不会保留新的模板。### 请求体所有字段均为可选。若省略请求体，则遵循应用策略。| 字段 | 类型 | 说明 |
| - | - | - |
| `retain_face_embeddings` | boolean 或 null | 为本次删除覆盖应用策略。`true` 保留模板，`false` 随会话删除特征向量，`null` 或省略则遵循策略。 |
| `face_retention_days` | 整数（1-3650） | 模板的有限保留时长。当需要保留模板且应用未设置 `face_retention_days` 时必填。 |
| `face_retention_deadline` | 日期时间（ISO 8601） | 可选的硬性到期时间。必须晚于当前时间。 |
| `deletion_instruction` | `operational_session_delete`（默认）或 `privacy_erasure` | 您下达的指令类别。`privacy_erasure` 会在删除会话前清除该会话所属用户的所有已保留模板，且不能与 `retain_face_embeddings: true` 同时使用。 |
| `instruction_id` | 字符串（最多 255 个字符） | 您为本指令设定的持久引用，例如您的擦除工单 ID。它会记录在审计日志和任何已保留模板上。若省略，Didit 会自动生成一个，可在模板详情中查看。 |### 响应```json theme={null}
{
"session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
"session_number": 1024,
"face_retention_outcome": "retained_with_user",
"biometric_template_uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b",
"biometric_template_expires_at": "2027-10-09T10:15:00Z",
"deleted_child_verifications": 0
}
```| 字段 | 说明 |
| - | - |
| `session_id` | 已删除的会话。 |
| `session_number` | 已删除会话的编号。 |
| `face_retention_outcome` | 会话的人脸生物识别数据的处理结果。见下表。 |
| `biometric_template_uuid` | 当 `face_retention_outcome` 为 `retained_with_user` 时，为已保留生物特征模板的 ID；否则为 `null`。 |
| `biometric_template_expires_at` | 已保留生物特征模板的删除时间；未保留模板时为 `null`。 |
| `deleted_child_verifications` | 对于 KYB 会话，表示随其一并删除的、由其创建的验证数量（包括其关键人员的 KYC 会话和企业所有者的 KYB 会话，递归计算）。对于 KYC 会话，始终为 `0`。 || `face_retention_outcome` | 含义 |
| - | - |
| `deleted` | 会话及其人脸特征向量已删除。默认行为。 |
| `retained_with_user` | 会话已删除。一个不含图像的生物特征模板仍与用户绑定；其 ID 为 `biometric_template_uuid`。可通过[生物特征模板 API](https://docs.didit.me/zh/management-api/biometric-templates/overview.md) 管理。 |
| `none` | 会话没有可删除或保留的人脸特征向量（例如 KYB 会话，或未包含活体自拍的 KYC 会话）。 |
| `ineligible_no_vendor_user` | 已请求保留，但该会话未关联用户（创建时未提供 `vendor_data`），因此无法绑定模板。会话及其特征向量已删除。该不符合条件的结果已记录在审计日志中。 |响应仅确认 Didit 已接受并执行了您的删除指令。它不是擦除证明：请在您自己的擦除日志中保存 `instruction_id`，以便日后将其与审计日志对应。### 保留时长与到期每个已保留模板都有一个有限的 `expires_at`。Didit 会将其设为以下各项中最早的时间：1) 请求中的 `face_retention_days`；若请求中省略，则为应用的 `face_retention_days`；
2) 应用的通用数据保留期限（若已配置）；
3) 请求中的 `face_retention_deadline`（若提供）。若某次请求会在没有任何有限时长的情况下保留模板，则该请求会被拒绝并返回 `400`，且不会删除任何数据。已保留的模板的存续时间不得超过最早的适用客户指令、目的终止时间、已配置的到期时间、数据主体的擦除指令或法定生物识别期限。您有责任选择符合用户所适用法律的时长；只要适用规则要求，就应选择更短的时长。### 隐私擦除`deletion_instruction: "privacy_erasure"` 用于代表数据主体处理请求时。Didit 会先清除与会话所属用户绑定的所有已保留生物特征模板，然后删除该会话及其人脸特征向量。应用的保留策略无法覆盖隐私擦除指令，`retain_face_embeddings: true` 会被拒绝并返回 `400`。使用[批量删除用户](https://docs.didit.me/zh/management-api/users/delete.md)删除用户时，也会清除其已保留的模板。## 不受影响的内容删除会话不会为你清理以下内容。如果你正在处理删除权请求，需要单独处理这些内容。- **黑名单条目**：由会话创建的（人脸或证件）黑名单条目会保留。请从[黑名单](https://docs.didit.me/zh/entities/users/blocklist.md)中移除。人脸黑名单条目保留其自身的生物特征条目，与任何已保留的生物特征模板无关。
- **分享 token**：会话已签发的分享 token 不会被撤销，但已无可导入的内容：使用该 token 调用[导入](https://docs.didit.me/zh/sessions-api/share-session/import.md)会返回 `400` 及 `{"share_token": ["Original session does not exist."]}`。
- **已送达的 Webhook**：会话已送达的 Webhook 不受影响。仍在排队的投递及其重试会被丢弃。删除操作本身不会发出 Webhook。
- **已消耗的额度**：验证已消耗的额度不予退还。
- **已通过邮件发送给签署人的已签署副本**：由电子签名步骤发送给签署人的副本保留在签署人的邮箱中，不受影响。
- 上级**用户**或**企业**实体不会被删除。请分别使用[删除用户](https://docs.didit.me/zh/management-api/users/delete.md)或[删除企业](https://docs.didit.me/zh/management-api/businesses/delete.md)。如果用户的头像来自被删除的会话，则该头像会被移除。
- **已保留的生物特征模板**（仅在你选择加入时）会一直保留，直到过期或你将其清除。你可以通过[生物特征模板 API](https://docs.didit.me/zh/management-api/biometric-templates/purge.md)清除，也可以删除该用户，或对同一用户的另一个会话重复执行带有 `deletion_instruction: "privacy_erasure"` 的删除。## 示例> [tab] 默认（应用策略）
>
> ```bash theme={null}
> curl -X DELETE https://verification.didit.me/v3/session/4c5c7f3a-.../delete/ \
> -H "x-api-key: YOUR_API_KEY"
> ```
>
> 未选择加入的应用的响应：
>
> ```json theme={null}
> {
> "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
> "session_number": 1024,
> "face_retention_outcome": "deleted",
> "biometric_template_uuid": null,
> "biometric_template_expires_at": null,
> "deleted_child_verifications": 0
> }
> ```> [tab] 保留生物特征模板
>
> ```bash theme={null}
> curl -X DELETE https://verification.didit.me/v3/session/4c5c7f3a-.../delete/ \
> -H "x-api-key: YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{"retain_face_embeddings": true, "face_retention_days": 365, "instruction_id": "cleanup-2026-08-0142"}'
> ```
>
> ```json theme={null}
> {
> "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
> "session_number": 1024,
> "face_retention_outcome": "retained_with_user",
> "biometric_template_uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b",
> "biometric_template_expires_at": "2027-10-09T10:15:00Z",
> "deleted_child_verifications": 0
> }
> ```> [tab] 在已选择加入的应用上强制删除
>
> ```bash theme={null}
> curl -X DELETE https://verification.didit.me/v3/session/4c5c7f3a-.../delete/ \
> -H "x-api-key: YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{"retain_face_embeddings": false}'
> ```
>
> ```json theme={null}
> {
> "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
> "session_number": 1024,
> "face_retention_outcome": "deleted",
> "biometric_template_uuid": null,
> "biometric_template_expires_at": null,
> "deleted_child_verifications": 0
> }
> ```> [tab] 隐私擦除
>
> ```bash theme={null}
> curl -X DELETE https://verification.didit.me/v3/session/4c5c7f3a-.../delete/ \
> -H "x-api-key: YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{"deletion_instruction": "privacy_erasure", "instruction_id": "dsar-2026-0142"}'
> ```
>
> 先清除该会话用户的所有已保留模板，然后再删除会话：
>
> ```json theme={null}
> {
> "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
> "session_number": 1024,
> "face_retention_outcome": "deleted",
> "biometric_template_uuid": null,
> "biometric_template_expires_at": null,
> "deleted_child_verifications": 0
> }
> ```> [tab] 没有用户的会话
>
> 创建时未传入 `vendor_data` 的会话没有可关联生物特征模板的用户：
>
> ```bash theme={null}
> curl -X DELETE https://verification.didit.me/v3/session/7a1e9c2d-.../delete/ \
> -H "x-api-key: YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{"retain_face_embeddings": true, "face_retention_days": 365}'
> ```
>
> ```json theme={null}
> {
> "session_id": "7a1e9c2d-5f4b-4c3a-8e2d-1b0a9f8e7d6c",
> "session_number": 1031,
> "face_retention_outcome": "ineligible_no_vendor_user",
> "biometric_template_uuid": null,
> "biometric_template_expires_at": null,
> "deleted_child_verifications": 0
> }
> ```> [tab] 企业验证（KYB）会话
>
> ```bash theme={null}
> curl -X DELETE https://verification.didit.me/v3/session/bs-01HJX1.../delete/ \
> -H "x-api-key: YOUR_API_KEY"
> ```
>
> 企业验证会与为其关键人员创建的三项验证一并删除：
>
> ```json theme={null}
> {
> "session_id": "0f3c9b7e-2d1a-4e5f-8c6b-7a9d8e1f2c3b",
> "session_number": 88,
> "face_retention_outcome": "none",
> "biometric_template_uuid": null,
> "biometric_template_expires_at": null,
> "deleted_child_verifications": 3
> }
> ```## 错误| 状态码 | 触发条件 | 响应体 |
| - | - | - |
| `400` | `privacy_erasure` 与 `retain_face_embeddings: true` 同时使用 | `{"retain_face_embeddings": ["Privacy erasure cannot retain biometric templates."]}` |
| `400` | 请求或应用中未指定有限的保留时长，却请求保留 | `{"detail": "A finite biometric-template retention duration is required."}` |
| `403` | 凭证缺少 `delete:sessions` 权限，或不拥有该会话 | `{"detail": "You do not have permission to perform this action."}` |
| `404` | 会话不存在或已被删除 | `{"detail": "Not found."}` |
| `503` | 删除会话时，存储服务或监控服务提供商不可用。 | `{"detail": "The session could not be deleted because a storage service or a monitoring provider is unavailable. The session is still in place; repeat the request to finish deleting it."}` |
| `503` | 保留或清除模板时，生物特征存储不可用。重试会收敛到单个模板。 | `{"detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable."}` |返回 `400` 时，不会删除任何内容。返回 `503` 时，会话仍然存在：请重复同一请求，直到返回 `200`。其部分存储文件或其人脸特征向量可能已被删除，因此在收到 `503` 后不要依赖它们。## 权限需要 `delete:sessions` 权限。同一权限同时适用于用户验证（KYC）和企业验证（KYB）会话，以及保留策略覆盖。## 批量删除对于 KYC 会话的批量操作，请使用 `POST /v3/sessions/delete/`。它接受相同的保留和指令字段。单次请求最多删除 20 个匹配的会话，并返回每个会话的结果；超出的部分将作为[删除任务](https://docs.didit.me/zh/management-api/sessions/get-deletion-job.md)运行。参见[批量删除会话](https://docs.didit.me/zh/management-api/sessions/batch-delete.md)。## 从 204 响应迁移在此版本之前，该端点返回 `204 No Content`。现在它返回 `200 OK` 及上文所述的 JSON 响应体，使每次删除都能报告其 `face_retention_outcome`。请更新对 `204` 进行断言的客户端。默认行为保持不变：现有应用继续使用 `delete_with_session`，迁移不会代你启用保留。请在控制台中启用，或通过 `PATCH /v3/webhook/` 显式启用。## 相关内容- [生物特征模板](https://docs.didit.me/zh/management-api/biometric-templates/overview.md)
- [数据保留](https://docs.didit.me/zh/console/data-retention.md)
- [会话概览](https://docs.didit.me/zh/sessions-api/overview.md)
## OpenAPI
````yaml zh/openapi-25.json DELETE /v3/session/{sessionId}/delete/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: 身份证件验证 API。使用 x-api-key 请求头进行身份验证。
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/session/{sessionId}/delete/:
delete:
tags:
- Sessions
summary: 删除验证会话（KYC 或 KYB）
description: >-
通过 `session_id` 删除单个验证会话，包括用户验证（KYC）或企业验证（KYB）。系统会先针对 KYC 会话解析该 ID，然后再针对
KYB 会话解析，因此两种类型的会话均可通过这一个 URL 删除。
**删除的内容：**
-
会话及其包含的每次验证尝试，包括重新提交所替换的结果：决策、提取的数据、所有相关功能记录（身份证件验证、人脸、活体检测、人脸比对、AML、公司登记核验、IP
分析等）、其审核记录以及活动日志。
- 会话拥有的所有存储文件：证件正/反面照片（完整版、裁剪版和隐私模糊处理版本）、证件采集视频、头像裁剪图、NFC
芯片头像和签名图像、人脸参考图像、活体视频、人脸比对源/目标图像、地址证明文件以及任何额外上传的文件（KYC）；已上传的公司文件和额外文件（KYB）。电子签名文件、已签名的
PDF、证据 PDF 和签名图像（KYC 和 KYB）：其下载路径将停止工作。之前签发的媒体
URL（`https:///...`）将停止解析。
- 会话的人脸数据。其人脸特征向量也会被删除，除非您选择保留无图像模板（请参阅**人脸生物识别数据**）。
- 仍在为该会话排队的 Webhook 投递及其重试。已投递的 Webhook 不受影响。
- 对于企业验证（KYB）会话：其为其关键人员（KYC）和企业所有者（KYB）递归创建的验证，在响应中报告为
`deleted_child_verifications`。它仅关联的验证（例如其复用的现有已通过 KYC）不会被删除。
该会话会立即从所有读取 endpoint 中消失：`GET /v3/session/{sessionId}/decision/` 返回
`404`，且 `GET /v3/sessions/` 不再将其列出。由被删除验证发起的持续 AML 监控和 KYB 公司登记监控将停止。
**不受影响的内容：**从此会话创建的黑名单条目（人脸或证件）**不会**被移除；请使用黑名单 endpoint
管理这些条目。为该会话签发的共享 token 不会被撤销，但已无内容可供其导入：使用此类 token 导入将返回 `400` 以及
`{"share_token": ["Original session does not
exist."]}`。已消耗的额度**不予**退款。父级用户或企业实体**不会**被删除；如需删除这些实体，请使用 `POST
/v3/users/delete/` 或 `POST
/v3/businesses/delete/`。如果用户的个人资料头像来自此会话，该头像将随之一并移除。
**人脸生物识别数据：**默认情况下，会话的人脸特征向量会随会话一起删除（`face_retention_outcome:
deleted`）。选择保留生物特征模板的应用（在 `PATCH /v3/webhook/` 上设置
`face_retention_policy: retain_until_user_deleted`），或带有
`retain_face_embeddings: true`
的请求，将保留一份单独管理的、不含图像的人脸生物特征模板并锚定到该会话的用户（`retained_with_user`），以便重复项检测、人脸搜索和生物识别认证继续工作。该模板绝不包含人脸图像、媒体、身份字段、决策或已删除会话的
ID；它是生物识别数据，将在 `biometric_template_expires_at` 时删除，或在用户删除、隐私清除或通过
`/v3/biometric-templates/`
显式清除时提前删除。没有关联用户的会话无法保留模板（`ineligible_no_vendor_user`）。对于数据主体请求，请发送
`deletion_instruction: privacy_erasure`：它会清除该用户的所有保留模板，且绝不保留新模板。
**不可逆：**删除是永久性的，没有恢复 endpoint。在调用之前，请导出您需要的任何内容（例如决策 PDF）。
**副作用：**删除操作不会发出 Webhook。
**响应：**删除完成后返回 `200 OK`，JSON 响应体报告
`face_retention_outcome`、保留模板的到期时间以及对于 KYB 会话的
`deleted_child_verifications`。此 endpoint 的早期版本返回 `204 No Content`；请更新断言
`204` 的客户端。请在您自己的清除日志中记录您的 `instruction_id`。
**幂等性：**在 HTTP 级别非幂等：首次调用返回 `200`；重复调用返回 `404`，因为该会话已无法解析。发生 `503`
后，会话仍然存在；重复相同的请求以完成删除。
**认证：**在 `x-api-key` 请求头中发送您的应用的 API 密钥；会话必须属于该应用。当控制台用户访问
token（`Authorization: Bearer ...`）携带 `delete:sessions` 权限时，也可以调用此
endpoint。认证和权限失败均返回 `403`；此 API 绝不返回 `401`。
**速率限制：**所有 POST/PATCH/DELETE endpoint 共享每个 API 密钥 300 次请求/分钟的写入预算；超出将返回
`429`。
如需通过数字 `session_number` 批量删除 KYC 会话，请改用 `POST /v3/sessions/delete/`。
**已提交的监管报告：**如果选定的数据处于已定稿的监管报告中，整个请求将被拒绝并返回 `409`，且不会删除任何内容。响应体使用 `code:
in_filed_report` 并列出每份报告的 `uuid`、`report_number`、`report_type` 和
`case_uuid`。删除这些报告，然后重试该请求。
operationId: delete_v3_session_by_id
parameters:
- in: path
name: sessionId
required: true
description: >-
要删除的用户验证（KYC）或企业验证（KYB）会话的
UUID（`session_id`），即创建会话时返回的值。必须是带连字符的标准规范 UUID — 非 UUID 值与该路由不匹配并返回
`404`。
schema:
type: string
format: uuid
example: 11111111-2222-3333-4444-555555555555
requestBody:
required: false
description: 可选。完全省略请求体，以遵循应用的数据保留策略执行操作性删除。
content:
application/json:
schema:
type: object
properties:
retain_face_embeddings:
type: boolean
nullable: true
description: >-
针对本次删除覆盖应用的 `face_retention_policy`。为 `true`
时，在会话删除后保留一个锚定到该会话用户的无图像人脸生物特征模板；为 `false`
时，随会话一同删除人脸特征向量；省略或设为 `null` 则遵循应用策略。对于 KYB
会话以及无人脸特征向量的会话，此项将被忽略。
example: true
face_retention_days:
type: integer
minimum: 1
maximum: 3650
description: >-
保留模板的有限保留时长（以天为单位）。除非应用已设置
`face_retention_days`，否则在保留模板时必填。模板的 `expires_at`
为此保留时长、应用的通用数据保留期和 `face_retention_deadline` 中的最早者。
example: 365
face_retention_deadline:
type: string
format: date-time
description: 保留模板的可选硬性到期时间。必须是将来的时间。
example: '2027-08-28T00:00:00Z'
deletion_instruction:
type: string
enum:
- operational_session_delete
- privacy_erasure
default: operational_session_delete
description: >-
您发出的指令类别。`operational_session_delete` 会删除会话，并且仅在策略或
`retain_face_embeddings` 要求时才保留模板。`privacy_erasure`
会在删除会话之前清除锚定到该会话用户的每个已保留生物特征模板，此操作不能被应用策略覆盖，也不能与
`retain_face_embeddings: true` 组合使用（`400`）。
example: operational_session_delete
instruction_id:
type: string
maxLength: 255
description: >-
您对该删除指令的持久化参考标识（例如删除工单 ID）。记录在审计追踪记录和任何保留的模板上。省略时由 Didit
自动生成。
example: dsar-2026-0142
examples:
Retain a biometric template:
summary: 删除会话，保留无图像的模板 365 天
value:
retain_face_embeddings: true
face_retention_days: 365
instruction_id: post-approval-cleanup-2026-08
Force deletion on an opted-in application:
summary: 无论应用策略如何，均删除人脸特征向量
value:
retain_face_embeddings: false
Privacy erasure:
summary: 数据主体请求：删除会话并清除该人员保留的所有模板
value:
deletion_instruction: privacy_erasure
instruction_id: dsar-2026-0142
responses:
'200':
description: 会话已删除。响应体报告了该会话人脸生物特征数据的处理结果，对于 KYB 会话，还报告了其创建的验证中有多少个已随之一同删除。
content:
application/json:
schema:
type: object
properties:
session_id:
type: string
format: uuid
description: 已删除的会话。
session_number:
type: integer
nullable: true
description: 已删除会话的编号。
face_retention_outcome:
type: string
enum:
- retained_with_user
- deleted
- none
- ineligible_no_vendor_user
description: >-
会话的人脸生物特征数据的处理结果。`deleted`：人脸特征向量随会话一同被删除（默认）。`retained_with_user`：会话被删除，且一个不含图像的生物特征模板继续锚定到用户；请参阅
`biometric_template_uuid`。`none`：该会话没有人脸特征向量（例如 KYB
会话，或没有活体自拍照的 KYC
会话）。`ineligible_no_vendor_user`：已请求保留，但该会话没有关联的用户，因此人脸特征向量随会话一同被删除。此
endpoint 从不通过该字段报告生物特征库故障：此时会返回 `503` 且会话不会被删除。
biometric_template_uuid:
type: string
format: uuid
nullable: true
description: >-
当 `face_retention_outcome` 为 `retained_with_user`
时保留的生物特征模板 ID；否则为 `null`。可通过
`/v3/biometric-templates/{template_uuid}/` 进行管理。
biometric_template_expires_at:
type: string
format: date-time
nullable: true
description: >-
当 `face_retention_outcome` 为 `retained_with_user`
时，保留的生物特征模板被删除的时间；未保留模板时为 `null`。
deleted_child_verifications:
type: integer
description: >-
对于企业验证（KYB）会话：与其一同删除的、由其创建的验证数量（递归包括其关键人员的 KYC 会话及其企业所有者的
KYB 会话）。对于 KYC 会话始终为 `0`。
examples:
Deleted (default):
value:
session_id: 4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02
session_number: 1024
face_retention_outcome: deleted
biometric_template_uuid: null
biometric_template_expires_at: null
deleted_child_verifications: 0
Retained with User:
value:
session_id: 4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02
session_number: 1024
face_retention_outcome: retained_with_user
biometric_template_uuid: 9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b
biometric_template_expires_at: '2027-10-09T10:15:00Z'
deleted_child_verifications: 0
'Ineligible: no User':
summary: 针对未提供 vendor_data 创建的会话请求了保留
value:
session_id: 7a1e9c2d-5f4b-4c3a-8e2d-1b0a9f8e7d6c
session_number: 1031
face_retention_outcome: ineligible_no_vendor_user
biometric_template_uuid: null
biometric_template_expires_at: null
deleted_child_verifications: 0
KYB session:
value:
session_id: 0f3c9b7e-2d1a-4e5f-8c6b-7a9d8e1f2c3b
session_number: 88
face_retention_outcome: none
biometric_template_uuid: null
biometric_template_expires_at: null
deleted_child_verifications: 3
summary: 已删除的企业验证及其为关键人员创建的三项验证
'400':
description: 验证错误 — 未删除任何内容。
content:
application/json:
examples:
Privacy erasure cannot retain:
value:
retain_face_embeddings:
- Privacy erasure cannot retain biometric templates.
No finite retention duration:
summary: 在请求或应用中未包含 face_retention_days 时请求了保留
value:
detail: >-
A finite biometric-template retention duration is
required.
'403':
description: >-
身份验证或权限失败。缺少密钥同样会返回 `403`；错误、已撤销或已过期的密钥将返回 `401`。例外情况：当 `sessionId`
无法解析为有效会话时，预认证所有者查找将优先返回 `404`，即使凭证缺失或无效也是如此。
content:
application/json:
schema:
type: object
properties:
detail:
type: string
examples:
Missing or invalid API key:
summary: 缺少 x-api-key 请求头，或该密钥无效
value:
detail: >-
Authentication credentials were not provided or are
invalid.
Insufficient permission:
summary: 没有 delete:sessions 权限的用户 token，或者不拥有该会话的应用的凭证
value:
detail: You do not have permission to perform this action.
'404':
description: >-
不存在具有此 `session_id` 的生产环境中的 KYC 或 KYB 会话：该 id
未知或会话已被删除（重复成功的删除操作将进入此状态）。
content:
application/json:
schema:
type: object
properties:
detail:
type: string
examples:
Not Found:
summary: 未知或已删除的会话
value:
detail: Not found.
'409':
description: 会话属于已定稿的监管报告的一部分。任何内容均未被删除。
content:
application/json:
schema:
$ref: '#/components/schemas/InFiledReportError'
'429':
description: >-
超出共享写入速率限制（每个 API 密钥每分钟 300 次 POST/PATCH/DELETE 请求）。重试前请检查
`Retry-After` 和 `X-RateLimit-*` 响应头。
content:
application/json:
schema:
type: object
properties:
detail:
type: string
examples:
Rate limited:
summary: 写入预算已耗尽
value:
detail: >-
Write request rate limit exceeded. You can make up to 300
requests per minute.
'503':
description: >-
由于存储服务、生物特征存储或监控提供商不可用，删除无法完成。会话仍然保留；请重复相同的请求，直到其返回
`200`。其存储的部分文件或其人脸特征向量可能已被删除，因此在收到 `503` 后请勿依赖它们。重试会收敛到单个模板。
content:
application/json:
schema:
type: object
properties:
detail:
type: string
examples:
Session deletion unavailable:
summary: 存储服务或监控提供商不可用
value:
detail: >-
The session could not be deleted because a storage service
or a monitoring provider is unavailable. The session is
still in place; repeat the request to finish deleting it.
Biometric store unavailable:
summary: 在保留或清除模板时生物特征存储库不可用
value:
detail: >-
The biometric-template operation could not finish because
an external store is unavailable. The operation is
retryable.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl (default policy)
source: |-
curl -X DELETE \
https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/ \
-H 'x-api-key: YOUR_API_KEY'
- lang: curl
label: curl (retain template)
source: |-
curl -X DELETE \
https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/ \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"retain_face_embeddings": true, "face_retention_days": 365}'
- lang: curl
label: curl (privacy erasure)
source: |-
curl -X DELETE \
https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/ \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"deletion_instruction": "privacy_erasure", "instruction_id": "dsar-2026-0142"}'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.sessions.delete(
"11111111-2222-3333-4444-555555555555",
retain_face_embeddings=True,
face_retention_days=365,
instruction_id="post-approval-cleanup-2026-08",
)
print(result)
- lang: javascript
label: Node.js
source: >-
import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await
didit.sessions.delete("11111111-2222-3333-4444-555555555555", {
retain_face_embeddings: true,
face_retention_days: 365,
instruction_id: "post-approval-cleanup-2026-08",
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Delete(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsDeleteParams{\n\tRetainFaceEmbeddings: didit.Bool(true),\n\tFaceRetentionDays: didit.Int(365),\n\tInstructionID: didit.String(\"post-approval-cleanup-2026-08\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import me.didit.Didit;
import me.didit.types.SessionsDeleteParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result =
client.sessions().delete("11111111-2222-3333-4444-555555555555",
SessionsDeleteParams.builder()
.retainFaceEmbeddings(true)
.faceRetentionDays(365L)
.instructionId("post-approval-cleanup-2026-08")
.build());
System.out.println(result);
- lang: php
label: PHP
source: >-
sessions->delete('11111111-2222-3333-4444-555555555555', [
'retain_face_embeddings' => true,
'face_retention_days' => 365,
'instruction_id' => 'post-approval-cleanup-2026-08',
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.sessions.delete(
"11111111-2222-3333-4444-555555555555",
retain_face_embeddings: true,
face_retention_days: 365,
instruction_id: "post-approval-cleanup-2026-08"
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await
client.Sessions.DeleteAsync("11111111-2222-3333-4444-555555555555",
new SessionsDeleteParams
{
RetainFaceEmbeddings = true,
FaceRetentionDays = 365,
InstructionId = "post-approval-cleanup-2026-08",
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
schemas:
InFiledReportError:
type: object
description: 由于所选数据包含在已定稿的监管报告中，删除被拒绝。没有任何内容被删除。请删除该报告，然后重试请求。
required:
- detail
- code
properties:
detail:
type: string
code:
type: string
enum:
- in_filed_report
description: 因最终监管报告阻止删除的稳定错误代码。
reports:
type: array
items:
$ref: '#/components/schemas/FiledRegulatoryReport'
description: 阻止删除个人、企业、案件或会话的报告。
transactions:
type: array
items:
$ref: '#/components/schemas/FiledReportTransaction'
description: 阻止删除该交易的交易列表，每笔均附带列出它的报告。
FiledRegulatoryReport:
type: object
description: 已定稿的监管报告，阻止了请求的删除操作。
required:
- uuid
- report_number
- report_type
- case_uuid
properties:
uuid:
type: string
format: uuid
description: 报告 UUID。
report_number:
type: string
description: 在控制台中显示的报告编号（例如 SAR-0001）。
report_type:
type: string
enum:
- SAR
- STR
- CTR
- TTR
- UTR
- IFT
- CBR
- TFR
description: 监管报告类型。
case_uuid:
type: string
format: uuid
description: 该报告所属的案件。
FiledReportTransaction:
type: object
description: 因已定稿的监管报告列出而无法删除的交易。
required:
- uuid
- transaction_id
- reports
properties:
uuid:
type: string
format: uuid
description: Didit 交易 UUID。
transaction_id:
type: string
description: 创建交易时提供的交易标识符。
reports:
type: array
items:
$ref: '#/components/schemas/FiledRegulatoryReport'
description: 列出此交易的已定稿报告。
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
您的应用 API 密钥，可在 Business Console 的“开发者 -> API
密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于
IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP
列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF
URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅
https://docs.didit.me/console/api-keys。
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.