跳转到主要内容
POST
curl

概览

删除一个或多个用户实体。用户记录会被永久删除。其验证会话不在本端点的覆盖范围内,会保留下来,但与用户的关联会被清除。请使用删除会话或批量删除会话删除这些会话。交易同样不在覆盖范围内,请使用批量删除交易删除。

适用场景

  • 被遗忘权请求(GDPR / CCPA)。
  • 在 QA 期间清理测试用户。
  • 从您自己的平台移除用户时的取消配置。

注意事项

  • 接受 vendor_data 值列表、didit_internal_id 值列表,或 delete_all: true。两个列表可以组合使用,二者按逻辑或(OR)合并。
  • 本端点永远不会用过滤条件收窄 delete_all。控制台的 filter_* 批量参数会被拒绝并返回 400,因此您想收窄的范围不会导致应用中的所有用户被删除。 例外情况是 filter_has_approved_sessions 和 filter_has_declined_sessions:它们既不会被拒绝,也不会被应用,因此请勿与 delete_all 一同发送。
  • 全有或全无:如果无法为您所选的用户完成删除,则其中任何一位都不会被删除,您可以放心地重复发送同一请求。
  • 幂等:重复发送同一列表,首次执行后将返回 deleted: 0。
  • 只返回已删除数量的统计,不返回逐项报告。未匹配到的值会被静默跳过。如果您希望将 deleted 与所发送标识符的数量进行比较,请发送去重后的列表,因为重复的标识符只会计算一次。
  • 删除操作不会发出任何 Webhook。Webhook 在用户状态和数据变更时触发,而不是在删除时触发,因此需要删除信号的集成必须在自身一侧记录该信号。
  • 与用户关联的验证会话不会被本端点删除。它们会保留下来,与用户的关联被清除,因此其证件、人脸和媒体文件只有在您自行删除这些会话后才会被移除。
  • retain_face_embeddings(布尔值,默认 false)和 face_retention_days(1 到 3650)是您的明确选择:为每位被删除的人保留一个不含图像的生物特征模板,用于重复检测,保留天数为该值。除此之外,不保留该人的任何其他信息。若两者都不设置,则模板会随用户一并删除。仅设置 face_retention_days 而未设置 retain_face_embeddings: true,或仅设置 retain_face_embeddings: true 而未设置 face_retention_days,都会因 face_retention_days 返回 400。
  • 除非您将 retain_face_embeddings 设为 true,否则与用户关联的已保留生物特征模板会在删除用户之前被清除。如果某个模板因生物特征存储不可用而无法清除,则调用返回 503,请求中的任何用户都不会被删除。重复请求即可完成剩余操作。

已定稿监管报告中的数据

如果任一所选人员属于某个已定稿监管报告所在的案件,整个请求将返回 409,且不会删除任何内容。响应使用 code: in_filed_report,并列出每份报告,以便您在控制台中打开查看:
使用删除报告删除每份报告,然后重复同一请求。如果另一位所选人员仍在某份报告中,仅将该人从列表中移除是不够的。

正在进行的删除

同一时间,一位人员只能由一个请求删除。如果另一个请求仍在删除所选人员中的某一位,本请求最多等待数秒,然后返回 409,code: subject_deletion_in_progress,且不删除任何内容:
待另一项删除完成后,重复同一请求即可。它已删除的人员将不再匹配,因此重复请求只会删除剩余的人员。

权限

应用的任何处于活动状态的 API 密钥都可以调用本端点。Didit 的 API 密钥是应用级别的,而非角色级别的。控制台中的角色和权限(delete:users 等)决定的是某人在控制台中能做什么,对管理 API 的请求则不会对其进行评估。因此,请通过控制谁可以读取应用的 API 密钥,来控制谁可以调用本端点。

相关内容

授权

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

提供 vendor_data_list、didit_internal_id_list 或 delete_all: true。两个列表可以组合使用,相互之间为“或”(OR)逻辑。当 delete_all 为 true 时,其优先级最高,两个列表都会被忽略。

vendor_data_list
string[]

您要删除的自身标识符,完全按照发送的内容进行匹配。

didit_internal_id_list
string<uuid>[]

要删除的 Didit 内部用户 ID,即创建和获取 endpoint 返回的 didit_internal_id。

delete_all
boolean
默认值:false

若为 true,则删除该应用中的所有用户。

retain_face_embeddings
boolean
默认值:false

您的明确选择,用于为每个被删除的人员保留一份无图像的生物特征模板以用于重复检测,保留 face_retention_days 天。该人员的所有其他信息都将被删除。省略此参数或发送 false,将连同用户一起删除模板。当为 true 时,face_retention_days 为必填项。

face_retention_days
integer

当 retain_face_embeddings 为 true 时保留无图像生物特征模板的天数。与该参数配合使用时为必填项;未配置该参数时将被拒绝并在 face_retention_days 上返回 400。

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

365

响应

用户已删除。返回实际删除的用户数量。

deleted
integer

已删除的用户数量(不包括未匹配到任何内容的 vendor_data 值)。

最后修改于 2026年11月7日