跳转到主要内容
POST
Python
预览不会更改会话,也不会发送邮件。 查看响应后,请使用 更新会话状态 进行确认,并将返回的 preview_token 作为 email_preview_token 传入。 回执 15 分钟后过期。 回执已更改或已过期时,接口会在修改会话或发送邮件之前返回 409。 发生冲突后,请重新生成预览。 现有 API 集成可以省略回执;在控制台中确认预览时,控制台会自动提供回执。 发件人和品牌信息遵循您现有的白标配置。 邮件内容来自已翻译的验证模板;模板输入不接受任意主题、邮件正文或操作 URL。

谁会收到邮件

email_address 为可选项。 如果未传入,邮件将发送到用户本人的邮箱:即其在流程中通过邮箱验证步骤验证的地址;若没有,则使用创建会话时 contact_details 中提供的地址。 您在 email_address 中传入的地址优先。 recipient_source 用于说明适用的是哪个地址:

是否会发送邮件

使用 send_email: true 确认重新提交时,若会发送邮件,则 will_be_sent 为 true。 为 false 时,not_sent_reason 说明原因:

确认重新提交

使用以下字段调用更新会话状态: 响应中的 language 表示邮件所用的语言:当您请求的语言不可用时,为英语。

重复的仅后端重新提交

当需要重新提交的所有步骤都无需用户参与(AML 筛查、数据库核验或 IP 分析)时,每 30 秒只能为用户重新提交一次会话。 在该时间窗口内,预览会返回 429,与更新会话状态的行为一致,等待时间通过 Retry-After 响应头返回。

相关内容

授权

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
nodes_to_resubmit
object[]

要预览的步骤,使用与重新提交相同的验证、选择和工作流排序。省略此项将自动选择需要重新提交的已记录尝试。

email_address
string<email>

可选。将邮件发送至此地址,而非此人的地址。如未提供,收件人为该人在流程中验证的地址,否则为 contact_details 中提供的地址。此调用不会发送邮件。

示例:

"user@example.com"

email_language
string
默认值:en

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

示例:

"en"

响应

仅供预览。会话保持不变且不会发送电子邮件。

recipient
string
必填

邮件发送的目标地址。若该人员无已知地址,则为空字符串:此时无法发送邮件,且 preview_token 同样为空。确认时请将其作为 email_address 传递。

示例:

"person@example.com"

recipient_source
enum<string>
必填

recipient 的来源。request:您传递的 email_address。email_verification:用户在流程的邮箱验证步骤中验证的地址。contact_details:创建会话时在 contact_details 中提供的地址。没有地址时为空字符串。

可用选项:
email_verification,
contact_details,
request,
示例:

"email_verification"

sender
string
必填

发送邮件时使用的 From 请求头。

示例:

"Example App <no-reply@mail.example.com>"

sender_name
string
必填

sender 的显示名称部分。

示例:

"Example App"

sender_email
string<email>
必填

sender 的地址部分。

示例:

"no-reply@mail.example.com"

sender_kind
enum<string>
必填

customer:邮件从您应用的已验证发送方域名发出(白标)。didit:从 Didit 自己的发送方发出。

可用选项:
customer,
didit
示例:

"customer"

subject
string
必填

与发送时完全一致的主题行。

示例:

"Action Required: Complete your verification in Example App"

html
string
必填

发送时完全一致的电子邮件 HTML,其徽标作为 data URL 嵌入。请在沙盒 frame 中渲染,切勿直接在您的应用 DOM 中渲染。

示例:

"<!DOCTYPE html><html><body>...</body></html>"

text
string
必填

电子邮件的纯文本内容,与该用户的“消息”会话中保留的一致,用于紧凑预览(HTML 仍为该用户收到的电子邮件形式)。

示例:

"Almost there\n\nSome steps need to be completed again.\nHere’s what to fix:\n\nhttps://verify.didit.me/session/abc123"

language
string
必填

邮件所用的语言。如果您请求的 email_language 不支持,则为英语(en)。

示例:

"en"

will_be_sent
boolean
必填

使用 send_email: true 确认更改是否会发送此电子邮件。当设置了 not_sent_reason 时为 false。

示例:

true

not_sent_reason
enum<string> | null
必填

确认操作不会发送电子邮件的原因;若将发送邮件,则为 null。no_user_action:所有选定步骤均无需该用户参与即可运行,因此重新提交会自动完成且不发送任何电子邮件。no_recipient:未获知该用户的地址,且您未传入任何地址。sandbox:接收者未选择接收沙盒邮件投递的沙盒会话,因此发送仅为模拟。

可用选项:
no_user_action,
no_recipient,
sandbox,
null
示例:

null

nodes_to_resubmit
object[]
必填
requires_user_action
boolean
必填

所选检查中是否至少有一项需要用户交互。这并不预示最终的工作流结果。

preview_token
string
必填

此特定邮件的签名收据,有效期为 15 分钟。将其作为 email_preview_token 传递给更新会话状态。当没有收件人时为空字符串。

示例:

"eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000"

最后修改于 2026年11月7日