用户管理 API：供应商用户增删改查

核心用户实体管理通过 /v3/users/ 下的公开 endpoint 完成。个人资料附件（例如导入的人脸上传）使用组织/应用路径并传入 didit_internal_id。本页提供概念性讲解，完整的请求与响应结构请参见 API 参考。

列出用户

GET /v3/users/ 以分页形式返回应用中的用户列表。支持按状态、搜索关键词、日期范围等条件筛选。

curl -G https://verification.didit.me/v3/users/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "search=jane" \
  --data-urlencode "page_size=50"

使用场景：

每天将部分用户同步到你的数据仓库。
查找已标记的用户，并将其加入分析师队列。
按显示名称搜索用户。

获取用户

GET /v3/users/{vendor_data}/ 通过 vendor_data 获取单个用户。返回完整的数据模型，包括汇总计数器。

curl https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY"

URL 中的 vendor_data 区分大小写。请务必传入创建会话时使用的完全相同的值。

创建用户

POST /v3/users/create/ 在任何会话运行之前创建用户实体。适用于以下场景：

在客户完成验证之前预先写入元数据或自定义字段。
设置初始状态（例如 FLAGGED，用于在你的入驻团队人工审核证件期间）。
从现有数据库预加载用户，从第一天起就拥有完整的用户名单。

curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "tier": "premium", "signup_source": "web" }
  }'

如果已存在具有相同 vendor_data 的用户，该调用将返回冲突错误，请改用 PATCH 进行更新。你还可以提交联系方式：first_name 和 last_name（未提供时，两者会合并为 full_name）、email、phone_number 和 country。 Didit 会将 email 和 phone_number 存储在 metadata.contact 中，将 country 存储在 metadata.address 中。要在同一次调用中邀请对方进行验证，请添加 send_verification_link: true，并提供 email 和 workflow_id。 Didit 会为该用户在此工作流上创建验证会话，并通过邮件发送链接。响应中的 verification_link 包含会话的 session_id、session_number、status、url、workflow_id 和 email；未请求链接时为 null。检查项与错误说明请参见创建用户。

上传导入的人脸

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/ 将可信的人脸图像附加到现有用户资料。如果你从其他服务商导入用户，并希望在用户首次 Didit 会话之前由 Didit 保存其人脸证据，这是正确的后续步骤。

# First create or retrieve the User and read didit_internal_id from the response.
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'

请求字段、限制、列表与删除 endpoint，以及黑名单的区别，请参见上传用户人脸。

更新用户

PATCH /v3/users/{vendor_data}/ 更新可变的资料字段。由已验证会话得出的大多数字段为只读：通过 PATCH 修改它们，要么会被忽略，要么会在审计日志中被标记。 可变字段： display_name、metadata、tags。 验证后只读： full_name、date_of_birth、portrait_image、所有汇总计数器、features 映射。

curl -X PATCH https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "tier": "enterprise" } }'

会发出包含 changed_fields 数组的 user.data.updated Webhook 事件。

变更状态

PATCH /v3/users/{vendor_data}/update-status/ 在 ACTIVE、FLAGGED 和 BLOCKED 之间切换用户状态。状态变更会影响之后的会话和交易。

curl -X PATCH https://verification.didit.me/v3/users/user-42/update-status/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "BLOCKED",
    "reason": "Chargeback fraud pattern detected"
  }'

从 → 到	常见触发条件
`ACTIVE` → `FLAGGED`	交易规则、分析师审核、持续 AML 命中
`ACTIVE` → `BLOCKED`	确认欺诈、手动加入黑名单、命中黑名单
`FLAGGED` → `ACTIVE`	分析师审核通过
`BLOCKED` → `ACTIVE`	分析师手动解除封禁

会发出 user.status.updated Webhook 事件。

批量删除用户

POST /v3/users/delete/ 删除一个或多个用户。用户记录将被永久删除，同时删除其会话后为其保留的所有生物特征模板也会被永久删除。此 endpoint 不涵盖其验证会话：这些会话会保留，但与用户的关联将被清除；请使用删除会话或批量删除会话删除它们。交易同样不在此 endpoint 的范围内，请在控制台中删除。

curl -X POST https://verification.didit.me/v3/users/delete/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data_list": ["user-42", "user-43", "user-44"]
  }'

可以通过 vendor_data_list、didit_internal_id_list 选择用户，也可以同时使用两者；或者传入 delete_all: true 以删除应用中的所有用户。控制台的 filter_* 批量参数在此处会返回 400 错误而被拒绝，而不是被忽略，从而确保缩小范围的意图不会变成全部清空。返回的是计数 {"deleted": <int>}，而不是逐项结果。未匹配到任何记录的标识符会被静默跳过，因此如果要将 deleted 与你发送的标识符数量进行比较，请先发送去重后的列表。

权限模型

API 密钥属于一个应用。主密钥和全访问权限密钥可以调用该应用的每个 /v3/users/* endpoint，包括 delete。范围受限的 API 密钥需要 People（users）访问权限：GET endpoint 需要读取权限，创建、更新、变更状态和删除需要写入权限。使用 send_verification_link: true 创建用户还需要会话写入权限，因为它会创建会话并发送其链接。缺少所需访问权限的密钥会返回 403。仅限部分工作流或已批准会话的密钥完全无法访问 /v3/users/* endpoint。角色是控制台的概念：users 权限资源及其声明决定团队成员在控制台中能做什么，对 API 密钥请求则不作评估。角色矩阵请参见角色与权限。要防止某个服务删除用户，请为其分配仅具有 People 读取权限的密钥，或完全不具有 People 访问权限的密钥。

速率限制与幂等性

所有 /v3/users/* endpoint 均受标准速率限制约束。
create 不是幂等的：使用相同 vendor_data 重试会返回冲突。请在你的系统中去重，或始终先执行 GET。
delete 是幂等的：删除已删除的用户不会产生任何效果。

这些操作触发的 Webhook

操作	Webhook
`create`	create 调用本身不触发 Webhook；首次 `user.data.updated` 会在会话或更新首次填充资料时到达
`update`	`user.data.updated`（包含 `changed_fields`）
`update-status`	`user.status.updated`
`delete`	无。如需对删除作出响应，请在您自己的系统中记录该删除操作

后续步骤

数据模型

完整的字段参考。

列表 API

GET /v3/users/ 的架构。

创建 API

POST /v3/users/create/ 的架构。

上传人脸

为用户资料附加导入的人脸图像。

概览

定价

工作流与验证

审核与运营

实体（用户与企业）

设置与自定义

安全与合规

Didit 学院

资源

用户管理 API：供应商用户增删改查

列出用户

获取用户

创建用户

上传导入的人脸

更新用户

变更状态

批量删除用户

权限模型

速率限制与幂等性

这些操作触发的 Webhook

后续步骤

数据模型

列表 API

创建 API

上传人脸

​列出用户

​获取用户

​创建用户

​上传导入的人脸

​更新用户

​变更状态

​批量删除用户

​权限模型

​速率限制与幂等性

​这些操作触发的 Webhook

​后续步骤

数据模型

列表 API

创建 API

上传人脸

列出用户

获取用户

创建用户

上传导入的人脸

更新用户

变更状态

批量删除用户

权限模型

速率限制与幂等性

这些操作触发的 Webhook

后续步骤