跳转到主要内容
PATCH
curl

KYC 与 KYB 支持

此 endpoint 对 用户验证(KYC) 和 企业验证(KYB) 会话的处理方式完全相同。Didit 会同时根据这两种会话类型解析 session_id;状态转换校验对两者也相同(两种会话适用同一组状态枚举)。 响应中只包含 session_id。当下游逻辑需要根据会话类型进行分支处理时,请从检索会话中读取 session_kind。

允许的状态转换

您可以将会话更改为 Approved、Declined 或 Resubmitted。其他任何 new_status(包括 In Review)都会返回 400。会话当前状态必须是 Approved、Declined、In Review、Kyc Expired、Abandoned 或 Resubmitted 之一,否则 API 返回 400。 将已为 Approved 或 Declined 的会话再次设置为相同状态是无操作:API 返回 200,不做任何更改,不触发 Webhook,也不发送邮件。将已是 Resubmitted 的会话再次设置为 Resubmitted 会返回 400(The new status is the same as the current status.)。 如果 nodes_to_resubmit 仅包含纯后端功能(AML、DATABASE_VALIDATION、IP_ANALYSIS),重新提交会自动执行,会话无需用户操作即可回到已决策状态。30 秒内重复此类重新提交会返回 429 Too Many Requests 和 Retry-After 响应头,因为立即重复不会产生不同的结果。收到 In Review 状态时,不要在 Webhook 处理程序中自动重新提交,应先审查结果或修改底层数据。

发送前预览邮件

当 send_email: true 时,Approved 和 Declined 会向用户发送决策邮件,Resubmitted 会向用户发送包含原因的新链接。您可以在更改任何内容之前查看该邮件:
  1. 对 Approved 或 Declined 调用预览决策邮件,或对 Resubmitted 调用预览重新提交邮件。
  2. 检查渲染后的 subject 和 html、recipient,以及 will_be_sent / not_sent_reason。
  3. 使用相同的 new_status(若是重新提交,还需使用相同的 nodes_to_resubmit)、send_email: true,将 email_address 设为 recipient,将 email_language 设为您预览时使用的语言,并将 email_preview_token 设为 preview_token,然后调用此 endpoint。
两种预览都不会更改会话,也不会发送任何内容。更新时将精确发送您预览过的邮件。该凭证 15 分钟后过期。如果预览后收件人、语言、会话状态、发件人或邮件发生变化,更新会在任何更改发生之前返回 409;请重新预览,并使用新凭证进行确认。在没有 send_email: true 的情况下发送 email_preview_token 会返回 400。预览步骤是可选的:现有集成可以继续直接调用此 endpoint,无需预览。

示例

权限

需要 write:sessions 权限。两种会话类型使用同一权限。

相关

授权

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。

路径参数

sessionId
string<uuid>
必填

要更新的验证会话的 UUID。支持用户(KYC)和企业(KYB)会话 ID,服务会跨两种会话类型解析该 ID。

示例:

"11111111-2222-3333-4444-555555555555"

请求体

application/json
new_status
enum<string>
必填

目标状态。Approved 和 Declined 会记录最终的人工审核决策(二者也可相互推翻)。Resubmitted 会清除所选步骤并将该会话退回给用户。任何其他值都会返回 400。

可用选项:
Approved,
Declined,
Resubmitted
示例:

"Approved"

comment
string

变更的自由文本原因,存储在该会话的审核轨迹中,并在 Get Decision 的 reviews 数组中返回。例如 Duplicated user。

示例:

"All checks passed manual review"

nodes_to_resubmit
object[]

用户必须重做的工作流步骤。仅在 new_status 为 Resubmitted 时生效。对于 Approved/Declined,条目仍会进行模式验证(无效的 feature 值会返回 400),但在语义上符合模式的条目会被忽略。如果省略,服务器会自动选择状态为 Declined、In Review、Not Finished 或 Expired 的现有 OCR、活体检测、人脸比对、地址证明、电话、邮箱、AML、数据库核验和问卷尝试(NFC、IP 分析、年龄估算、人脸搜索和 KYB 证件尝试绝不会被自动选择;非人脸比对的人脸尝试会被选为 LIVENESS);用户从未尝试过的功能(无记录尝试)不会被选择,因此即使没有任何内容通过,零次尝试的会话也会返回 400("No features found that need resubmission");在这种情况下请显式传递 nodes_to_resubmit。无论您发送步骤的顺序如何,步骤均按工作流图谱顺序执行。KYB_REGISTRY、KYB_KEY_PEOPLE 和 KYB 别名会被拒绝并返回 400,这些父级检查会根据其子 KYC 会话重新计算。

send_email
boolean
默认值:false

是否就此变更向用户发送邮件。需要提供 email_address。对于 Approved/Declined,用户会收到状态通知;对于 Resubmitted,邮件将包含验证链接以及针对各步骤的重新提交原因。

示例:

false

email_address
string<email>

通知邮件的收件人。当 send_email 为 true 时为必填项,省略将返回 400。

示例:

"user@example.com"

email_language
string
默认值:en

通知邮件的语言。在 schema 层面接受任何字符串;不支持的代码将以静默方式回退为英语(en)。

示例:

"en"

email_preview_token
string
write-only

来自预览决策邮件(适用于 Approved 和 Declined)或预览重新提交邮件(适用于 Resubmitted)的可选凭证:即其 preview_token。仅在 send_email: true 时有效;若未提供,请求将返回 400。收件人、语言、会话状态、发件人和邮件(以及在重新提交时所选的步骤)仍必须与预览匹配,且凭证在 15 分钟后过期。否则在会话发生变更或发送邮件之前,请求将返回 409。现有集成可以省略此字段。

Required string length: 1 - 512

响应

状态已更新。响应仅包含 session_id;请通过 Get Decision 获取更新后的会话。变更提交后会触发 status.updated Webhook。重复传入 Approved 或 Declined 会返回相同的响应体且不做任何更改。

session_id
string<uuid>

已更新会话的 UUID。

最后修改于 2026年11月7日