批量删除会话 API：KYC 清理

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

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);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Sessions.BatchDelete(ctx, didit.SessionsBatchDeleteParams{
	SessionNumbers: didit.Some([]string{"1001", "1002", "1003"}),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

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);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->sessions->batchDelete([
    'session_numbers' => ['1001', '1002', '1003'],
]);
print_r($result->toArray());

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));

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

POST

sessions

delete

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

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);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Sessions.BatchDelete(ctx, didit.SessionsBatchDeleteParams{
	SessionNumbers: didit.Some([]string{"1001", "1002", "1003"}),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

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);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->sessions->batchDelete([
    'session_numbers' => ['1001', '1002', '1003'],
]);
print_r($result->toArray());

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));

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

行为

每个匹配的会话都会按照删除会话的方式删除：会话本身、其持有的每次验证尝试、决策和提取的数据、功能记录以及所有已存储的文件都会被删除，会话将从所有读取端点中消失，之前签发的媒体 URL 也将无法再解析。仍在为已删除会话排队的 Webhook 投递及其重试会被丢弃；已经送达的 Webhook 不受影响。删除是永久性的，且不可撤销。如果任一选定的会话属于已定稿的监管报告，则整个请求返回 409，且不会删除任何内容。响应中会使用 code: in_filed_report，并列出每份报告。请使用删除报告逐一删除这些报告，然后重新发送请求。删除报告不会删除会话；在您重新发送此请求之前，会话会一直保留。无论您使用 session_numbers 还是 delete_all 选择会话，匹配的会话数量决定了请求的响应方式：

匹配的会话数	响应
最多 20 个	删除完成后返回 `200 OK`，并在 `results` 中为每个匹配的会话返回一条结果。
超过 20 个	返回 `202 Accepted` 及删除作业。会话将在后台删除；请轮询获取会话删除作业，直到作业完成。

除非 face_retention_outcome 为 failed_retryable，否则结果即表示会话已被删除。在这种情况下，该会话未被删除，仍然保留，因此应将此结果视为需要重试的失败，而不能作为删除确认。与您应用中有效 KYC 会话不匹配的编号会被跳过，且不会出现在 results 中。

使用过滤器缩小 `delete_all` 的范围

设置 delete_all: true 后，您可以使用列出会话的过滤器缩小选择范围，每个过滤器都需加上 filter_ 前缀。它们接受的值与查询参数相同。接受多个值的过滤器（status、workflow_id、country、region、document_type、document_name、session_type、warning、organization_name）可接受以逗号分隔的字符串或数组：

