跳转到主要内容
POST
cURL

KYC 与 KYB 支持

同一个 endpoint 既可以创建用户验证会话,也可以创建企业验证会话。工作流的类型决定会话种类:
  • 传入 KYC 工作流的 workflow_id,将创建用户验证(KYC)会话。响应中的 session_kind: "user"。
  • 传入 KYB 工作流的 workflow_id,将创建企业验证(KYB)会话。响应中的 session_kind: "business"。
请在控制台的 工作流 → 创建工作流 中配置工作流。工作流在创建时即为 KYC 或 KYB 之一,创建后无法更改类型。

示例

响应(201 Created):

电子签名文档

当工作流包含从会话获取文档的电子签名步骤(即 signature_documents_source 设为 session 或 both)时,请在 sign.documents 中发送这些文档。每个文档均为 base64 编码的文件,因此 Didit 无需再从 URL 获取文件。
如果不提供 fields,签署人只需阅读文档并表示同意。

按锚点文本放置字段

字段可以不使用位置,而是带有 anchor:即文档中标记字段放置位置的一段文本。锚点适用于为每个会话生成的文档,例如基于 Word 模板生成的文档。对于工作流文档,请在控制台中放置字段。 如果文档中找不到该文本,调用将返回 400 以及 field_anchor_not_found 和该字段的 key。Didit 不会从 PDF 中删除锚点文本,因此请将其设置为与页面背景相同的颜色。

字段值

sign.field_values 用于设置所有 prefill 为 api.<key> 的字段的值,适用于工作流文档和会话文档。它是一个以这些 <key> 名称为键的对象。text 和 data 字段的值为 1 至 500 个字符的字符串,checkbox 字段的值为布尔值。

错误与重复调用

一个会话最多包含 20 个文档,总大小不超过 50 MB。在以下情况下,调用将返回 400 以及 sign 错误:
  • 工作流不包含电子签名步骤。
  • 您发送了 sign.documents,但该步骤只接受工作流文档。
  • 该步骤只接受会话文档,而您未发送任何文档;或该步骤没有工作流文档,且您也未发送任何文档。
  • 某个文档过大、不是有效的 base64,或不是受支持的文件类型。
  • Word 文件被 signature_document_not_supported 拒绝,或无法转换并返回 signature_document_conversion_failed,两者均附带支持的文件中列出的 reason。
  • 某个字段无效,其锚点未找到(field_anchor_not_found),或字段值被拒绝。
使用相同的 workflow_id 和 vendor_data 再次调用创建接口,将返回待处理的会话。如果该调用包含 sign,其文档、字段和字段值必须与第一次完全一致(顺序、标题、文件名、内容、字段和值均相同)。任何不同之处都会返回 400 以及 {"sign": "signature_document_changed"}:请使用其他 vendor_data,或等待待处理的会话完成。

沙盒场景测试

在沙盒模式的应用中,传入 sandbox_scenario 可以预设确定的结果(通过、特定的拒绝结果,或审核中场景),且不会调用真实服务商,也不会消耗您的余额:
在正式环境的应用中,sandbox_scenario 会被拒绝,返回 400。如果创建时尚不确定结果,可以在会话仍处于 Not Started 状态时,稍后通过 POST /v3/session/{session_id}/sandbox/arm/ 设置(或重新设置)场景。托管流程中的预流程场景选择器也使用同一个端点。完整的场景目录、魔法值注册表以及 arm endpoint 的请求和响应结构,请参阅沙盒与测试数据。

vendor_data 将会话绑定到实体

  • 对于 KYC 工作流:绑定到用户实体。如果用户不存在,将自动创建。
  • 对于 KYB 工作流:绑定到企业实体。如果是新实体,将自动创建。
更多信息请参阅供应商数据关联。

伊利诺伊州、得克萨斯州和科罗拉多州的生物识别同意

托管流程以及 4.10.0 或更高版本的原生 SDK 可以在首次人脸采集之前显示明确的生物识别同意步骤,具体取决于应用的同意模式以及用户所在位置。以下两个可选字段会影响该判断:
  • user_state:用户居住的地区(如果您知道)。可填写 US-IL、IL 或 Illinois。在自动模式下,如果用户位于涵盖的州,流程会请求同意。
  • biometric_consent:包含 given_at 和 text_version 的对象,用于记录您已收集的同意。流程不会再次请求同意。
