> ## 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：KYC 清理 > 通过会话编号批量删除 KYC 会话，或一次性全部删除。Didit 对最多 20 个会话的选择返回每个会话的结果；更多会话则作为删除任务运行，需轮询查询进度。 批量删除会话提示 将提示词复制到剪贴板 \

\`Goal: Delete a list of User Verification (KYC) sessions, or every session, for the calling application, and control what happens to each session's face biometric data. KYC only — KYB sessions are not covered here; use DELETE /v3/session/{sessionId}/delete/ for a single KYB or KYC session.

Endpoint: POST https://verification.didit.me/v3/sessions/delete/
Auth header: x-api-key: YOUR_API_KEY
Content-Type: application/json

Request body — provide EXACTLY ONE selector:
\- session_numbers: string[] — UI-visible decimal session numbers ("#1234" style), NOT UUIDs. Each entry must be digits only (regex ^[0-9]+$). minItems: 1.
\- delete_all: true — delete every remaining KYC session for the application. When delete_all is true, session_numbers is ignored.

Narrowing delete_all (optional, only together with delete_all: true):
\- filter_ - any filter of GET /v3/sessions/ (see /sessions-api/list-sessions) prefixed with filter_, with the same values: filter_status, filter_workflow_id, filter_date_from, filter_date_to, filter_vendor_data, filter_country, filter_document_type, filter_warning, filter_search and the others. Filters that take several values in GET /v3/sessions/ (status, workflow_id, country, region, document_type, document_name, session_type, warning, organization_name) accept a comma-separated string or an array. The others take one value: an array is joined into one comma-separated value, so several dates, UUIDs or api_service values are refused with 400, and several texts are not matched as alternatives. An empty value is ignored and does not narrow the selection.
\- An unknown filter_* key returns 400 { "filter_": "Unknown filter." } and a value that cannot be read returns 400 keyed by that filter_* key (for example { "filter_date_from": ["Enter a valid date."] }). Nothing is deleted in either case.
\- A deletion job applies the same filters.

Optional retention and instruction fields (same semantics as the single-session endpoint, applied to every matched session):
\- retain_face_embeddings (boolean | null) — true keeps an image-free biometric template anchored to each session's User; false deletes the embedding with the session; omit/null follows the application's face_retention_policy.
\- face_retention_days (integer 1-3650) — required when retaining unless the application sets face_retention_days.
\- face_retention_deadline (ISO 8601 datetime, future) — optional hard expiry.
\- deletion_instruction ("operational_session_delete" default | "privacy_erasure") — privacy_erasure purges every retained template for each session's User and never retains a new one. Cannot be combined with retain_face_embeddings: true (400).
\- instruction_id (string, max 255) — your durable reference for this instruction; recorded on the audit trail and on every retained template.

curl:
curl -X POST 'https://verification.didit.me/v3/sessions/delete/' \
-H "x-api-key: YOUR_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"session_numbers": ["1001", "1002", "1003"]}'

Response: the number of matching sessions decides, whether they are selected by session_numbers or with delete_all.

Up to 20 matching sessions: they are deleted in the request. Response 200 (this endpoint no longer returns 204):
\{
"results": [
\{"session_id": "", "session_number": 1001, "face_retention_outcome": "deleted", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0},
\{"session_id": "", "session_number": 1002, "face_retention_outcome": "retained_with_user", "biometric_template_uuid": "", "biometric_template_expires_at": "", "deleted_child_verifications": 0},
\{"session_id": "", "session_number": 1003, "face_retention_outcome": "failed_retryable", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0}
]
}
face_retention_outcome per session:
\- deleted: session and face embedding deleted (default).
\- retained_with_user: session deleted; an image-free biometric template stays anchored to the User until biometric_template_expires_at (manage it via /v3/biometric-templates/).
\- none: the session had no face embedding.
\- ineligible_no_vendor_user: retention requested but the session has no linked User; session and embedding deleted.
\- failed_retryable: the group this session was deleted with could not be deleted (a storage service, a biometric store or a monitoring provider was unavailable). That session is NOT deleted and is still in place; re-run the request for it. Other groups in the same request are unaffected.
deleted_child_verifications is always 0 here: this endpoint deletes KYC sessions only.

More than 20 matching sessions: they are deleted in the background. Response 202 with a deletion job:
\{"job_id": "", "status": "PENDING", "total": 250, "processed": 0, "outcomes": {"deleted": 0, "none": 0, "retained_with_user": 0, "ineligible_no_vendor_user": 0, "failed_retryable": 0, "already_deleted": 0}, "deleted_child_verifications": 0, "error": null, "created_at": "", "completed_at": null}
Poll GET /v3/sessions/delete/{job_id}/ every few seconds until status is COMPLETED or FAILED. The job reports counts per outcome, never which sessions it deleted. A delete_all job deletes only the sessions created before the request. A FAILED job explains why in error; the sessions it had not reached are still in place, so repeat the request to delete them.

Side effects:
\- Each matched session is deleted along with everything it produced, including every verification attempt: its decision, its extracted data, its KYC / Face / AML / Location / POA / Phone / Email records, its reviews and activity log, and all of its stored files.
\- The sessions stop appearing in GET /v3/sessions/ and GET /v3/session/{sessionId}/decision/, and media URLs issued before the call stop resolving.
\- Webhook deliveries still queued for the deleted sessions, and their retries, are dropped. Webhooks already delivered are not affected.
\- Share tokens issued for the sessions 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 sessions are NOT removed.
\- Credits already consumed by the verifications are NOT refunded.
\- The parent User entities are NOT deleted; use POST /v3/users/delete/ for those (that also purges their retained templates).
\- NO deletion webhook is emitted.
\- Sessions are deleted in groups; a failure in one group does not roll back the others. Numbers that no longer match a live session are skipped and do not appear in results.

Idempotency: re-running with the same session_numbers deletes nothing more (numbers that no longer match a session are skipped). Deletion is permanent and cannot be undone.

Failure modes:
\- 400: validation, nothing deleted:
\{ "session_numbers": ["This field is required unless delete_all is true."] }
\{ "session_numbers": ["All session_numbers must be numeric."] }
\{ "retain_face_embeddings": ["Privacy erasure cannot retain biometric templates."] }
\{ "detail": "A finite biometric-template retention duration is required." }
\{ "filter_reviewer": "Unknown filter." }
\{ "filter_date_from": ["Enter a valid date."] }
\- 409: at least one selected session is part of a finalized regulatory report. Nothing is deleted. The body has code: in_filed_report and reports[] with uuid, report_number, report_type and case_uuid. Delete the reports, then repeat the request.
\- 403: API key invalid or application not allowed. { "detail": "You do not have permission to perform this action." }

Migration note: until this release the endpoint returned 204 with an empty body; it now returns 200 with results[], or 202 with a deletion job when more than 20 sessions match. Existing applications stay on delete_with_session until you explicitly change the policy.

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

\
粘贴到 ## 行为每个匹配的会话都会按照[删除会话](https://docs.didit.me/zh/sessions-api/delete-session.md)的方式删除：会话本身、其持有的每次验证尝试、决策和提取的数据、功能记录以及所有已存储的文件都会被删除，会话将从所有读取端点中消失，之前签发的媒体 URL 也将无法再解析。仍在为已删除会话排队的 Webhook 投递及其重试会被丢弃；已经送达的 Webhook 不受影响。删除是永久性的，且不可撤销。如果任一选定的会话属于已定稿的监管报告，则整个请求返回 `409`，且不会删除任何内容。响应中会使用 `code: in_filed_report`，并列出每份报告。请使用[删除报告](https://docs.didit.me/zh/management-api/regulatory-reports/delete.md)逐一删除这些报告，然后重新发送请求。删除报告不会删除会话；在您重新发送此请求之前，会话会一直保留。无论您使用 `session_numbers` 还是 `delete_all` 选择会话，匹配的会话数量决定了请求的响应方式：| 匹配的会话数 | 响应 | | - | - | | 最多 20 个 | 删除完成后返回 `200 OK`，并在 `results` 中为每个匹配的会话返回一条结果。 | | 超过 20 个 | 返回 `202 Accepted` 及删除作业。会话将在后台删除；请轮询[获取会话删除作业](https://docs.didit.me/zh/management-api/sessions/get-deletion-job.md)，直到作业完成。 |除非 `face_retention_outcome` 为 `failed_retryable`，否则结果即表示会话已被删除。在这种情况下，该会话**未**被删除，仍然保留，因此应将此结果视为需要重试的失败，而不能作为删除确认。 与您应用中有效 KYC 会话不匹配的编号会被跳过，且不会出现在 `results` 中。## 使用过滤器缩小 `delete_all` 的范围设置 `delete_all: true` 后，您可以使用[列出会话](https://docs.didit.me/zh/sessions-api/list-sessions.md)的过滤器缩小选择范围，每个过滤器都需加上 `filter_` 前缀。 它们接受的值与查询参数相同。 接受多个值的过滤器（`status`、`workflow_id`、`country`、`region`、`document_type`、`document_name`、`session_type`、`warning`、`organization_name`）可接受以逗号分隔的字符串或数组：```json theme={null} { "delete_all": true, "filter_status": ["Declined"], "filter_workflow_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "filter_date_from": "2026-09-01", "filter_date_to": "2026-09-30" } ```- 过滤器仅在与 `delete_all` 一起使用时生效；与 `session_numbers` 一起使用时，过滤器会被校验，但不会改变选择范围。 - 其他过滤器只接受一个值。 数组会被合并为一个以逗号分隔的值，因此传入多个日期、UUID 或 `api_service` 值会返回 `400`；传入多个 `vendor_data`、`search` 或 `screened_full_name` 文本时，它们不会被当作可选项进行匹配。 - 值为空的过滤器会被忽略，因此不会缩小选择范围。 - 未知的 `filter_*` 键会返回 `400` 和 `{"filter_reviewer": "Unknown filter."}`；无法解析的值会返回以该 `filter_*` 键为键的 `400`，例如 `{"filter_date_from": ["Enter a valid date."]}`。两种情况下都不会删除任何内容，因此输入错误的过滤器绝不会将删除范围扩大到所有会话。 - 删除作业应用相同的过滤器，并且与所有 `delete_all` 一样，它只涵盖在请求之前创建的会话。## 保留与指令字段该端点接受与单会话端点相同的可选字段，并将其应用于每个匹配的会话：| 字段 | 类型 | 说明 | | - | - | - | | `retain_face_embeddings` | 布尔值或 null | 为本次请求覆盖应用的 `face_retention_policy`。 | | `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 个字符） | 您为该指令提供的持久引用。会记录在审计日志和每个已保留模板上。 |有关已保留模板包含和不包含的内容、`expires_at` 的计算方式，以及隐私擦除指令的作用，请参阅[删除会话](https://docs.didit.me/zh/sessions-api/delete-session.md#人脸生物识别数据的删除或保留)。## 每个会话的结果对于最多 20 个匹配的会话，`200 OK` 会为每个会话返回一条结果：```json theme={null} { "results": [ { "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02", "session_number": 1001, "face_retention_outcome": "deleted", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0 }, { "session_id": "b8e1d2c3-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "session_number": 1002, "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": "7a1e9c2d-5f4b-4c3a-8e2d-1b0a9f8e7d6c", "session_number": 1003, "face_retention_outcome": "ineligible_no_vendor_user", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0 }, { "session_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "session_number": 1004, "face_retention_outcome": "failed_retryable", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0 } ] } ```每条结果包含的字段与[删除会话](https://docs.didit.me/zh/sessions-api/delete-session.md#响应)响应相同。`biometric_template_expires_at` 表示已保留模板被删除的时间；`deleted_child_verifications` 在此始终为 `0`，因为该端点仅删除 KYC 会话。| `face_retention_outcome` | 含义 | | - | - | | `deleted` | 会话及其人脸特征向量会被删除。默认行为。 | | `retained_with_user` | 会话会被删除。一个不含图像的生物特征模板仍绑定到用户；其 ID 为 `biometric_template_uuid`。 | | `none` | 该会话没有需要删除或保留的人脸特征向量。 | | `ineligible_no_vendor_user` | 已请求保留，但该会话未关联用户，因此没有可用于绑定模板的对象。会话及其特征向量会被删除。 | | `failed_retryable` | 与该会话一同删除的分组无法被删除，原因是存储服务、生物特征存储或监控服务提供方不可用。该会话**未**被删除，仍然保留。请针对该会话重新运行请求；多次重试会收敛到同一个模板。 |会话按组删除。当某个组无法删除时，该组中的每个会话都会被报告为 `failed_retryable`；其他组不受影响，并保持已删除状态。## 大量选择将作为任务运行当匹配的会话超过 20 个时，响应为 `202 Accepted`，并返回删除任务，而不是 `results`：```json theme={null} { "job_id": "5b8f2c1e-7d3a-4f6b-9e2c-1a0d8f7e6c5b", "status": "PENDING", "total": 250, "processed": 0, "outcomes": { "deleted": 0, "none": 0, "retained_with_user": 0, "ineligible_no_vendor_user": 0, "failed_retryable": 0, "already_deleted": 0 }, "deleted_child_verifications": 0, "error": null, "created_at": "2026-10-09T10:15:00Z", "completed_at": null } ```每隔几秒轮询一次 [获取会话删除任务](https://docs.didit.me/zh/management-api/sessions/get-deletion-job.md)，直到 `status` 变为 `COMPLETED` 或 `FAILED`。- 任务只报告每种结果中有多少个会话，从不报告具体删除了哪些会话。 - `delete_all` 任务只删除您发出请求之前创建的会话。任务运行期间新开始的会话不会被删除。 - 请求中的数据保留和指令字段适用于任务删除的每个会话。 - 如果某组会话暂时无法删除，任务会自行重试。 - 状态为 `FAILED` 的任务会在 `error` 中说明原因。任务尚未处理的会话仍然保留：重新发出请求即可删除它们。## 示例> [tab] 按数量删除 > > ```bash theme={null} > curl -X POST https://verification.didit.me/v3/sessions/delete/ \ > -H "x-api-key: YOUR_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{"session_numbers": ["1001", "1002", "1003"]}' > ```> [tab] 删除并保留模板 > > ```bash theme={null} > curl -X POST https://verification.didit.me/v3/sessions/delete/ \ > -H "x-api-key: YOUR_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{ > "session_numbers": ["1001", "1002"], > "retain_face_embeddings": true, > "face_retention_days": 365, > "instruction_id": "post-approval-cleanup-2026-08" > }' > ```> [tab] 隐私擦除 > > ```bash theme={null} > curl -X POST https://verification.didit.me/v3/sessions/delete/ \ > -H "x-api-key: YOUR_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{ > "session_numbers": ["1001"], > "deletion_instruction": "privacy_erasure", > "instruction_id": "dsar-2026-0142" > }' > ```> [tab] 全部删除并轮询任务 > > ```bash theme={null} > curl -X POST https://verification.didit.me/v3/sessions/delete/ \ > -H "x-api-key: YOUR_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{"delete_all": true}' > > # More than 20 sessions matched: the response is 202 with a job_id. > curl https://verification.didit.me/v3/sessions/delete/JOB_ID/ \ > -H "x-api-key: YOUR_API_KEY" > ```## 从 204 响应迁移在此版本之前，该端点返回 `204 No Content`。现在，它返回带有 `results[]` 的 `200 OK`；如果匹配的会话超过 20 个，则返回带有删除任务的 `202 Accepted`。请更新仍然断言 `204` 的客户端。默认删除行为保持不变：现有应用会继续使用 `delete_with_session`，直到您明确更改策略。## 相关内容- [删除会话](https://docs.didit.me/zh/sessions-api/delete-session.md) - [获取会话删除任务](https://docs.didit.me/zh/management-api/sessions/get-deletion-job.md) - [生物特征模板](https://docs.didit.me/zh/management-api/biometric-templates/overview.md) - [数据保留](https://docs.didit.me/zh/console/data-retention.md) ## OpenAPI ````yaml zh/openapi-25.json POST /v3/sessions/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/sessions/delete/: post: tags: - Sessions summary: 按 session_number 批量删除 KYC 会话 description: >- 通过数字形式的 `session_number` 批量删除用户验证（KYC）会话，或通过 `delete_all: true` 删除您应用中的所有 KYC 会话。 `session_number` 是控制台会话列表中显示的易于阅读的递增计数器，并在创建会话和决策 endpoint 中作为 `session_number` 返回；它**不是** `session_id` UUID。如需通过 UUID 删除会话，或删除企业验证（KYB）会话（本 endpoint 绝不涉及此类会话），请改用 `DELETE /v3/session/{sessionId}/delete/`。 **单次请求最多同步删除 20 个会话，超过则作为后台任务运行。** 无论会话是通过 `session_numbers` 还是 `delete_all` 选定，均由匹配的会话数量决定处理方式： - 最多 20 个匹配会话：在返回响应前完成删除，响应状态码为 `200`，并在 `results[]` 中为每个会话包含一个条目。 - 超过 20 个：响应状态码为 `202` 并返回一个删除任务，会话将在后台删除。请轮询 `GET /v3/sessions/delete/{job_id}/`，直至 `status` 为 `COMPLETED` 或 `FAILED`。任务仅报告每种结果的数量统计，绝不会报告具体删除了哪些会话。`delete_all` 任务仅删除在请求发起前创建的会话；任务运行期间启动的会话不会被删除。 每个被删除的会话均与单会话删除 endpoint 享受完全相同的处理方式：会话本身、其中包含的每次验证尝试、其决策和提取的数据、其相关功能记录（身份证件验证、人脸、活体检测、人脸比对等）以及所有存储的文件均会被删除，它将从所有读取 endpoint 中消失，并且之前签发的多媒体 URL 将停止解析。仍处于队列中等待投递给已删除会话的 Webhook 投递及其重试将被丢弃；已经投递的 Webhook 不受影响。黑名单条目**不会**被移除，已消耗的额度**不会**退还，上级用户实体**不会**被删除（如需删除请使用 `POST /v3/users/delete/`）；删除操作不会触发任何 Webhook。删除为永久性操作且不可逆。 **选择语义：** - 使用 `delete_all: true` 时，您可以使用 `GET /v3/sessions/` 的过滤器来缩小选择范围，每个过滤器前缀均为 `filter_`（例如 `filter_status`、`filter_workflow_id`、`filter_date_from`）。在获取会话列表中支持多个值的过滤器（`status`、`workflow_id`、`country`、`region`、`document_type`、`document_name`、`session_type`、`warning`、`organization_name`）可接收逗号分隔的字符串或数组；其余过滤器接收单一值。空值将被忽略。过滤器仅在与 `delete_all` 一起使用时生效，删除任务也会应用相同的过滤器。 - 未知的 `filter_*` 键或无法读取的过滤器值会在删除任何内容前拒绝整个请求并返回 `400`，因此拼写错误的过滤器绝不会导致删除范围扩大到所有会话。 - `session_numbers` 中与您应用内有效 KYC 会话不匹配的条目（未知编号、已删除的会话或属于其他应用的会话）将被**静默跳过**：它们不会出现在 `results` 中，也不会计入任务的 `total`。 - 验证失败（非数字条目、空列表、未提供 `session_numbers` 也未提供 `delete_all`，或者应用无法满足的模板保留设置）将拒绝**整个请求**并返回 `400`，且不会删除任何内容。 - 会话按组进行删除。如果某个组无法删除（例如存储服务不可用），该组中的每个会话都将被报告为 `face_retention_outcome: failed_retryable` 并保持原样；其他组不受影响。针对这些会话重新发起请求即可。后台任务会自动重试此类分组。 - 列表长度没有明确的文档上限；下文所述的共享写入速率限制是实际的约束边界。 **人脸生物特征数据：** 可选字段 `retain_face_embeddings`、`face_retention_days`、`face_retention_deadline`、`deletion_instruction` 和 `instruction_id` 的含义与 `DELETE /v3/session/{sessionId}/delete/` 相同，并适用于每个匹配的会话。每个结果都会报告自己的 `face_retention_outcome`。 **响应：** 对于最多 20 个匹配会话返回包含 `results[]` 的 `200 OK`，超过 20 个则返回包含删除任务的 `202 Accepted`。除 `face_retention_outcome: failed_retryable`（表示会话未被删除，应重试）外，每个结果均确认已完成删除。该 endpoint 的早期版本曾返回 `204 No Content`；请更新依赖 `204` 断言的客户端。 **幂等性：** 重复相同的请求不会删除更多内容：不再匹配会话的编号将被跳过。 **`delete_all: true`（破坏性操作）：** 删除应用中**所有**剩余的 KYC 会话；设置此项时将忽略 `session_numbers`。该操作没有确认步骤，且无法撤销。 **认证：** 在 `x-api-key` 请求头中传入 API 密钥。缺少凭据或凭据无效将返回 `403`（`{"detail": "You do not have permission to perform this action."}`）；此 API 绝不会返回 `401`。 **速率限制：** 每个 API 密钥在所有 POST/PATCH/DELETE endpoint 间共享 300 次请求/分钟的写入预算；超出限制将返回 `429`。 本 endpoint 仅接受 API 密钥。Business Console 用户 Bearer token 将被拒绝并返回 `403`（与单会话删除不同，后者两者均支持）。 **已提交的监管报告：** 如果选定的数据存在于已定稿的监管报告中，整个请求将被拒绝并返回 `409`，且不会删除任何内容。响应体使用 `code: in_filed_report`，并通过 `uuid`、`report_number`、`report_type` 和 `case_uuid` 指明各个报告。请先删除这些报告，然后重试请求。 operationId: batch_delete_sessions requestBody: required: true content: application/json: schema: type: object properties: session_numbers: type: array description: >- 要删除的 KYC 会话的纯数字字符串格式数字 `session_number` 值（也接受 JSON 数字并会进行强制转换）。除非 `delete_all` 为 `true`，否则为必填项；空列表将返回 `400`。任何非数字条目都会导致整个请求以 `400` 被拒绝（除非 `delete_all` 为 `true`，此时将跳过校验并忽略这些条目）。与您应用中的活动会话不匹配的数字将被直接忽略。 items: type: string pattern: ^[0-9]+$ example: '1001' minItems: 1 example: - '1001' - '1002' - '1003' delete_all: type: boolean description: >- 为 `true` 时，调用应用中所有剩余的 KYC 会话都将被删除，并且 `session_numbers` 将被忽略，除非您使用 `filter_*` 键缩小选择范围。匹配超过 20 个会话时将作为删除任务（`202`）运行，仅涵盖请求前创建的会话。默认为 `false`。不可逆；没有确认步骤。 default: false example: false 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 filter_status: description: >- 将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `status` 过滤器匹配的会话，取值相同。逗号分隔的字符串或数组。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。 oneOf: - type: string - type: array items: type: string filter_vendor_data: description: >- 将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `vendor_data` 过滤器匹配的会话，取值相同。单个值，而不是列表：数组会被拼接成一个逗号分隔的文本，因此多个值不会作为备选项进行匹配。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。 type: string filter_search: description: >- 将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `search` 过滤器匹配的会话，取值相同。单个值，而不是列表：数组会被拼接成一个逗号分隔的文本，因此多个值不会作为备选项进行匹配。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。 type: string filter_workflow_id: description: >- 将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `workflow_id` 过滤器匹配的会话，取值相同。逗号分隔的字符串或数组。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。 oneOf: - type: string - type: array items: type: string filter_date_from: description: >- 将 `delete_all` 缩小至与[列出会话](/zh/sessions-api/list-sessions)的 `date_from` 过滤器匹配且值相同的会话。单个值，非列表：数组会被连接为一个逗号分隔的值，因此多个值会被拒绝并返回 `400`。若无 `delete_all` 则忽略。空值会被忽略，且不会缩小选择范围。 type: string format: date filter_date_to: description: >- 将 `delete_all` 缩小至与[列出会话](/zh/sessions-api/list-sessions)的 `date_to` 过滤器匹配且值相同的会话。单个值，非列表：数组会被连接为一个逗号分隔的值，因此多个值会被拒绝并返回 `400`。若无 `delete_all` 则忽略。空值会被忽略，且不会缩小选择范围。 type: string format: date filter_country: description: >- 将 `delete_all` 缩小至与[列出会话](/zh/sessions-api/list-sessions)的 `country` 过滤器匹配且值相同的会话。逗号分隔的字符串或数组。若无 `delete_all` 则忽略。空值会被忽略，且不会缩小选择范围。 oneOf: - type: string - type: array items: type: string filter_document_type: description: >- 将 `delete_all` 缩小至与[列出会话](/zh/sessions-api/list-sessions)的 `document_type` 过滤器匹配且值相同的会话。逗号分隔的字符串或数组。若无 `delete_all` 则忽略。空值会被忽略，且不会缩小选择范围。 oneOf: - type: string - type: array items: type: string filter_document_name: description: >- 将 `delete_all` 缩小至与[列出会话](/zh/sessions-api/list-sessions)的 `document_name` 过滤器匹配且值相同的会话。逗号分隔的字符串或数组。若无 `delete_all` 则忽略。空值会被忽略，且不会缩小选择范围。 oneOf: - type: string - type: array items: type: string filter_region: description: >- 将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `region` 过滤器匹配的会话，取值相同。逗号分隔的字符串或数组。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。 oneOf: - type: string - type: array items: type: string filter_didit_internal_id: description: >- 将 `delete_all` 缩小至与[列出会话](/zh/sessions-api/list-sessions)的 `didit_internal_id` 过滤器匹配且值相同的会话。单个值，非列表：数组会被连接为一个逗号分隔的值，因此多个值会被拒绝并返回 `400`。若无 `delete_all` 则忽略。空值会被忽略，且不会缩小选择范围。 type: string format: uuid filter_session_type: description: >- 将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `session_type` 过滤器匹配的会话，取值相同。逗号分隔的字符串或数组。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。 oneOf: - type: string - type: array items: type: string filter_api_service: description: >- 将 `delete_all` 缩小至与[列出会话](/zh/sessions-api/list-sessions)的 `api_service` 过滤器匹配且值相同的会话。单个值，非列表：数组会被连接为一个逗号分隔的值，因此多个值会被拒绝并返回 `400`。若无 `delete_all` 则忽略。空值会被忽略，且不会缩小选择范围。 type: string filter_screened_full_name: description: >- 将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `screened_full_name` 过滤器匹配的会话，取值相同。单个值，而不是列表：数组会被拼接成一个逗号分隔的文本，因此多个值不会作为备选项进行匹配。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。 type: string filter_warning: description: >- 将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `warning` 过滤器匹配的会话，取值相同。逗号分隔的字符串或数组。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。 oneOf: - type: string - type: array items: type: string filter_status_initialized_as_in_review: description: >- 将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `status_initialized_as_in_review` 过滤器匹配的会话，取值相同。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。 type: boolean filter_is_kyc_to_be_reviewed: description: >- 将 `delete_all` 缩小至与[列出会话](/zh/sessions-api/list-sessions)的 `is_kyc_to_be_reviewed` 过滤器匹配且值相同的会话。若无 `delete_all` 则忽略。空值会被忽略，且不会缩小选择范围。 type: boolean filter_euuid: description: >- 将 `delete_all` 缩小至与[列出会话](/zh/sessions-api/list-sessions)的 `euuid` 过滤器匹配且值相同的会话。单个值，非列表：数组会被连接为一个逗号分隔的值，因此多个值会被拒绝并返回 `400`。若无 `delete_all` 则忽略。空值会被忽略，且不会缩小选择范围。 type: string format: uuid filter_organization_name: description: >- 将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `organization_name` 过滤器匹配的会话，取值相同。逗号分隔的字符串或数组。使用 API 密钥时只能匹配您自己组织的名称，因此它会选择您的所有会话或不选择任何会话。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。 oneOf: - type: string - type: array items: type: string examples: Specific sessions: summary: 按编号删除特定会话 value: session_numbers: - '1001' - '1002' - '1003' All sessions: summary: 删除应用中的所有 KYC 会话 value: delete_all: true Delete and retain templates: summary: 删除会话但保留无图像的生物特征模板 365 天 value: session_numbers: - '1001' - '1002' retain_face_embeddings: true face_retention_days: 365 instruction_id: post-approval-cleanup-2026-08 Privacy erasure: summary: 删除会话并清除其用户的所有留存模板 value: session_numbers: - '1001' deletion_instruction: privacy_erasure instruction_id: dsar-2026-0142 Filtered delete_all: summary: 删除某工作流在 2026 年 9 月创建的所有已拒绝会话 value: delete_all: true filter_status: - Declined filter_workflow_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 filter_date_from: '2026-09-01' filter_date_to: '2026-09-30' responses: '200': description: >- 请求中最多匹配并处理了 20 个会话。每个匹配的会话对应一条结果；未匹配任何内容的编号（未知或已删除）会被跳过且不显示。结果将确认删除，除非 `face_retention_outcome` 为 `failed_retryable`：该会话未被删除，应进行重试。 content: application/json: schema: type: object properties: results: type: array items: 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 - failed_retryable description: >- 会话的人脸生物特征数据的处理结果。`deleted`：人脸特征向量随会话一同被删除（默认）。`retained_with_user`：会话被删除，且一个不含图像的生物特征模板继续锚定到用户；请参阅 `biometric_template_uuid`。`none`：该会话没有人脸特征向量（例如仅验证证件而无需活体自拍照的 KYC 会话；此 endpoint 从不选择 KYB 会话）。`ineligible_no_vendor_user`：已请求保留，但该会话没有关联的用户，因此人脸特征向量随会话一同被删除。`failed_retryable`（仅限批量 endpoint）：此会话所属的批组无法被删除（存储服务、生物特征库或监控提供商不可用）；该会话仍保留在原处，请对其重新发起请求。 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: >- 在此 endpoint 上始终为 `0`，该 endpoint 仅删除 KYC 会话。使用 `DELETE /v3/session/{sessionId}/delete/` 删除企业验证（KYB）会话会报告由其创建并随之一同删除的验证数量。 examples: Mixed outcomes: value: results: - session_id: 4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02 session_number: 1001 face_retention_outcome: deleted biometric_template_uuid: null biometric_template_expires_at: null deleted_child_verifications: 0 - session_id: b8e1d2c3-4f5a-4b6c-8d7e-9f0a1b2c3d4e session_number: 1002 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: 7a1e9c2d-5f4b-4c3a-8e2d-1b0a9f8e7d6c session_number: 1003 face_retention_outcome: ineligible_no_vendor_user biometric_template_uuid: null biometric_template_expires_at: null deleted_child_verifications: 0 - session_id: c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f session_number: 1004 face_retention_outcome: failed_retryable biometric_template_uuid: null biometric_template_expires_at: null deleted_child_verifications: 0 '202': description: >- 匹配到超过 20 个会话。这些会话正在后台删除；请轮询 `GET /v3/sessions/delete/{job_id}/`，直至 `status` 变为 `COMPLETED` 或 `FAILED`。 content: application/json: schema: $ref: '#/components/schemas/SessionDeletionJob' examples: Job accepted: value: job_id: 5b8f2c1e-7d3a-4f6b-9e2c-1a0d8f7e6c5b status: PENDING total: 250 processed: 0 outcomes: deleted: 0 none: 0 retained_with_user: 0 ineligible_no_vendor_user: 0 failed_retryable: 0 already_deleted: 0 deleted_child_verifications: 0 error: null created_at: '2026-10-09T10:15:00Z' completed_at: null '400': description: 验证错误 — 未删除任何内容。错误值为以字段名为键的消息字符串数组。 content: application/json: schema: type: object properties: session_numbers: type: array items: type: string additionalProperties: description: >- 其他键：不属于列出会话（List Sessions）过滤器的 `filter_*` 键（`"Unknown filter."`），或者值无法读取的 `filter_*` 键（以该 `filter_*` 键为键名，值为包含错误消息的数组）。 examples: Missing selector: summary: 既未提供 session_numbers 也未提供 delete_all value: session_numbers: - This field is required unless delete_all is true. Empty list: summary: session_numbers 是一个空数组 value: session_numbers: - This list may not be empty. Non-numeric entry: summary: session_numbers 包含非数字字符串 value: session_numbers: - All session_numbers must be numeric. Privacy erasure cannot retain: summary: >- deletion_instruction 为 privacy_erasure 且 retain_face_embeddings 为 true 的组合 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. Unknown filter: summary: List Sessions 不具备的 filter_* 键 value: filter_reviewer: Unknown filter. Unreadable filter value: summary: 无法读取的过滤器值 value: filter_date_from: - Enter a valid date. '403': description: 缺少 API 密钥。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。 content: application/json: schema: type: object properties: detail: type: string examples: Missing or invalid API key: summary: 缺少 x-api-key 请求头，或该密钥无效 value: detail: You do not have permission to perform this action. '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. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST \ https://verification.didit.me/v3/sessions/delete/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "session_numbers": ["1001", "1002", "1003"] }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.sessions.batch_delete( session_numbers=["1001", "1002", "1003"], ) 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.batchDelete({ session_numbers: ["1001", "1002", "1003"], }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.BatchDelete(ctx, didit.SessionsBatchDeleteParams{\n\tSessionNumbers: didit.Some([]string{\"1001\", \"1002\", \"1003\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.util.List; import me.didit.Didit; import me.didit.types.SessionsBatchDeleteParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.sessions().batchDelete(SessionsBatchDeleteParams.builder() .sessionNumbers(List.of("1001", "1002", "1003")) .build()); System.out.println(result); - lang: php label: PHP source: |- sessions->batchDelete([ 'session_numbers' => ['1001', '1002', '1003'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: >- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.sessions.batch_delete(session_numbers: ["1001", "1002", "1003"]) 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.BatchDeleteAsync(new SessionsBatchDeleteParams { SessionNumbers = new string[] { "1001", "1002", "1003" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: SessionDeletionJob: type: object description: 正在后台运行的批量会话删除：包含进度和按结果统计的数量，绝不包含其删除了哪些会话。 properties: job_id: type: string format: uuid description: 使用此 ID 轮询 `GET /v3/sessions/delete/{job_id}/`。 status: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED description: >- `PENDING`：已接受，尚未开始。`PROCESSING`：正在删除；`processed` 和 `outcomes` 正在更新。`COMPLETED`：所有选定的会话均已处理。`FAILED`：任务提前停止；详见 `error`。 total: type: integer description: 请求删除时选定的会话。 processed: type: integer description: 截至目前作业已处理完成的会话。 outcomes: type: object description: 以各项结果结束的会话数量。每个键始终存在。 properties: deleted: type: integer description: 与人脸特征向量一同删除的会话。 none: type: integer description: 已删除且不包含人脸特征向量的会话。 retained_with_user: type: integer description: 根据请求或应用策略的要求，在为其用户保留了一个不含图像的生物特征模板的同时删除的会话。 ineligible_no_vendor_user: type: integer description: 因请求保留但未关联用户而连同其人脸特征向量一同被删除的会话。 failed_retryable: type: integer description: 报告为未删除的会话。作业会自动重试其自身未能删除的分组，而不会将其计入此处。 already_deleted: type: integer description: 在任务处理到所选会话时，这些会话已被删除（例如被另一个请求删除）。 deleted_child_verifications: type: integer description: >- 已被删除的企业验证所创建的验证数，已随之一并删除。对于由 `POST /v3/sessions/delete/` 启动的任务，此项始终为 `0`，因为该任务仅删除 KYC 会话。 error: type: string nullable: true description: >- 除非 `status` 为 `FAILED`，否则为 `null`；若失败则表示删除停止的原因。该作业尚未处理到的会话仍保留在原处：可重复该请求以继续删除它们。 created_at: type: string format: date-time description: 请求删除的时间。 completed_at: type: string format: date-time nullable: true description: 任务完成时间；运行中时为 `null`。 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.