{
  "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 的计算方式，以及隐私擦除指令的作用，请参阅删除会话。

每个会话的结果

对于最多 20 个匹配的会话，200 OK 会为每个会话返回一条结果：

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

每条结果包含的字段与删除会话响应相同。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：

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

每隔几秒轮询一次获取会话删除任务，直到 status 变为 COMPLETED 或 FAILED。

任务只报告每种结果中有多少个会话，从不报告具体删除了哪些会话。
delete_all 任务只删除您发出请求之前创建的会话。任务运行期间新开始的会话不会被删除。
请求中的数据保留和指令字段适用于任务删除的每个会话。
如果某组会话暂时无法删除，任务会自行重试。
状态为 FAILED 的任务会在 error 中说明原因。任务尚未处理的会话仍然保留：重新发出请求即可删除它们。

示例

按数量删除
删除并保留模板
隐私擦除
全部删除并轮询任务

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

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

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

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，直到您明确更改策略。

相关内容

授权

x-api-key

string

header

必填

您的应用 API 密钥，可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于 IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP 列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。

请求体

application/json

session_numbers

string[]

要删除的 KYC 会话的纯数字字符串格式数字 session_number 值（也接受 JSON 数字并会进行强制转换）。除非 delete_all 为 true，否则为必填项；空列表将返回 400。任何非数字条目都会导致整个请求以 400 被拒绝（除非 delete_all 为 true，此时将跳过校验并忽略这些条目）。与您应用中的活动会话不匹配的数字将被直接忽略。

Minimum array length: 1

Pattern: ^[0-9]+$

示例:

["1001", "1002", "1003"]

delete_all

boolean

默认值:false

为 true 时，调用应用中所有剩余的 KYC 会话都将被删除，并且 session_numbers 将被忽略，除非您使用 filter_* 键缩小选择范围。匹配超过 20 个会话时将作为删除任务（202）运行，仅涵盖请求前创建的会话。默认为 false。不可逆；没有确认步骤。

示例:

false

retain_face_embeddings

boolean | null

针对本次删除覆盖应用的 face_retention_policy。为 true 时，在会话删除后保留一个锚定到该会话用户的无图像人脸生物特征模板；为 false 时，随会话一同删除人脸特征向量；省略或设为 null 则遵循应用策略。对于 KYB 会话以及无人脸特征向量的会话，此项将被忽略。

示例:

true

face_retention_days

integer

保留模板的有限保留时长（以天为单位）。除非应用已设置 face_retention_days，否则在保留模板时必填。模板的 expires_at 为此保留时长、应用的通用数据保留期和 face_retention_deadline 中的最早者。

必填范围: 1 <= x <= 3650

示例:

365

face_retention_deadline

string<date-time>

保留模板的可选硬性到期时间。必须是将来的时间。

示例:

"2027-08-28T00:00:00Z"

deletion_instruction

enum<string>

默认值:operational_session_delete

您发出的指令类别。operational_session_delete 会删除会话，并且仅在策略或 retain_face_embeddings 要求时才保留模板。privacy_erasure 会在删除会话之前清除锚定到该会话用户的每个已保留生物特征模板，此操作不能被应用策略覆盖，也不能与 retain_face_embeddings: true 组合使用（400）。

可用选项:

operational_session_delete,

privacy_erasure

示例:

"operational_session_delete"

instruction_id

string

您对该删除指令的持久化参考标识（例如删除工单 ID）。记录在审计追踪记录和任何保留的模板上。省略时由 Didit 自动生成。

Maximum string length: 255

示例:

"dsar-2026-0142"

filter_status

将 delete_all 的范围缩小为与 List Sessions 的 status 过滤器匹配的会话，取值相同。逗号分隔的字符串或数组。在没有 delete_all 时被忽略。空值会被忽略，不会缩小选择范围。

filter_vendor_data

string

将 delete_all 的范围缩小为与 List Sessions 的 vendor_data 过滤器匹配的会话，取值相同。单个值，而不是列表：数组会被拼接成一个逗号分隔的文本，因此多个值不会作为备选项进行匹配。在没有 delete_all 时被忽略。空值会被忽略，不会缩小选择范围。

filter_search

string

将 delete_all 的范围缩小为与 List Sessions 的 search 过滤器匹配的会话，取值相同。单个值，而不是列表：数组会被拼接成一个逗号分隔的文本，因此多个值不会作为备选项进行匹配。在没有 delete_all 时被忽略。空值会被忽略，不会缩小选择范围。

filter_workflow_id

将 delete_all 的范围缩小为与 List Sessions 的 workflow_id 过滤器匹配的会话，取值相同。逗号分隔的字符串或数组。在没有 delete_all 时被忽略。空值会被忽略，不会缩小选择范围。

filter_date_from

string<date>

将 delete_all 缩小至与列出会话的 date_from 过滤器匹配且值相同的会话。单个值，非列表：数组会被连接为一个逗号分隔的值，因此多个值会被拒绝并返回 400。若无 delete_all 则忽略。空值会被忽略，且不会缩小选择范围。

filter_date_to

string<date>

将 delete_all 缩小至与列出会话的 date_to 过滤器匹配且值相同的会话。单个值，非列表：数组会被连接为一个逗号分隔的值，因此多个值会被拒绝并返回 400。若无 delete_all 则忽略。空值会被忽略，且不会缩小选择范围。

filter_country

将 delete_all 缩小至与列出会话的 country 过滤器匹配且值相同的会话。逗号分隔的字符串或数组。若无 delete_all 则忽略。空值会被忽略，且不会缩小选择范围。

filter_document_type

将 delete_all 缩小至与列出会话的 document_type 过滤器匹配且值相同的会话。逗号分隔的字符串或数组。若无 delete_all 则忽略。空值会被忽略，且不会缩小选择范围。

filter_document_name

将 delete_all 缩小至与列出会话的 document_name 过滤器匹配且值相同的会话。逗号分隔的字符串或数组。若无 delete_all 则忽略。空值会被忽略，且不会缩小选择范围。

filter_region

将 delete_all 的范围缩小为与 List Sessions 的 region 过滤器匹配的会话，取值相同。逗号分隔的字符串或数组。在没有 delete_all 时被忽略。空值会被忽略，不会缩小选择范围。

filter_didit_internal_id

string<uuid>

将 delete_all 缩小至与列出会话的 didit_internal_id 过滤器匹配且值相同的会话。单个值，非列表：数组会被连接为一个逗号分隔的值，因此多个值会被拒绝并返回 400。若无 delete_all 则忽略。空值会被忽略，且不会缩小选择范围。

filter_session_type

将 delete_all 的范围缩小为与 List Sessions 的 session_type 过滤器匹配的会话，取值相同。逗号分隔的字符串或数组。在没有 delete_all 时被忽略。空值会被忽略，不会缩小选择范围。

filter_api_service

string

将 delete_all 缩小至与列出会话的 api_service 过滤器匹配且值相同的会话。单个值，非列表：数组会被连接为一个逗号分隔的值，因此多个值会被拒绝并返回 400。若无 delete_all 则忽略。空值会被忽略，且不会缩小选择范围。

filter_screened_full_name

string

将 delete_all 的范围缩小为与 List Sessions 的 screened_full_name 过滤器匹配的会话，取值相同。单个值，而不是列表：数组会被拼接成一个逗号分隔的文本，因此多个值不会作为备选项进行匹配。在没有 delete_all 时被忽略。空值会被忽略，不会缩小选择范围。

filter_warning

将 delete_all 的范围缩小为与 List Sessions 的 warning 过滤器匹配的会话，取值相同。逗号分隔的字符串或数组。在没有 delete_all 时被忽略。空值会被忽略，不会缩小选择范围。

filter_status_initialized_as_in_review

boolean

将 delete_all 的范围缩小为与 List Sessions 的 status_initialized_as_in_review 过滤器匹配的会话，取值相同。在没有 delete_all 时被忽略。空值会被忽略，不会缩小选择范围。

filter_is_kyc_to_be_reviewed

boolean

将 delete_all 缩小至与列出会话的 is_kyc_to_be_reviewed 过滤器匹配且值相同的会话。若无 delete_all 则忽略。空值会被忽略，且不会缩小选择范围。

filter_euuid

string<uuid>

将 delete_all 缩小至与列出会话的 euuid 过滤器匹配且值相同的会话。单个值，非列表：数组会被连接为一个逗号分隔的值，因此多个值会被拒绝并返回 400。若无 delete_all 则忽略。空值会被忽略，且不会缩小选择范围。

filter_organization_name

将 delete_all 的范围缩小为与 List Sessions 的 organization_name 过滤器匹配的会话，取值相同。逗号分隔的字符串或数组。使用 API 密钥时只能匹配您自己组织的名称，因此它会选择您的所有会话或不选择任何会话。在没有 delete_all 时被忽略。空值会被忽略，不会缩小选择范围。

响应

请求中最多匹配并处理了 20 个会话。每个匹配的会话对应一条结果；未匹配任何内容的编号（未知或已删除）会被跳过且不显示。结果将确认删除，除非 face_retention_outcome 为 failed_retryable：该会话未被删除，应进行重试。

results

object[]

Show child attributes

最后修改于 2026年11月7日

​行为

​使用过滤器缩小 delete_all 的范围

​保留与指令字段

​每个会话的结果

​大量选择将作为任务运行

​示例

​从 204 响应迁移

​相关内容

授权

请求体

响应

行为

使用过滤器缩小 `delete_all` 的范围

保留与指令字段

每个会话的结果

大量选择将作为任务运行

示例

从 204 响应迁移

相关内容