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-abc-123", "full_name": "John Doe"}'from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.users.create(
vendor_data="user-abc-123",
full_name="John Doe",
)
print(result)import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.users.create({
vendor_data: "user-abc-123",
full_name: "John Doe",
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.Users.Create(ctx, didit.UsersCreateParams{
VendorData: "user-abc-123",
FullName: didit.String("John Doe"),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import me.didit.Didit;
import me.didit.types.UsersCreateParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.users().create(UsersCreateParams.builder()
.vendorData("user-abc-123")
.fullName("John Doe")
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->users->create([
'vendor_data' => 'user-abc-123',
'full_name' => 'John Doe',
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.users.create(
vendor_data: "user-abc-123",
full_name: "John Doe"
)
puts result.to_husing System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Users.CreateAsync(new UsersCreateParams
{
VendorData = "user-abc-123",
FullName = "John Doe",
});
Console.WriteLine(JsonSerializer.Serialize(result));{
"didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418",
"vendor_data": "user-abc-123",
"display_name": null,
"full_name": "John Doe",
"date_of_birth": null,
"effective_name": "John Doe",
"status": "ACTIVE",
"metadata": {},
"portrait_image_url": null,
"session_count": 0,
"approved_count": 0,
"declined_count": 0,
"in_review_count": 0,
"issuing_states": [],
"approved_emails": [],
"approved_phones": [],
"features": {},
"features_list": [],
"last_session_at": null,
"last_activity_at": "2025-06-15T10:30:00Z",
"first_session_at": null,
"tags": [],
"comments": [],
"created_at": "2025-06-15T10:30:00Z",
"updated_at": "2025-06-15T10:30:00Z",
"verification_link": null
}创建用户 API:供应商用户实体
在 KYC 会话运行前,预先创建 Didit 供应商用户实体。可从外部数据库批量导入用户,或为交易监控注册用户。
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-abc-123", "full_name": "John Doe"}'from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.users.create(
vendor_data="user-abc-123",
full_name="John Doe",
)
print(result)import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.users.create({
vendor_data: "user-abc-123",
full_name: "John Doe",
});
console.log(result);ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()
result, err := client.Users.Create(ctx, didit.UsersCreateParams{
VendorData: "user-abc-123",
FullName: didit.String("John Doe"),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", result)import me.didit.Didit;
import me.didit.types.UsersCreateParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.users().create(UsersCreateParams.builder()
.vendorData("user-abc-123")
.fullName("John Doe")
.build());
System.out.println(result);<?php
require 'vendor/autoload.php';
use Didit\DiditClient;
// Reads DIDIT_API_KEY.
$didit = new DiditClient();
$result = $didit->users->create([
'vendor_data' => 'user-abc-123',
'full_name' => 'John Doe',
]);
print_r($result->toArray());require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.users.create(
vendor_data: "user-abc-123",
full_name: "John Doe"
)
puts result.to_husing System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Users.CreateAsync(new UsersCreateParams
{
VendorData = "user-abc-123",
FullName = "John Doe",
});
Console.WriteLine(JsonSerializer.Serialize(result));{
"didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418",
"vendor_data": "user-abc-123",
"display_name": null,
"full_name": "John Doe",
"date_of_birth": null,
"effective_name": "John Doe",
"status": "ACTIVE",
"metadata": {},
"portrait_image_url": null,
"session_count": 0,
"approved_count": 0,
"declined_count": 0,
"in_review_count": 0,
"issuing_states": [],
"approved_emails": [],
"approved_phones": [],
"features": {},
"features_list": [],
"last_session_at": null,
"last_activity_at": "2025-06-15T10:30:00Z",
"first_session_at": null,
"tags": [],
"comments": [],
"created_at": "2025-06-15T10:30:00Z",
"updated_at": "2025-06-15T10:30:00Z",
"verification_link": null
}概述
在运行任何会话之前,显式创建一个用户实体。 除非另行指定,返回的实体状态为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 选择邮件的语言;省略时默认为英语。
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-abc-789",
"first_name": "Julia",
"last_name": "Martin",
"email": "julia.martin@example.com",
"send_verification_link": true,
"workflow_id": "YOUR_WORKFLOW_ID",
"language": "es"
}'
- 使用链接时必须提供
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 密钥请求。
相关内容
授权
您的应用 API 密钥,可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域:针对每个资源设为无权限、只读或读写,限定于特定工作流或已通过的会话、限定于 IP 地址列表,以及设置到期日期。401 表示密钥错误、已撤销或已过期;403 表示未发送密钥、密钥无权访问该资源或操作,或请求来自其 IP 列表之外的地址;在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null;没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。
请求体
您对此用户的唯一标识符(自由格式字符串,非 UUID)。在该应用的用户之间必须唯一;按发送的内容精确匹配。
用户的法定姓名。
512控制台中显示的易读显示名称(在界面显示时优先级高于 full_name)。
255YYYY-MM-DD 格式的出生日期。
初始生命周期状态。默认为 ACTIVE。
ACTIVE, FLAGGED, BLOCKED 附加到用户的任意 JSON 对象。默认为 {}。
该用户的预信任邮箱地址,例如 ["john@example.com"]。
该用户的预信任电话号码,例如 ["+14155551234"]。
预先记录的签发国家/地区(ISO 3166-1 alpha-3),例如 ["USA"]。
名字。未发送 full_name 时,Didit 会使用空格将 first_name 和 last_name 拼接为 full_name。不作为单独字段返回。
255姓氏。未发送 full_name 时,将与 first_name 拼接为 full_name。不作为单独字段返回。
255联系邮箱,存储在 metadata.contact.email 中(它会替换您在 metadata.contact 内发送的 email)。当 send_verification_link 为 true 时必填:验证链接将发送至此地址。如果 metadata.contact 不是 JSON 对象,则调用将针对此字段返回 400。
联系电话号码,存储在 metadata.contact.phone_number 中。如果 metadata.contact 不是 JSON 对象,该调用会因该字段返回 400。
32ISO 3166 代码格式的国家/地区,alpha-2 或 alpha-3(ES 或 ESP)。以大写形式存储在 metadata.address.country 中。如果 metadata.address 不是 JSON 对象,则该调用针对该字段返回 400。
3为 true 时,Didit 会根据 workflow_id 为该人员创建验证会话,并通过电子邮件将链接发送至 email。需要提供 email 和 workflow_id。限定权限的 API 密钥还需要具备 sessions 写入权限。
验证会话的工作流。当 send_verification_link 为 true 时必填。该工作流必须验证个人:企业验证(KYB)工作流将被拒绝。其他情况下忽略。
响应
用户已创建。完整的用户记录(格式与获取用户相同),加上 verification_link:当 send_verification_link 为 true 时为 Didit 发送邮件的验证会话,否则为 null。
完整的用户详情。在 UserListItem 基础上扩展了元数据、备注和 updated_at。
Didit 创建并通过电子邮件发送给该人员的验证会话。始终存在:当 send_verification_link 不为 true 时为 null。
Show child attributes
Show child attributes
Didit 为此用户分配的稳定内部 UUID。
您对此用户的唯一标识符(创建会话时传入)。未提供供应商标识符时可为 null。
您设置的自定义显示名称
从已验证证件中提取的姓名
最佳可用名称:如果已设置则为 display_name,否则为 full_name
用户记录的生命周期状态(并非会话状态)。ACTIVE 为默认值,FLAGGED 标记该用户需要人工关注,BLOCKED 会阻止该 vendor_data 创建新会话。
ACTIVE, FLAGGED, BLOCKED 用户肖像照片的预签名 URL(数小时后过期)
该用户的验证会话总数
已通过的会话数量
已拒绝的会话数量
审核中的会话数量
此用户已通过的身份证件上显示的签发国家/地区的 ISO 3166-1 alpha-3 代码,例如 ["USA", "ESP"]。无时为空数组。
从该用户已通过的会话中收集的已验证邮箱地址,例如 ["john@example.com"]。
从该用户已通过的会话中收集的已验证电话号码,例如 ["+14155551234"]。
该用户所有会话的每项功能汇总状态。可选键: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 相同的数据,为 {feature, status} 对象的有序数组。
Show child attributes
Show child attributes
最近一次会话的时间戳
首次会话的时间戳
该用户最近一次活动的时间戳(会话、交易、状态变更、数据编辑等)。
标签分配情况。注意:与列表响应中使用的扁平 {uuid, name, color} 结构不同,详情响应中的每个条目均为标签链接对象({uuid, tag: {...}, added_by_email, added_by_name, created_at})。
Show child attributes
Show child attributes
您附加到此用户的自定义元数据 JSON。默认为 {}。
该用户的活动日志和评论(状态变更、资料修改、手动备注)。
Show child attributes
Show child attributes