4.10.0 之前的原生 SDK 无法显示该步骤:其会话照常运行,判断结果会显示同意尚未收集。参见生物识别同意。

重要提示:披露与同意仍需在您的产品中完成

Create Session 会生成验证 URL 和会话令牌。它本身并不能证明您已向用户展示了披露信息,或已获得您具体使用场景所需的同意。 如果您从自己的应用、网站、SDK 封装或白标流程发起 Didit 会话,应当在用户开始采集之前,先在自己的用户体验中处理法律层面的事项。

建议的验证前检查清单

  1. 告知用户您的公司正在请求进行验证,并且 Didit 是为该流程提供支持的验证服务提供商/处理者。
  2. 链接到您的隐私声明以及适用于该流程的数据控制者一方适用的法律条款。
  3. 链接到 Didit 的验证隐私声明和身份验证最终用户条款。
  4. 如果您的流程包括证件采集、自拍采集、活体检测或生物识别,在适用法律或您的法律立场要求的情况下,收集明确的肯定性同意。
  5. 如果您使用自定义 UI、自定义域名或仅 API 的流程,请在将用户引导至 Didit 流程之前,先在您自己的产品中展示这些披露信息。
  6. 如果您的法务团队要求审计追踪,请保留您自己的通知或同意文本、时间戳及相关元数据记录。
法律要求因司法管辖区而异。白标品牌并不会消除 Didit 在验证流程中的角色。如果您在有生物识别专门规定的司法管辖区运营,请在上线前与法律顾问一起审查您的实施方案。

授权

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
workflow_id
string<uuid>
必填

工作流的稳定标识符,用于定义会话将运行哪些验证步骤。工作流在控制台的 工作流 页面中创建和管理。workflow_id 还会隐式选择该会话是 KYC 还是 KYB。

示例:

"11111111-2222-3333-4444-555555555555"

vendor_data
string

正在接受验证的用户的唯一标识符,例如 UUID、邮箱或内部用户 ID。此字段用于:(1) 用户分组:具有相同 vendor_data 的会话将关联到“用户”选项卡中的同一个用户资料。(2) 跨会话重复检测:在检查重复的人脸、证件、电话号码、邮箱、IP 地址或设备指纹时,具有相同 vendor_data 的会话将被视为同一用户并从匹配项中排除。若不提供 vendor_data,每个会话都将被视为独立用户,且所有潜在重复项都会被显示。我们强烈建议始终提供 vendor_data,以减少重复检测中的干扰。

示例:

"user-123"

multi_account_segment
string

您组织内部可选的重复检测领域(realm)。重复人脸检查仅会将当前会话与带有相同 segment 的其他会话进行比对,因此独立的账户体系(个人账户和企业账户,或每个 B2B 子客户对应一个账户体系)不会将合法在两边各持有一个账户的用户误标记。省略此项将使用单一的默认领域,这也是目前所有会话所使用的模式。黑名单和白名单匹配会忽略此字段。

Maximum string length: 64
示例:

"business-accounts"

callback
string

