跳转到主要内容
POST
curl

概述

在运行任何会话之前,显式创建一个用户实体。 除非另行指定,返回的实体状态为 ACTIVE。 您还可以选择在同一次调用中向用户发送验证链接(参见发送验证链接)。

适用场景

  • 预先填充元数据(等级、注册来源、内部标签),在客户开始验证之前完成。
  • 从其他供应商迁移:在 Didit 中重新创建现有用户名单,使历史数据和分析从已知基线开始。
  • 导入可信的用户人脸:先创建用户,然后使用返回的 didit_internal_id 调用上传用户人脸。
  • 仅交易场景:使用 vendor_data 注册用户,无需运行用户验证(KYC)会话即可提交交易。
  • 邀请他人验证:一次调用即可创建用户并通过邮件发送验证链接。

联系方式

您可以在用户资料字段旁一并提供用户的联系方式。 未发送 full_name 时,first_name 和 last_name 之间以空格连接,组成 full_name。 email 和 phone_number 存储在 metadata.contact 中,country 存储在 metadata.address 中。 country 接受 alpha-2 或 alpha-3 格式的 ISO 3166 代码(如 ES 或 ESP),并以大写形式存储。 如果您发送的 metadata 中,contact 或 address 已有非 JSON 对象的值,Didit 不会覆盖该值:调用会针对需要写入的那个字段返回 400。

发送验证链接

将 send_verification_link 设为 true,即可在同一次调用中邀请用户进行验证。 Didit 会基于 workflow_id 中的工作流为该用户创建验证会话,并将链接发送至 email。 使用 language 选择邮件的语言;省略时默认为英语。
  • 使用链接时必须提供 email 和 workflow_id,且该工作流必须用于验证个人:企业验证(KYB)工作流会返回 400。
  • 会话会经过与创建会话相同的检查。 vendor_data 位于黑名单中或额度不足时,都会返回 400。
  • 用户和会话要么同时创建,要么都不创建。 任一检查失败时,不写入任何数据,也不发送邮件。
  • 响应中包含 verification_link,其中有会话的 session_id、session_number、status、url、workflow_id,以及链接发送到的 email。 未发送链接时,verification_link 为 null。

注意事项

  • vendor_data 为必填项,且在每个应用内必须唯一。尝试创建重复项会返回冲突错误。要更新已有用户,请使用 PATCH /v3/users/{vendor_data}/。
  • vendor_data 的硬性上限为 2000 字节(UTF-8 编码)。超过该上限的值会返回 400 验证错误,而不会被接受。
  • 通常由已验证的会话派生的字段(full_name、date_of_birth)可以在此预先填充,但可能会被首个已通过的用户验证(KYC)会话覆盖。
  • 此接口不接受人脸图像。要添加可信的导入人脸,请在此接口返回 didit_internal_id 后,使用 POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/。
  • 创建操作本身不发送 webhook。之后对用户的更改会发送 user.data.updated 或 user.status.updated。
  • 使用 send_verification_link 时,新会话会在同一次调用中更新用户,并发送 user.data.updated。

权限

主密钥和拥有完全访问权限的 API 密钥始终可以调用此接口。 具有自定义访问权限的密钥需要 用户(users)写入权限。 当 send_verification_link: true 时,还需要 会话 写入权限,因为该调用会创建会话并分发其链接。 否则调用会返回 403,错误信息为 This API key has no write access to sessions.,且不写入任何数据。 仅限部分工作流或已通过会话的密钥无法访问此接口。 Console 的角色与权限决定团队成员在 Console 中可以执行的操作。这些角色和权限不会用于评估 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
string
必填

您对此用户的唯一标识符(自由格式字符串,非 UUID)。在该应用的用户之间必须唯一;按发送的内容精确匹配。

full_name
string | null

用户的法定姓名。

Maximum string length: 512
display_name
string | null

控制台中显示的易读显示名称(在界面显示时优先级高于 full_name)。

Maximum string length: 255
date_of_birth
string<date> | null

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

status
enum<string>
默认值:ACTIVE

初始生命周期状态。默认为 ACTIVE。

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

附加到用户的任意 JSON 对象。默认为 {}。

approved_emails
string[]

该用户的预信任邮箱地址,例如 ["john@example.com"]。

approved_phones
string[]

该用户的预信任电话号码,例如 ["+14155551234"]。

issuing_states
string[]

预先记录的签发国家/地区(ISO 3166-1 alpha-3),例如 ["USA"]。

first_name
string

名字。未发送 full_name 时,Didit 会使用空格将 first_name 和 last_name 拼接为 full_name。不作为单独字段返回。

Maximum string length: 255
last_name
string

姓氏。未发送 full_name 时,将与 first_name 拼接为 full_name。不作为单独字段返回。

Maximum string length: 255
email
string<email>

联系邮箱,存储在 metadata.contact.email 中(它会替换您在 metadata.contact 内发送的 email)。当 send_verification_link 为 true 时必填:验证链接将发送至此地址。如果 metadata.contact 不是 JSON 对象,则调用将针对此字段返回 400。

phone_number
string

联系电话号码,存储在 metadata.contact.phone_number 中。如果 metadata.contact 不是 JSON 对象,该调用会因该字段返回 400。

Maximum string length: 32
country
string

ISO 3166 代码格式的国家/地区,alpha-2 或 alpha-3(ES 或 ESP)。以大写形式存储在 metadata.address.country 中。如果 metadata.address 不是 JSON 对象,则该调用针对该字段返回 400。

Maximum string length: 3

为 true 时,Didit 会根据 workflow_id 为该人员创建验证会话,并通过电子邮件将链接发送至 email。需要提供 email 和 workflow_id。限定权限的 API 密钥还需要具备 sessions 写入权限。

workflow_id
string<uuid>

验证会话的工作流。当 send_verification_link 为 true 时必填。该工作流必须验证个人:企业验证(KYB)工作流将被拒绝。其他情况下忽略。

language
string

验证邮件的语言,采用支持的语言代码。省略时为英语。当 send_verification_link 不为 true 时忽略。

Maximum string length: 10

响应

用户已创建。完整的用户记录(格式与获取用户相同),加上 verification_link:当 send_verification_link 为 true 时为 Didit 发送邮件的验证会话,否则为 null。

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

Didit 创建并通过电子邮件发送给该人员的验证会话。始终存在:当 send_verification_link 不为 true 时为 null。

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日