跳转到主要内容
PATCH
curl

概览

更新 用户实体 中的可变字段。由已验证的用户验证(KYC)会话同步而来的字段(full_name、date_of_birth、portrait_image、汇总计数器和 features)为只读。

适用场景

  • 更新您自己的元数据:将用户调整到其他等级、修改标签或记录内部备注。
  • 重命名:为内部控制台视图设置更合适的 display_name。
  • 覆盖已验证数据(请谨慎操作):允许手动覆盖,但会记录到审计日志中。

注意事项

  • 此接口无法修改 URL 中的 vendor_data。如需更换标识,请创建新用户并删除旧用户。
  • 会发出包含 changed_fields 数组的 user.data.updated Webhook 事件,便于使用方高效同步。
  • 在此修改 status 的效果与更新用户状态相同。该变更会记录在用户的活动记录中,可选的 reason(最多 1000 个字符)将作为其备注。将状态设为 BLOCKED 时,还会把 vendor_data 添加到系统黑名单中。user.status.updated Webhook 事件不包含 reason。
  • 若您通过 PATCH 修改当前由已验证会话管理的字段,该覆盖会被接受,但会在审计日志中标记。

权限

主密钥和全权限 API 密钥始终可以调用此接口。具有自定义访问权限的密钥需要 用户(users)的写入权限。仅限于部分工作流或已通过会话的密钥,无法调用此接口。 控制台中的角色与权限决定团队成员可在控制台中执行的操作。对于 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。

路径参数

vendor_data
string
必填

您对该用户的唯一标识符(自由格式字符串,非 UUID)。

请求体

application/json
full_name
string | null

用户的姓名

Maximum string length: 512
display_name
string | null

该用户的自定义显示名称

date_of_birth
string<date> | null

YYYY-MM-DD 格式的出生日期

status
enum<string>

用户生命周期状态。状态变更会记录为 STATUS_CHANGED 活动,且 BLOCKED 会将 vendor_data 添加到系统黑名单中(移出 BLOCKED 会移除该条目)。

可用选项:
ACTIVE,
FLAGGED,
BLOCKED
metadata
object | null

附加到用户的任意 JSON 对象。更新时将完全替换现有元数据;如果仅想添加键,请在客户端进行合并。

approved_emails
string[]

该用户的已验证邮箱地址,例如 ["john@example.com"]。完全替换已存储的列表。

approved_phones
string[]

该用户的已验证电话号码。完全替换已存储的列表。

issuing_states
string[]

签发国家/地区(ISO 3166-1 alpha-3),例如 ["USA"]。完全替换已存储的列表。

reason
string | null

状态变更的原因。仅在状态实际变更时,记录在用户活动的状态变更条目(comments[].comment,以及 Business Console 中的 Activity)上。Webhook 不包含此项。

Maximum string length: 1000

响应

用户已更新。返回完整的已更新用户记录(格式与获取用户相同)。

完整的用户详情。在 UserListItem 基础上扩展了元数据、备注和 updated_at。

didit_internal_id
string<uuid>

Didit 为此用户分配的稳定内部 UUID。

vendor_data
string | null

您对此用户的唯一标识符(创建会话时传入)。未提供供应商标识符时可为 null。

display_name
string | null

您设置的自定义显示名称

full_name
string | null

从已验证证件中提取的姓名

date_of_birth
string<date> | null
effective_name
string | null

最佳可用名称:如果已设置则为 display_name,否则为 full_name

status
enum<string>

用户记录的生命周期状态(并非会话状态)。ACTIVE 为默认值,FLAGGED 标记该用户需要人工关注,BLOCKED 会阻止该 vendor_data 创建新会话。

可用选项:
ACTIVE,
FLAGGED,
BLOCKED
portrait_image_url
string | null

用户肖像照片的预签名 URL(数小时后过期)

session_count
integer

该用户的验证会话总数

approved_count
integer

已通过的会话数量

declined_count
integer

已拒绝的会话数量

in_review_count
integer

审核中的会话数量

issuing_states
string[]

此用户已通过的身份证件上显示的签发国家/地区的 ISO 3166-1 alpha-3 代码,例如 ["USA", "ESP"]。无时为空数组。

approved_emails
string[]

从该用户已通过的会话中收集的已验证邮箱地址,例如 ["john@example.com"]。

approved_phones
string[]

从该用户已通过的会话中收集的已验证电话号码,例如 ["+14155551234"]。

features
object

该用户所有会话的每项功能汇总状态。可选键:ID_VERIFICATION、NFC、LIVENESS、FACE_MATCH、POA、QUESTIONNAIRE、EMAIL_VERIFICATION、PHONE、AML、IP_ANALYSIS、AGE_ESTIMATION、DATABASE_VALIDATION。可选值:Approved、Declined、In Review、Not Finished、Resub Requested。

features_list
object[]

与 features 相同的数据,为 {feature, status} 对象的有序数组。

last_session_at
string<date-time> | null

最近一次会话的时间戳

first_session_at
string<date-time> | null

首次会话的时间戳

last_activity_at
string<date-time> | null

该用户最近一次活动的时间戳(会话、交易、状态变更、数据编辑等)。

tags
object[]

标签分配情况。注意:与列表响应中使用的扁平 {uuid, name, color} 结构不同,详情响应中的每个条目均为标签链接对象({uuid, tag: {...}, added_by_email, added_by_name, created_at})。

created_at
string<date-time>
metadata
object

您附加到此用户的自定义元数据 JSON。默认为 {}。

comments
object[]

该用户的活动日志和评论(状态变更、资料修改、手动备注)。

updated_at
string<date-time>
最后修改于 2026年11月7日