删除会话 API：GDPR 被遗忘权

curl -X DELETE \
  https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/ \
  -H 'x-api-key: YOUR_API_KEY'

{
  "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
}

DELETE

session

{sessionId}

delete

curl -X DELETE \
  https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/ \
  -H 'x-api-key: YOUR_API_KEY'

{
  "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
}

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，请参阅迁移指南。

已定稿监管报告中的数据

如果会话所属案件已有定稿的监管报告，请求将返回 409，且不会删除任何内容。响应使用 code: in_filed_report，并列出每份报告的名称：

{
  "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"
    }
  ]
}

使用删除报告删除每份报告，然后再次删除会话。删除报告并不会删除会话，在您再次调用此接口之前，会话仍会保留。

人脸生物识别数据的删除或保留

每个带活体自拍的 KYC 会话都包含一个人脸特征向量，它支持人脸搜索 1:N 和重复检测。默认情况下，该特征向量随会话一并删除（face_retention_policy: delete_with_session），因此您删除了其会话的用户可以再次验证，而不会被标记为重复。如果应用需要在会话删除后仍保留重复检测能力，可以选择启用生物特征模板保留。Didit 会照常删除会话及其全部数据，并保留一个独立管理、不含图像的人脸生物特征模板，该模板与会话所属的用户绑定。

保留的生物特征模板属于生物识别数据。它不是匿名数据，不是临时数据，也不会随会话一并删除。它会一直保留，直到计划到期时间、更早的适用法律期限、用户被删除、隐私擦除请求或明确的清除操作为止。仅当您的控制者指令和隐私声明涵盖此项时，才启用保留功能。

保留的模板包含什么，不包含什么：

已保留	永不保留
用于比对的数值化人脸模板	人脸图像、活体视频、证件图像、人像裁剪图以及其他任何媒体文件
一个新的随机模板 ID 和一个不透明的 `provenance_reference`	已删除会话的 ID、编号、决策、提取的身份字段或特征 payload
所属用户（`vendor_user_uuid`、当前 `vendor_data`）	黑名单状态、历史匹配记录、欺诈标签或跨机构身份声明
保留元数据：`retained_at`、`expires_at`、策略、覆盖设置、指令类别、`instruction_id` 以及执行操作的主体 ID	操作人的电子邮件地址

保留策略可在三个位置配置，按从宽到窄排列：

应用策略，位于 Business Console → App Settings → Data retention，或通过 PATCH /v3/webhook/ 设置（face_retention_policy、face_retention_days）。参见数据保留。
单次调用覆盖，在本端点和批量删除会话上使用 retain_face_embeddings。
指令类别，使用 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 会自动生成一个，可在模板详情中查看。

响应

{
  "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 管理。
`none`	会话没有可删除或保留的人脸特征向量（例如 KYB 会话，或未包含活体自拍的 KYC 会话）。
`ineligible_no_vendor_user`	已请求保留，但该会话未关联用户（创建时未提供 `vendor_data`），因此无法绑定模板。会话及其特征向量已删除。该不符合条件的结果已记录在审计日志中。

响应仅确认 Didit 已接受并执行了您的删除指令。它不是擦除证明：请在您自己的擦除日志中保存 instruction_id，以便日后将其与审计日志对应。

保留时长与到期

每个已保留模板都有一个有限的 expires_at。Didit 会将其设为以下各项中最早的时间：

请求中的 face_retention_days；若请求中省略，则为应用的 face_retention_days；
应用的通用数据保留期限（若已配置）；
请求中的 face_retention_deadline（若提供）。

若某次请求会在没有任何有限时长的情况下保留模板，则该请求会被拒绝并返回 400，且不会删除任何数据。已保留的模板的存续时间不得超过最早的适用客户指令、目的终止时间、已配置的到期时间、数据主体的擦除指令或法定生物识别期限。您有责任选择符合用户所适用法律的时长；只要适用规则要求，就应选择更短的时长。

隐私擦除

deletion_instruction: "privacy_erasure" 用于代表数据主体处理请求时。Didit 会先清除与会话所属用户绑定的所有已保留生物特征模板，然后删除该会话及其人脸特征向量。应用的保留策略无法覆盖隐私擦除指令，retain_face_embeddings: true 会被拒绝并返回 400。使用批量删除用户删除用户时，也会清除其已保留的模板。

不受影响的内容

删除会话不会为你清理以下内容。如果你正在处理删除权请求，需要单独处理这些内容。

黑名单条目：由会话创建的（人脸或证件）黑名单条目会保留。请从黑名单中移除。人脸黑名单条目保留其自身的生物特征条目，与任何已保留的生物特征模板无关。
分享 token：会话已签发的分享 token 不会被撤销，但已无可导入的内容：使用该 token 调用导入会返回 400 及 {"share_token": ["Original session does not exist."]}。
已送达的 Webhook：会话已送达的 Webhook 不受影响。仍在排队的投递及其重试会被丢弃。删除操作本身不会发出 Webhook。
已消耗的额度：验证已消耗的额度不予退还。
已通过邮件发送给签署人的已签署副本：由电子签名步骤发送给签署人的副本保留在签署人的邮箱中，不受影响。
上级用户或企业实体不会被删除。请分别使用删除用户或删除企业。如果用户的头像来自被删除的会话，则该头像会被移除。
已保留的生物特征模板（仅在你选择加入时）会一直保留，直到过期或你将其清除。你可以通过生物特征模板 API清除，也可以删除该用户，或对同一用户的另一个会话重复执行带有 deletion_instruction: "privacy_erasure" 的删除。

示例

curl -X DELETE https://verification.didit.me/v3/session/4c5c7f3a-.../delete/ \
  -H "x-api-key: YOUR_API_KEY"

未选择加入的应用的响应：

{
  "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
}

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"}'

{
  "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
}

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}'

{
  "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
}

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"}'

先清除该会话用户的所有已保留模板，然后再删除会话：

{
  "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
}

创建时未传入 vendor_data 的会话没有可关联生物特征模板的用户：

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}'

{
  "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
}

curl -X DELETE https://verification.didit.me/v3/session/bs-01HJX1.../delete/ \
  -H "x-api-key: YOUR_API_KEY"

企业验证会与为其关键人员创建的三项验证一并删除：

{
  "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 个匹配的会话，并返回每个会话的结果；超出的部分将作为删除任务运行。参见批量删除会话。

从 204 响应迁移

在此版本之前，该端点返回 204 No Content。现在它返回 200 OK 及上文所述的 JSON 响应体，使每次删除都能报告其 face_retention_outcome。请更新对 204 进行断言的客户端。默认行为保持不变：现有应用继续使用 delete_with_session，迁移不会代你启用保留。请在控制台中启用，或通过 PATCH /v3/webhook/ 显式启用。

​KYC 与 KYB 支持

​行为

​已定稿监管报告中的数据

​人脸生物识别数据的删除或保留

​请求体

​响应

​保留时长与到期

​隐私擦除

​不受影响的内容

​示例

​错误

​权限

​批量删除

​从 204 响应迁移

​相关内容

授权

路径参数

请求体

响应

KYC 与 KYB 支持

行为

已定稿监管报告中的数据

人脸生物识别数据的删除或保留

请求体

响应

保留时长与到期

隐私擦除

不受影响的内容

示例

错误

权限

批量删除

从 204 响应迁移

相关内容