验证完成后重定向用户的 URL。Didit 会自动将 verificationSessionId 和 status(Approved、Declined、In Review)作为查询参数附加。支持自定义 URL 方案(例如 myapp://)用于移动端回调。如果省略,将使用工作流的默认 callback_url。当应用配置了允许的域名(PATCH /v3/webhook/ 上的 allowed_domains)时,http 或 https 回调必须位于这些源之一上(相同的方案、主机和端口),否则请求将在 callback 上失败并返回 400:callback must be on one of the application's allowed domains: https://app.example.com。自定义 URL 方案始终会被接受。

示例:

"https://example.com/verification/callback"

callback_method
enum<string>
默认值:initiator

决定哪个设备应处理重定向到提供的回调 URL。使用 initiator 仅重定向启动流程的设备,使用 completer 重定向完成流程的设备,或使用 both 允许任一设备触发回调。如果您发现回调无法可靠触发,我们建议将此值设置为 both。

可用选项:
initiator,
completer,
both
示例:

"both"

metadata
any

随会话一起存储并在响应和 Webhook 中原样回显的任意 JSON。接受任何 JSON 值(对象、字符串、数字、数组),但建议使用键/值对形式的 JSON 对象。不对终端用户显示。可用于传递您自己的关联 ID、A/B 测试变体或业务上下文。

示例:
tags
string[]

创建会话时按名称添加到该会话的标签。最多 10 个,每个最多 50 个字符。名称不区分大小写,并以大写形式存储。应用中尚不存在的名称将作为新标签创建。这些标签会显示在控制台的会话中,您可以在控制台中按标签进行过滤。

Maximum array length: 10
Maximum string length: 50
示例:
language
enum<string>

验证流程界面的语言代码(ISO 639-1)。控制验证期间向终端用户显示的语言。如果未提供,将自动检测并使用浏览器的语言。请在此处查看所有支持的语言。

可用选项:
en,
ar,
bg,
bn,
bs,
ca,
cnr,
cs,
da,
de,
el,
es,
et,
fa,
fi,
fr,
he,
hi,
hr,
hu,
hy,
id,
it,
ja,
ka,
kk,
ko,
ky,
lt,
lv,
mk,
mn,
ms,
nl,
no,
pl,
pt-BR,
pt,
ro,
ru,
sk,
sl,
so,
sq,
sr,
sv,
th,
tr,
uk,
uz,
vi,
zh-CN,
zh-TW,
zh
示例:

"en"

contact_details
object

可用于通知、预填验证表单以及电话验证的用户联系信息。包括电子邮箱地址、首选沟通语言和电话号码。

示例:
expected_details
object

预期的用户详细信息,用于与从用户身份证件、地址证明和其他验证步骤中提取的数据进行交叉比对。不匹配项将在决策中作为警告呈现;某些字段(例如 id_country、expected_document_types)还会改变面向用户的流程。对于企业验证(KYB)工作流,仅使用企业字段(company_name、registry_country、registration_number),它们会为用户预填充公司登记搜索,所有人员级字段均被忽略。

示例:
portrait_image
string<byte>

终端用户人脸的 Base64 编码肖像图像(最大 2MB;JPEG、PNG、WebP 或 TIFF)。当工作流是启用了人脸比对的 Biometric Authentication 工作流,或人脸比对在身份证件验证(OCR)之前运行的任何图谱工作流时,用作与活体采集进行比对的参考图像。当 vendor_data 用户已有存储的人脸图像时为可选:Didit 会按以下优先级自动复用:已通过的活体人脸、电子护照芯片照片、身份证件肖像、手动录入的个人资料人脸(仅复用来自已通过会话的人脸或您自行录入的人脸)。提供时,portrait_image 始终优先于存储的人脸。如果省略且不存在已存储的人脸(或未发送 vendor_data),会话创建将失败并返回 400。对于其他工作流类型将被忽略。

示例:

"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="

sandbox_scenario
string

仅限沙盒的场景 slug。仅在 API 密钥属于沙盒模式应用时被接受;在生产环境应用上会被拒绝。设置后,创建流程会将场景绑定的魔法值展开到会话的输入字段(contact_details、expected_details)中,以便模拟的供应商通过真实的工作流管道复现该场景的结果。请参阅 GET /v1/sandbox/scenarios/ 中的场景目录或沙盒与测试数据。只要会话仍处于 Not Started 状态,您也可以在创建后通过 POST /v3/session/{sessionId}/sandbox/arm/ 预设(或重新预设)场景。对于非证件查询,使用 lookup_partial_match、lookup_no_match 或 lookup_provider_error 来测试配置的尝试预算和回退机制。对于身份钱包,使用 wallet_cancelled、wallet_timeout 或 wallet_provider_error;approve 模拟已验证的钱包。所有目录中的钱包均可在沙盒中进行测试,包括生产环境应用中不可用的方案。模拟的尝试不会被计费。

示例:

"decline_document_expired"

sign
object

此会话的电子签名输入。documents 为待签署的文件,适用于电子签名步骤从会话中获取文件(signature_documents_source 为 session 或 both)的工作流:总计最多 20 个文件和 50 MB。field_values 用于填充工作流文件和会话文件中 prefill 为 api.<key> 的字段。针对相同的 workflow_id 和 vendor_data 再次创建会话将返回待处理的会话;如果该调用发送了 sign,其文件、字段和值必须与首次调用完全一致,若有任何不同,将返回 400 以及 {"sign": "signature_document_changed"}。请参阅 电子签名文件。

user_state
string

此人的居住地(已知时):ISO 3166-2 行政区划代码(US-IL、ES-M)或美国州代码或名称(IL、Illinois)。法律要求明确生物识别同意的州(伊利诺伊州、得克萨斯州、科罗拉多州)会使验证流程在捕获人脸之前征求同意,触发器为 declared_state。无法识别的值将返回 400。请参阅生物识别同意。

Maximum string length: 16
示例:

"US-IL"

您已向该人员收集的显式生物识别同意。这满足了要求,因此验证流程不会再次询问,决策会将其记录为 status: "given",触发器为 customer_collected。该人员在流程中已给出的回答绝不会被替换。请参阅生物识别同意。

响应

会话已创建(如果工作流最新发布的版本上已存在具有相同 vendor_data 的未完成会话,则直接返回)。响应为序列化的会话,包括用于将用户重定向至托管验证页面的 url。

session_id
string<uuid>
必填

验证会话的唯一标识符。调用 GET /v3/session/{sessionId}/decision/ 时使用此 ID。

示例:

"11111111-2222-3333-4444-555555555555"

session_number
integer
必填

在您的应用内分配给该会话的便于人类阅读的序号。便于客服支持和在仪表板中使用。

示例:

43762

session_token
string
必填

12 个字符的 URL 安全 token,用于授权终端用户通过 url 访问托管验证流程。在会话过期前一直有效。请将其视为机密信息 — 任何持有该 token 的人都可以打开此会话的验证流程。

示例:

"3FaJ9wLqX2Mz"

url
string<uri>
必填

用于重定向终端用户的托管验证 URL。该 URL 内嵌了 session_token,若已配置,还会使用您的白标域名。当请求包含 language 时,URL 会包含语言路径段:https://verify.didit.me/{language}/session/{session_token}(例如 /es/session/...);若未提供 language,则省略该路径段。

示例:

"https://verify.didit.me/session/3FaJ9wLqX2Mz"

vendor_data
string | null
必填

您在请求中传递的标识符,用于将该会话链接到您自身系统中的用户或企业。逐字回传。未提供时为 null。

示例:

"user-123"

metadata
any
必填

在创建会话时随其一起存储的任意 JSON payload。原样回显:无论您发送的是何种 JSON 值(对象、字符串、数字、数组),都将按原样返回,但建议使用 JSON 对象。不对终端用户显示。始终在响应中提供;创建时未提供则为 null。

示例:
status
enum<string>
必填

会话的当前状态。新创建的会话返回 Not Started。如果工作流最新发布的版本上已存在具有相同 vendor_data 的未完成会话,则返回的状态反映该现有会话。

可用选项:
Not Started,
In Progress,
Approved,
Declined,
In Review,
Expired,
Abandoned,
Kyc Expired,
Resubmitted,
Awaiting User
示例:

"Not Started"

callback
string<uri> | null
必填

用户完成流程后被重定向到的最终重定向 URL。Didit 会在此 URL 后追加 ?verificationSessionId={session_id}&status={status}。若请求中未提供,则回退到工作流配置的回调 URL;若两者均未设置则为 null。当应用配置了允许的域名且此 URL 是域名列表之外的 Web URL 时(例如在更改列表前设置的工作流默认值),托管流程不会将用户重定向至该 URL。

示例:

"https://example.com/verification/callback"

workflow_id
string<uuid>
必填

此会话运行所在工作流的稳定标识符。始终为工作流的稳定分组标识符。即使您在请求中引用了特定工作流版本的 UUID(向后兼容的查找方式),响应中也会包含稳定的 workflow_id。使用它可将会话与您在控制台中配置的工作流进行关联。

示例:

"11111111-2222-3333-4444-555555555555"

workflow_version
integer
必填

会话在创建时所绑定的已发布工作流版本号。在创建会话时,Didit 会将 workflow_id 解析为该工作流最新发布的版本,即使之后重新发布工作流,该会话也会继续运行该版本。

示例:

3

tags
string[]

会话中的标签,按名称列出。

示例:
最后修改于 2026年11月7日