> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.
# 创建会话 API：启动 KYC 或 KYB 验证
> Didit 的 POST /v3/session/ 端点可启动验证会话，统一支持 KYC 与 KYB，按量计费，推理耗时低于 2 秒，每月赠送 $10 免费额度。
创建会话提示词
将提示词复制到剪贴板
\
\`Create a verification session via Didit's REST API.
Endpoint:
POST https://verification.didit.me/v3/session/
Authentication:
Use the x-api-key header with your Didit API key. The workflow's type (KYC or KYB) determines which kind of session is created — there is no separate endpoint for KYB.
Request body:
\- workflow_id (string, UUID, required) — Stable workflow UUID from /v3/workflows/. KYC workflows create User Verification sessions; KYB workflows create Business Verification sessions.
\- vendor_data (string, optional) — Your stable identifier for the entity (user or business). Strongly recommended: it binds the session to a User or Business entity and is used for duplicate detection across sessions.
\- callback (string, URL, optional): Where the hosted flow redirects the user when finished. Didit appends ?verificationSessionId={session_id}&status={status}. Falls back to the workflow default. When the application has allowed domains (allowed_domains on PATCH /v3/webhook/), an http or https callback must be on one of those origins (same scheme, host and port), otherwise creation fails with 400 on callback: "callback must be on one of the application's allowed domains: https://app.example.com". Custom URL schemes (app deep links such as myapp://) are always accepted. A workflow-default callback outside the allowed domains is not used for the redirect.
\- callback_method (string, optional, default "initiator") — One of "initiator", "completer", "both". Use "both" if the callback sometimes fails to fire.
\- metadata (object, optional) — Arbitrary JSON echoed back in responses and webhooks. Not shown to the user.
\- tags (array of strings, optional): Tags added to the session when it is created, by name, for example ["VIP", "ONBOARDING Q4"]. Up to 10, each up to 50 characters. Names are case-insensitive and stored in upper case; a name that does not exist yet in the application is created as a new tag. The tags show on the session in the console, where you can filter by them, and come back in the create response.
\- language (string, optional) — ISO 639-1 code for the verification UI (en, es, fr, de, pt, etc.). Defaults to browser detection.
\- contact_details (object, optional) — { email, send_notification_emails, email_lang, phone }. Pre-fills phone/email steps and (optionally) sends notification emails.
\- expected_details (object, optional) — Expected first_name, last_name, date_of_birth, nationality (ISO-3), id_country (ISO-3), expected_document_types (e.g. ["P","ID","DL","RP","SSC"]). Mismatches surface as decision warnings. For Business Verification (KYB) workflows, pass the business fields instead — company_name, registry_country, registration_number — to pre-fill the company registry search; registry_country is ISO 3166-1 alpha-2 and can include the state for state-level registries (e.g. "US-CA"), same format as the KYB Registry Search country_code. Person-level fields are ignored on KYB sessions.
\- portrait_image (string, base64, conditional) — Reference face for Biometric Authentication workflows (and graph workflows where Face Match runs before ID Verification). Max 2MB; JPEG, PNG, WebP, or TIFF. Optional when the vendor_data user already has a stored face: Didit reuses it automatically (approved liveness face, then ePassport chip photo, then ID document portrait, then a manually enrolled profile face). If omitted and no stored face exists, creation fails with 400. Ignored for other workflow types.
\- multi_account_segment (string, optional, max 64 chars) — Duplicate-detection realm inside your own organization. Duplicate face checks only compare this session against other sessions carrying the same segment, so an organization that runs separate account bases (personal vs business, or one per sub-client) does not see a person who legitimately holds one account in each reported as a duplicate. Omit it to use the single default realm — which is what every session uses today, so existing integrations are unaffected. Blocklist and allowlist matching ignore this field: a blocklisted face stays blocklisted in every segment.
\- sandbox_scenario (string, optional, sandbox applications only): Scenario slug from the sandbox catalog (GET /v1/sandbox/scenarios/). Expands the scenario's bundled magic values onto contact_details/expected_details so the session reproduces that outcome. Rejected with 400 on live applications. You can also arm or re-arm a scenario after create, as long as the session is still Not Started, via POST /v3/session/{session_id}/sandbox/arm/. See /integration/sandbox-testing.
\- user_state (string, optional, max 16 chars): Where the person lives, when you know it: an ISO 3166-2 code (US-IL) or a US state code or name (IL, Illinois). In Auto consent mode, Illinois, Texas or Colorado makes the flow ask for explicit biometric consent before the first face capture. 400 on an unrecognized value.
\- biometric_consent (object, optional): Consent you already collected: { given_at (ISO 8601, not in the future), text_version (max 64 chars) }. The flow does not ask again; the decision records it as given with trigger customer_collected.
\- sign (object, optional): { documents: [ { title, file_name, content_base64, fields } ], field_values: { : value } }. documents is for a workflow whose E-signature step takes documents from the session (signature_documents_source "session" or "both"). file_name ends in .pdf or .docx; content_base64 is the file in base64. Up to 20 documents and 50 MB in total; a PDF up to 20 MB and 100 pages, without a password, scripts or attachments; a Word file (.docx) up to 20 MB, converted to PDF while the request runs, at most 5 per session. fields is optional (up to 200 per document): signature, initials, full_name, date_signed, text, checkbox, email or data fields, each with a key unique in its document (^[a-z][a-z0-9_]{0,63}$), placed by page, x, y, width and height, or by anchor text ({ text, occurrence, offset_x, offset_y, width, height }). role defaults to the step's signer. field_values fills the fields whose prefill is "api.", on workflow and session documents alike: strings of 1 to 500 characters, booleans for checkboxes. 400 when the workflow has no E-signature step, takes workflow documents only and you sent documents, or needs session documents you didn't send; field_anchor_not_found, field_value_unknown, field_value_missing or field_value_invalid for fields and values. See /core-technology/electronic-signature/overview.
Idempotency:
Within one application, only one non-finished session can exist per (workflow_id, vendor_data). Calling create again with the same pair returns the existing session (and updates its callback + metadata, and adds any tags you send) instead of creating a duplicate. If you send sign again, its documents, fields and field values must be identical (same order, titles, file names, content, fields and values), or the call returns 400 { "sign": "signature_document_changed" }.
curl example:
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: " \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "",
"vendor_data": "user-42",
"callback": "https://yourapp.com/callback",
"metadata": { "plan": "premium" }
}'
Response (201 Created) — keys you must handle:
\- session_id (UUID) — use this on every subsequent /v3/session/{session_id}/... call.
\- session_kind ("user" | "business") — discriminator, dispatch on this.
\- session_number (int) — human-friendly per-application sequence.
\- session_token (string) — short-lived, embedded in the hosted URL. Treat as secret.
\- url (string) — hosted verification URL. Redirect the end user here. (Field name is "url", NOT "verification_url".)
\- status (string) — newly created sessions return "Not Started".
\- workflow_id, workflow_version, vendor_data, metadata, callback — echoed back.
See /reference/data-models for the full schema.
Failure modes:
\- 400 — { "workflow_id": ["Invalid workflow_id."] } when the UUID is unknown.
\- 400 — { "vendor_data": ["This user or business has been blocked and cannot create new verification sessions."] } when blocklisted.
\- 400 — { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } when out of credits.
\- 400 — { "portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first." } on a Face Match workflow when portrait_image is omitted and the vendor_data user has no stored face.
\- 401 — invalid or missing API key.
\- 403 — { "detail": "You do not have permission to perform this action." } when the key lacks write:sessions.
\- 429 — rate limited (600 successful calls/minute per token/IP). Honour Retry-After.
Disclosure & consent:
This endpoint generates a URL — it does not record that you obtained user consent. Show your privacy notice and any biometric-specific consent in your own UX before redirecting to the hosted flow.
For people covered by Illinois, Texas or Colorado law, the hosted flow and native SDK 4.10.0 or later can ask for explicit biometric consent before the selfie; native SDKs below 4.10.0 cannot show that step. See /getting-started/biometric-consent.
Next step:
After the user finishes (status changes to Approved / Declined / In Review), call GET https://verification.didit.me/v3/session/{session_id}/decision/ for the full decision — see /sessions-api/retrieve-session.
For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`
\
粘贴到
## KYC 与 KYB 支持同一个 endpoint 既可以创建用户验证会话，也可以创建企业验证会话。**工作流的类型**决定会话种类：- 传入 **KYC 工作流**的 `workflow_id`，将创建用户验证（KYC）会话。响应中的 `session_kind: "user"`。
- 传入 **KYB 工作流**的 `workflow_id`，将创建企业验证（KYB）会话。响应中的 `session_kind: "business"`。请在控制台的 *工作流 → 创建工作流* 中配置工作流。工作流在创建时即为 KYC 或 KYB 之一，创建后无法更改类型。## 示例> [tab] 用户验证（KYC）
>
> ```bash theme={null}
> curl -X POST https://verification.didit.me/v3/session/ \
> -H "x-api-key: YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{
> "workflow_id": "YOUR_KYC_WORKFLOW_ID",
> "vendor_data": "user-42",
> "callback": "https://yourapp.com/callback"
> }'
> ```
>
> **响应（201 Created）：**
>
> ```json theme={null}
> {
> "session_id": "4c5c7f3a-1f82-4f3b-8d8e-1a8d2d2f9b7a",
> "session_kind": "user",
> "session_number": 1024,
> "session_token": "...",
> "url": "https://verify.didit.me/session/...",
> "status": "Not Started",
> "workflow_id": "YOUR_KYC_WORKFLOW_ID",
> "vendor_data": "user-42"
> }
> ```> [tab] 企业验证（KYB）
>
> ```bash theme={null}
> curl -X POST https://verification.didit.me/v3/session/ \
> -H "x-api-key: YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{
> "workflow_id": "YOUR_KYB_WORKFLOW_ID",
> "vendor_data": "biz-acme-001",
> "callback": "https://yourapp.com/callback"
> }'
> ```
>
> **响应（201 Created）：**
>
> ```json theme={null}
> {
> "session_id": "bs-01HJX1...",
> "session_kind": "business",
> "session_number": 89,
> "session_token": "...",
> "url": "https://verify.didit.me/session/...",
> "status": "Not Started",
> "workflow_id": "YOUR_KYB_WORKFLOW_ID",
> "vendor_data": "biz-acme-001"
> }
> ```## 电子签名文档当工作流包含从会话获取文档的[电子签名](https://docs.didit.me/zh/core-technology/electronic-signature/overview.md)步骤（即 `signature_documents_source` 设为 `session` 或 `both`）时，请在 `sign.documents` 中发送这些文档。每个文档均为 base64 编码的文件，因此 Didit 无需再从 URL 获取文件。```json theme={null}
{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-42",
"sign": {
"documents": [
{
"title": "Loan agreement",
"file_name": "loan-agreement.pdf",
"content_base64": "JVBERi0xLjcKJc...",
"fields": [
{ "key": "borrower_signature", "type": "signature", "label": "Borrower signature", "page": 3, "x": 0.1, "y": 0.78, "width": 0.32, "height": 0.06 },
{ "key": "date_signed", "type": "date_signed", "label": "Date", "page": 3, "x": 0.6, "y": 0.8, "width": 0.2, "height": 0.03, "date_format": "DD/MM/YYYY" },
{ "key": "loan_amount", "type": "data", "label": "Loan amount", "page": 1, "x": 0.34, "y": 0.31, "width": 0.3, "height": 0.03, "prefill": "api.loan_amount" },
{ "key": "initials", "type": "initials", "anchor": { "text": "[[initials]]", "occurrence": "all", "offset_x": 0, "offset_y": -0.005, "width": 0.12, "height": 0.04 } }
]
}
],
"field_values": { "loan_amount": "12,000 EUR" }
}
}
```| 字段 | 规则 |
| - | - |
| `title` | 向签署人显示。1 至 255 个字符。默认为 `file_name`。 |
| `file_name` | 必填。以 `.pdf` 或 `.docx` 结尾。1 至 255 个字符。 |
| `content_base64` | 必填。PDF 最多 20 MB、100 页，不得有密码、脚本或附件。Word 文件最多 20 MB，请求执行期间会转换为 PDF，转换时间最多 25 秒；转换后的 PDF 受相同限制。每个会话最多 5 个 Word 文件。 |
| `fields` | 可选。最多 200 个[字段](https://docs.didit.me/zh/core-technology/electronic-signature/overview.md#文档上的字段)，放置在文档上，采用不含 `id` 的字段结构。每个字段需要 `key` 和 `type`，并且需指定位置（`page`、`x`、`y`、`width` 和 `height`）或 [`anchor`](#按锚点文本放置字段)。`role` 默认为该步骤的签署人，`required` 和 `label` 根据类型取默认值。Didit 会根据字段所在位置设置 `position`。页码和位置指的是 PDF；对于 Word 文件，指的是转换后的 PDF。 |如果不提供 `fields`，签署人只需阅读文档并表示同意。### 按锚点文本放置字段字段可以不使用位置，而是带有 `anchor`：即文档中标记字段放置位置的一段文本。锚点适用于为每个会话生成的文档，例如基于 Word 模板生成的文档。对于工作流文档，请在控制台中放置字段。| `anchor` 属性 | 规则 |
| - | - |
| `text` | 1 至 64 个字符，在文档的文本中搜索。对于 Word 文件，在转换后的 PDF 中搜索。 |
| `occurrence` | `first`（默认）仅在第一处匹配处放置一个字段。`all` 在每处匹配处各放置一个字段，第一个之后的字段 key 依次加上 `_2`、`_3` 等后缀。 |
| `offset_x`、`offset_y` | 页面的比例值。字段的左上角为锚点文本左上角加上这些偏移量。 |
| `width`、`height` | 字段的尺寸，为页面的比例值。 |如果文档中找不到该文本，调用将返回 `400` 以及 `field_anchor_not_found` 和该字段的 key。Didit 不会从 PDF 中删除锚点文本，因此请将其设置为与页面背景相同的颜色。### 字段值`sign.field_values` 用于设置所有 `prefill` 为 `api.` 的字段的值，适用于工作流文档和会话文档。它是一个以这些 `` 名称为键的对象。`text` 和 `data` 字段的值为 1 至 500 个字符的字符串，`checkbox` 字段的值为布尔值。```json theme={null}
{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-42",
"sign": {
"field_values": { "credit_limit": "3,000 EUR", "monthly_fee": "4.90 EUR" }
}
}
```| 错误（`400`） | 触发条件 |
| - | - |
| `field_value_unknown` | 提供的 key 不属于任何字段。 |
| `field_value_missing` | 必填字段的 `api.` 没有提供值。 |
| `field_value_invalid` | 值未通过其字段的[校验](https://docs.didit.me/zh/core-technology/electronic-signature/overview.md#验证)。 |### 错误与重复调用一个会话最多包含 20 个文档，总大小不超过 50 MB。在以下情况下，调用将返回 `400` 以及 `sign` 错误：- 工作流不包含电子签名步骤。
- 您发送了 `sign.documents`，但该步骤只接受工作流文档。
- 该步骤只接受会话文档，而您未发送任何文档；或该步骤没有工作流文档，且您也未发送任何文档。
- 某个文档过大、不是有效的 base64，或不是受支持的文件类型。
- Word 文件被 `signature_document_not_supported` 拒绝，或无法转换并返回 `signature_document_conversion_failed`，两者均附带[支持的文件](https://docs.didit.me/zh/core-technology/electronic-signature/overview.md#支持的文件)中列出的 `reason`。
- 某个字段无效，其锚点未找到（`field_anchor_not_found`），或[字段值](#字段值)被拒绝。使用相同的 `workflow_id` 和 `vendor_data` 再次调用创建接口，将返回待处理的会话。如果该调用包含 `sign`，其文档、字段和字段值必须与第一次完全一致（顺序、标题、文件名、内容、字段和值均相同）。任何不同之处都会返回 `400` 以及 `{"sign": "signature_document_changed"}`：请使用其他 `vendor_data`，或等待待处理的会话完成。## 沙盒场景测试在沙盒模式的应用中，传入 `sandbox_scenario` 可以预设确定的结果（通过、特定的拒绝结果，或审核中场景），且不会调用真实服务商，也不会消耗您的余额：```json theme={null}
{
"workflow_id": "YOUR_SANDBOX_WORKFLOW_ID",
"sandbox_scenario": "decline_document_expired"
}
```在正式环境的应用中，`sandbox_scenario` 会被拒绝，返回 `400`。如果创建时尚不确定结果，可以在会话仍处于 `Not Started` 状态时，稍后通过 `POST /v3/session/{session_id}/sandbox/arm/` 设置（或重新设置）场景。托管流程中的预流程场景选择器也使用同一个端点。完整的场景目录、魔法值注册表以及 arm endpoint 的请求和响应结构，请参阅[沙盒与测试数据](https://docs.didit.me/zh/integration/sandbox-testing.md)。## `vendor_data` 将会话绑定到实体- 对于 KYC 工作流：绑定到[用户实体](https://docs.didit.me/zh/entities/users/overview.md)。如果用户不存在，将自动创建。
- 对于 KYB 工作流：绑定到[企业实体](https://docs.didit.me/zh/entities/businesses/overview.md)。如果是新实体，将自动创建。更多信息请参阅[供应商数据关联](https://docs.didit.me/zh/entities/vendor-data-linking.md)。## 伊利诺伊州、得克萨斯州和科罗拉多州的生物识别同意托管流程以及 4.10.0 或更高版本的原生 SDK 可以在首次人脸采集之前显示明确的生物识别同意步骤，具体取决于应用的同意模式以及用户所在位置。以下两个可选字段会影响该判断：- `user_state`：用户居住的地区（如果您知道）。可填写 `US-IL`、`IL` 或 `Illinois`。在自动模式下，如果用户位于涵盖的州，流程会请求同意。
- `biometric_consent`：包含 `given_at` 和 `text_version` 的对象，用于记录您已收集的同意。流程不会再次请求同意。4.10.0 之前的原生 SDK 无法显示该步骤：其会话照常运行，判断结果会显示同意尚未收集。参见[生物识别同意](https://docs.didit.me/zh/getting-started/biometric-consent.md)。## 重要提示：披露与同意仍需在您的产品中完成`Create Session` 会生成验证 URL 和会话令牌。它**本身并不能**证明您已向用户展示了披露信息，或已获得您具体使用场景所需的同意。如果您从自己的应用、网站、SDK 封装或白标流程发起 Didit 会话，应当在用户开始采集之前，先在自己的用户体验中处理法律层面的事项。## 建议的验证前检查清单1. 告知用户**您的公司**正在请求进行验证，并且 **Didit** 是为该流程提供支持的验证服务提供商/处理者。
2. 链接到**您的隐私声明**以及适用于该流程的数据控制者一方适用的法律条款。
3. 链接到 Didit 的[验证隐私声明](https://didit.me/terms/verification-privacy-notice)和[身份验证最终用户条款](https://didit.me/terms/identity-verification)。
4. 如果您的流程包括证件采集、自拍采集、活体检测或生物识别，在适用法律或您的法律立场要求的情况下，收集**明确的肯定性同意**。
5. 如果您使用自定义 UI、自定义域名或仅 API 的流程，请在将用户引导至 Didit 流程之前，先在您自己的产品中展示这些披露信息。
6. 如果您的法务团队要求审计追踪，请保留您自己的通知或同意文本、时间戳及相关元数据记录。> [!WARNING]
>
> 法律要求因司法管辖区而异。白标品牌并不会消除 Didit 在验证流程中的角色。如果您在有生物识别专门规定的司法管辖区运营，请在上线前与法律顾问一起审查您的实施方案。
## OpenAPI
````yaml zh/openapi-25.json POST /v3/session/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: 身份证件验证 API。使用 x-api-key 请求头进行身份验证。
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/session/:
post:
tags:
- Sessions
summary: 创建验证会话
description: >-
创建用户验证（KYC）或企业验证（KYB）会话，并获取托管验证 `url` 以及
`session_token`，以便为您的终端用户重定向或嵌入。`workflow_id` 用于选择运行哪些验证步骤以及该会话是 KYC 还是
KYB。
每当需要验证用户或企业时，请从您的后端调用此接口（切勿在浏览器中调用 — API
密钥属于机密）：例如在注册时、执行敏感操作前或需要重新验证时。前置条件：已发布的工作流（在控制台
[Workflows](https://docs.didit.me/zh/console/workflows)
页面中创建）以及具有可用额度的应用 API 密钥。沙盒应用会跳过额度检查。
**幂等性：**当提供了 `vendor_data` 且该工作流的**当前最新已发布版本**上已存在具有相同 `vendor_data`
的未完成会话（`Not Started`、`In Progress`、`Resubmitted` 或 `Awaiting
User`）（并且该会话已具有托管验证 URL）时，将返回现有会话（状态码仍为 `201`）而不是创建重复会话 — 其 `callback` 和
`metadata`
会更新为新提供的值。在旧版本工作流（此后已重新发布）上创建的未完成会话**不会**被复用；而是会创建一个固定到最新已发布版本的新会话。处于
`Approved`、`Declined`、`In Review`、`Expired`、`Abandoned` 或 `Kyc Expired`
状态的会话绝不会被复用。
**副作用：**生成并存储托管验证 URL；如果 `contact_details.send_notification_emails` 为
`true` 且提供了邮箱，则会发送验证邀请邮件。会话将在工作流配置的会话过期时间后过期。对于 KYB
工作流，`contact_details.phone` 和 `expected_details` 将被忽略。
operationId: post_v3_session_create
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- workflow_id
properties:
workflow_id:
type: string
format: uuid
description: >-
工作流的稳定标识符，用于定义会话将运行哪些验证步骤。工作流在控制台的
[工作流](/zh/console/workflows) 页面中创建和管理。`workflow_id`
还会隐式选择该会话是 KYC 还是 KYB。
example: 11111111-2222-3333-4444-555555555555
x-readme-id: '0.0'
vendor_data:
type: string
description: >-
正在接受验证的用户的唯一标识符，例如 UUID、邮箱或内部用户 ID。此字段用于：(1) **用户分组**：具有相同
vendor_data 的会话将关联到“用户”选项卡中的同一个用户资料。(2)
**跨会话重复检测**：在检查重复的人脸、证件、电话号码、邮箱、IP 地址或设备指纹时，具有相同 vendor_data
的会话将被视为同一用户并从匹配项中排除。若不提供
vendor_data，每个会话都将被视为独立用户，且所有潜在重复项都会被显示。我们强烈建议始终提供
vendor_data，以减少重复检测中的干扰。
example: user-123
x-readme-id: '0.1'
multi_account_segment:
type: string
maxLength: 64
description: >-
您组织内部可选的重复检测领域（realm）。重复人脸检查仅会将当前会话与带有相同 segment
的其他会话进行比对，因此独立的账户体系（个人账户和企业账户，或每个 B2B
子客户对应一个账户体系）不会将合法在两边各持有一个账户的用户误标记。省略此项将使用单一的默认领域，这也是目前所有会话所使用的模式。黑名单和白名单匹配会忽略此字段。
example: business-accounts
callback:
type: string
description: >-
验证完成后重定向用户的 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 方案始终会被接受。
example: https://example.com/verification/callback
x-readme-id: '0.2'
callback_method:
type: string
description: >-
决定哪个设备应处理重定向到提供的回调 URL。使用 `initiator` 仅重定向启动流程的设备，使用
`completer` 重定向完成流程的设备，或使用 `both`
允许任一设备触发回调。如果您发现回调无法可靠触发，我们建议将此值设置为 `both`。
enum:
- initiator
- completer
- both
default: initiator
example: both
x-readme-id: '0.3'
metadata:
description: >-
随会话一起存储并在响应和 Webhook 中原样回显的任意 JSON。接受任何 JSON
值（对象、字符串、数字、数组），但建议使用键/值对形式的 JSON 对象。不对终端用户显示。可用于传递您自己的关联
ID、A/B 测试变体或业务上下文。
example:
user_type: premium
account_id: ABC123
x-readme-id: '0.4'
tags:
type: array
items:
type: string
maxLength: 50
maxItems: 10
description: >-
创建会话时按名称添加到该会话的标签。最多 10 个，每个最多 50
个字符。名称不区分大小写，并以大写形式存储。应用中尚不存在的名称将作为新标签创建。这些标签会显示在控制台的会话中，您可以在控制台中按标签进行过滤。
example:
- VIP
- ONBOARDING Q4
language:
type: string
description: >-
验证流程界面的语言代码（ISO
639-1）。控制验证期间向终端用户显示的语言。如果未提供，将自动检测并使用浏览器的语言。请在[此处](/zh/integration/supported-languages)查看所有支持的语言。
enum:
- 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
example: en
x-readme-id: '0.5'
contact_details:
type: object
description: 可用于通知、预填验证表单以及电话验证的用户联系信息。包括电子邮箱地址、首选沟通语言和电话号码。
example:
email: john.doe@example.com
send_notification_emails: true
email_lang: en
phone: '+14155552671'
properties:
email:
type: string
format: email
description: >-
用户的邮箱地址（例如
"john.doe@example.com"），将在[邮箱验证](/zh/core-technology/email-verification/overview)步骤中使用。如果未提供，用户必须在验证流程中自行提供。
example: john.doe@example.com
x-readme-id: '1.0'
send_notification_emails:
type: boolean
default: false
description: >-
若为 true 且提供了邮箱，Didit
会在创建用户验证（KYC）或企业验证（KYB）会话时以异步方式发送初始“验证您的身份”邮件。Didit
还会将需要人工审核的会话的验证状态通知发送至所提供的邮箱地址（例如，从“审核中”变为“已通过”或“已拒绝”）。这有助于用户在验证完成后返回您的应用。如果您为该会话启用了白标，发送的邮件将采用白标定制。
example: true
x-readme-id: '1.1'
email_lang:
type: string
description: >-
邮件通知的语言代码（ISO 639-1）。控制所有邮件通信的语言（例如
"en"、"es"、"fr"）。未存储默认值；省略时，验证邀请邮件仅在发送时回退为英语（`en`）。下方的枚举为快照；支持值的实时基准信息请参阅[支持的语言](/zh/integration/supported-languages)文档，在依赖特定代码之前，请始终查阅该文档。
enum:
- 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
example: en
x-readme-id: '1.2'
phone:
type: string
description: >-
将在[电话验证](/zh/core-technology/phone-verification/overview)步骤中使用的
E.164 格式电话号码（例如
"+14155552671"）。如果未提供，用户必须在验证流程中输入。企业验证（KYB）工作流会忽略此字段。**重要提示：**仅当该电话号码为有效的
E.164
电话号码时才会强制生效。如果提供的号码无效或无法解析，系统将忽略该号码，用户可以在电话验证步骤中输入任意有效电话号码。
example: '+14155552671'
x-readme-id: '1.3'
x-readme-id: '0.4'
expected_details:
type: object
description: >-
预期的用户详细信息，用于与从用户身份证件、地址证明和其他验证步骤中提取的数据进行交叉比对。不匹配项将在决策中作为警告呈现；某些字段（例如
`id_country`、`expected_document_types`）还会改变面向用户的流程。对于企业验证（KYB）工作流，仅使用企业字段（`company_name`、`registry_country`、`registration_number`），它们会为用户预填充公司登记搜索，所有人员级字段均被忽略。
example:
first_name: John
last_name: Doe
date_of_birth: '1990-05-15'
nationality: USA
id_country: USA
expected_document_types:
- P
- ID
properties:
first_name:
type: string
description: >-
用户的名。例如
`John`。比对采用模糊比较，您可以通过在控制台中为身份证件和地址证明工作流配置姓名匹配分数阈值来调整严格程度。
example: John
x-readme-id: '1.0'
last_name:
type: string
description: >-
用户的姓。例如
`Doe`。比对采用模糊比较，您可以通过在控制台中为身份证件和地址证明工作流配置姓名匹配分数阈值来调整严格程度。
example: Doe
x-readme-id: '1.1'
date_of_birth:
type: string
format: date
description: 用户的出生日期，格式为：YYYY-MM-DD。例如 `1990-05-15`。
example: '1990-05-15'
x-readme-id: '1.2'
gender:
type: string
nullable: true
enum:
- M
- F
default: null
description: 用户的性别。必须为 'M'、'F' 或 null。
example: M
x-readme-id: '1.3'
nationality:
type: string
description: >-
代表申请人原籍国家/地区的 ISO 3166-1 alpha-3 国家/地区代码。例如
`USA`。请参阅[受支持国家/地区代码的完整列表](https://docs.didit.me/zh/core-technology/id-verification/supported-documents-id-verification#按国家/地区列出的支持证件)。
example: USA
x-readme-id: '1.4'
country:
type: string
description: >-
用作身份证件验证和地址证明国家/地区不匹配检查备用项的 ISO 3166-1 alpha-3
国家/地区代码。当提供了 `address` 且未设置 `id_country` 和 `poa_country`
时必填。
example: USA
x-readme-id: 1.4.1
id_country:
type: string
description: >-
代表申请人身份证件预期国家/地区的 ISO 3166-1 alpha-3 国家/地区代码（可能与国籍不同）。例如
`GBR`。在身份证件验证国家/地区不匹配检查中优先于
`country`。请参阅[受支持国家/地区代码的完整列表](https://docs.didit.me/zh/core-technology/id-verification/supported-documents-id-verification#按国家/地区列出的支持证件)。
example: GBR
x-readme-id: '1.5'
poa_country:
type: string
description: >-
代表地址证明文件预期国家/地区的 ISO 3166-1 alpha-3 国家/地区代码。例如 `USA`。在
POA 国家/地区不匹配检查中优先于
`country`。请参阅[受支持国家/地区代码的完整列表](https://docs.didit.me/zh/core-technology/id-verification/supported-documents-id-verification#按国家/地区列出的支持证件)。
example: USA
x-readme-id: 1.5.1
address:
type: string
description: >-
人类可读格式的地址，包含尽可能多的详细信息。例如 `123 Main St, San Francisco, CA
94105, USA`。提供此参数时，您还必须传递 `country` 或
`poa_country`，否则请求将失败并返回 `400`。
example: 123 Main St, San Francisco, CA 94105, USA
x-readme-id: '1.6'
identification_number:
type: string
description: 用户的证件号码、个人编号或税号。例如 `123456789`。
example: '123456789'
x-readme-id: '1.7'
ip_address:
type: string
description: >-
会话的预期 IP 地址，采用 IPv4 或 IPv6 格式。如果实际 IP 地址与此值不一致，将记录警告。例如
`192.168.1.100` 或 `2001:db8::1`。
example: 192.168.1.100
x-readme-id: '1.8'
expected_document_types:
type: array
description: >-
限制用户在身份证件验证（OCR）步骤中可以出示的证件类型。设置后，证件选择界面仅显示所请求的类型，且返回的
`documents_allowed` 会进行相应过滤。值不区分大小写并会自动去重；无法识别的值会被拒绝并返回
`400`。允许的代码：`P`（护照）、`ID`（国民身份证）、`DL`（驾照）、`RP`（居留许可）、`HIC`（健康保险卡）、`TC`（税卡）、`SSC`（社保卡）。
items:
type: string
enum:
- P
- ID
- DL
- RP
- HIC
- TC
- SSC
example:
- P
- ID
x-readme-id: '1.9'
company_name:
type: string
maxLength: 255
description: >-
待验证企业的预期法定名称。例如，`Tesco
PLC`。在企业验证（KYB）工作流中预填充公司登记搜索的公司名称字段；若同时提供了
`registration_number`，登记查询将结合这两个标识符。在 KYC 工作流中忽略。
example: Tesco PLC
x-readme-id: '1.10'
registry_country:
type: string
maxLength: 10
description: >-
企业所注册的公司登记处所在国家/地区的 ISO 3166-1 alpha-2 代码。例如
`GB`。如果公司登记处在州或省级别运作，请以 `XX-YY` 格式附加 ISO 3166-2
行政区划代码：`US-CA` 针对加利福尼亚州登记处。与 [KYB 登记处搜索
API](https://docs.didit.me/zh/standalone-apis/kyb-registry-search)
上的 `country_code` 格式相同。在企业验证（KYB）工作流中预选登记处国家/地区；在 KYC
工作流中忽略。
example: US-CA
x-readme-id: '1.11'
registration_number:
type: string
maxLength: 100
description: >-
企业在公司登记中的预期注册号。例如，`00445790`。在企业验证（KYB）工作流中预填充登记搜索的注册号字段；若同时提供了
`company_name`，登记查询将结合这两个标识符。在 KYC 工作流中忽略。
example: '00445790'
x-readme-id: '1.12'
x-readme-id: '0.5'
portrait_image:
type: string
format: byte
description: >-
终端用户人脸的 Base64 编码肖像图像（最大 2MB；JPEG、PNG、WebP 或
TIFF）。当工作流是启用了人脸比对的 `Biometric Authentication`
工作流，或人脸比对在身份证件验证（OCR）之前运行的任何图谱工作流时，用作与活体采集进行比对的参考图像。当
`vendor_data` 用户已有存储的人脸图像时为可选：Didit
会按以下优先级自动复用：已通过的活体人脸、电子护照芯片照片、身份证件肖像、手动录入的个人资料人脸（仅复用来自已通过会话的人脸或您自行录入的人脸）。提供时，`portrait_image`
始终优先于存储的人脸。如果省略且不存在已存储的人脸（或未发送 `vendor_data`），会话创建将失败并返回
`400`。对于其他工作流类型将被忽略。
example: >-
iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=
x-readme-id: '0.6'
sandbox_scenario:
type: string
description: >-
仅限沙盒的场景 slug。仅在 API
密钥属于沙盒模式应用时被接受；在生产环境应用上会被拒绝。设置后，创建流程会将场景绑定的魔法值展开到会话的输入字段（contact_details、expected_details）中，以便模拟的供应商通过真实的工作流管道复现该场景的结果。请参阅
GET /v1/sandbox/scenarios/
中的场景目录或[沙盒与测试数据](/zh/integration/sandbox-testing)。只要会话仍处于
`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`
模拟已验证的钱包。所有目录中的钱包均可在沙盒中进行测试，包括生产环境应用中不可用的方案。模拟的尝试不会被计费。
example: decline_document_expired
sign:
type: object
description: >-
此会话的电子签名输入。`documents`
为待签署的文件，适用于电子签名步骤从会话中获取文件（`signature_documents_source` 为
`session` 或 `both`）的工作流：总计最多 20 个文件和 50 MB。`field_values`
用于填充工作流文件和会话文件中 `prefill` 为 `api.` 的字段。针对相同的
`workflow_id` 和 `vendor_data` 再次创建会话将返回待处理的会话；如果该调用发送了
`sign`，其文件、字段和值必须与首次调用完全一致，若有任何不同，将返回 `400` 以及 `{"sign":
"signature_document_changed"}`。请参阅
[电子签名文件](/zh/sessions-api/create-session#电子签名文档)。
properties:
documents:
type: array
minItems: 1
maxItems: 20
items:
$ref: '#/components/schemas/SessionSignDocument'
field_values:
type: object
description: >-
以每个 `api.` 预填充源的 `` 为键的值：`text` 和 `data` 字段为 1
到 500 个字符的字符串，`checkbox` 为布尔值。若键未被任何字段使用则返回 `400` 及
`field_value_unknown`，若必填字段缺少值则返回
`field_value_missing`，若值未通过字段验证则返回
`field_value_invalid`。
additionalProperties:
oneOf:
- type: string
minLength: 1
maxLength: 500
- type: boolean
example:
credit_limit: 3,000 EUR
user_state:
type: string
maxLength: 16
description: >-
此人的居住地（已知时）：ISO 3166-2
行政区划代码（`US-IL`、`ES-M`）或美国州代码或名称（`IL`、`Illinois`）。法律要求明确生物识别同意的州（伊利诺伊州、得克萨斯州、科罗拉多州）会使验证流程在捕获人脸之前征求同意，触发器为
`declared_state`。无法识别的值将返回
`400`。请参阅[生物识别同意](/zh/getting-started/biometric-consent)。
example: US-IL
biometric_consent:
type: object
description: >-
您已向该人员收集的显式生物识别同意。这满足了要求，因此验证流程不会再次询问，决策会将其记录为 `status:
"given"`，触发器为
`customer_collected`。该人员在流程中已给出的回答绝不会被替换。请参阅[生物识别同意](/zh/getting-started/biometric-consent)。
required:
- given_at
- text_version
properties:
given_at:
type: string
format: date-time
description: 当事人给出明确生物识别同意的时间（ISO 8601）。不能是未来的时间。
text_version:
type: string
maxLength: 64
description: 该人员接受的同意文本在您自身记录中的版本 ID。
example:
workflow_id: 11111111-2222-3333-4444-555555555555
vendor_data: user-123
callback: https://example.com/verification/callback
callback_method: both
metadata:
user_type: premium
account_id: ABC123
language: en
contact_details:
email: john.doe@example.com
send_notification_emails: true
email_lang: en
phone: '+14155552671'
expected_details:
first_name: John
last_name: Doe
date_of_birth: '1990-05-15'
id_country: USA
expected_document_types:
- P
- ID
examples:
Create KYC session:
summary: 用户验证（KYC）会话的完整成功路径 payload
description: >-
使用了所有通常设置的字段的真实创建调用：工作流选择、供应商关联、回调路由、元数据、语言环境、联系方式预填以及预期的用户详情。可直接复制并粘贴到上方的
cURL 示例中。
value:
workflow_id: 11111111-2222-3333-4444-555555555555
vendor_data: user-123
callback: https://example.com/verification/callback
callback_method: both
metadata:
user_type: premium
account_id: ABC123
language: en
contact_details:
email: john.doe@example.com
send_notification_emails: true
email_lang: en
phone: '+14155552671'
expected_details:
first_name: John
last_name: Doe
date_of_birth: '1990-05-15'
nationality: USA
id_country: USA
expected_document_types:
- P
- ID
Create KYB session:
summary: 企业验证（KYB）会话的正常流程 payload
description: >-
数据结构与 KYC 调用相同，`workflow_id` 决定了会话为 KYB。`vendor_data`
通常引用您系统中的公司，`contact_details.email`
指向将完成该流程的法定代表人。`expected_details`
接收企业字段（`company_name`、`registry_country`、`registration_number`），这些字段会预填充公司登记搜索；个人级字段和
`contact_details.phone` 在 KYB 工作流中会被忽略。
value:
workflow_id: 33333333-4444-5555-6666-777777777777
vendor_data: company-acme-001
callback: https://example.com/kyb/callback
callback_method: both
metadata:
tier: enterprise
company_id: ACME-001
expected_details:
company_name: Tesco PLC
registry_country: GB
registration_number: '00445790'
language: en
contact_details:
email: legal-rep@acme.example.com
send_notification_emails: true
email_lang: en
responses:
'201':
description: >-
会话已创建（如果工作流最新发布的版本上已存在具有相同 `vendor_data`
的未完成会话，则直接返回）。响应为序列化的会话，包括用于将用户重定向至托管验证页面的 `url`。
content:
application/json:
schema:
type: object
required:
- session_id
- session_number
- session_token
- url
- vendor_data
- metadata
- status
- workflow_id
- workflow_version
- callback
properties:
session_id:
type: string
format: uuid
description: >-
验证会话的唯一标识符。调用 `GET /v3/session/{sessionId}/decision/` 时使用此
ID。
example: 11111111-2222-3333-4444-555555555555
session_number:
type: integer
description: 在您的应用内分配给该会话的便于人类阅读的序号。便于客服支持和在仪表板中使用。
example: 43762
session_token:
type: string
description: >-
12 个字符的 URL 安全 token，用于授权终端用户通过 `url`
访问托管验证流程。在会话过期前一直有效。请将其视为机密信息 — 任何持有该 token
的人都可以打开此会话的验证流程。
example: 3FaJ9wLqX2Mz
url:
type: string
format: uri
description: >-
用于重定向终端用户的托管验证 URL。该 URL 内嵌了
`session_token`，若已配置，还会使用您的白标域名。当请求包含 `language` 时，URL
会包含语言路径段：`https://verify.didit.me/{language}/session/{session_token}`（例如
`/es/session/...`）；若未提供 `language`，则省略该路径段。
example: https://verify.didit.me/session/3FaJ9wLqX2Mz
vendor_data:
type: string
nullable: true
description: 您在请求中传递的标识符，用于将该会话链接到您自身系统中的用户或企业。逐字回传。未提供时为 null。
example: user-123
metadata:
description: >-
在创建会话时随其一起存储的任意 JSON payload。原样回显：无论您发送的是何种 JSON
值（对象、字符串、数字、数组），都将按原样返回，但建议使用 JSON
对象。不对终端用户显示。始终在响应中提供；创建时未提供则为 `null`。
example:
user_type: premium
account_id: ABC123
tags:
type: array
items:
type: string
description: 会话中的标签，按名称列出。
example:
- VIP
- ONBOARDING Q4
status:
type: string
enum:
- Not Started
- In Progress
- Approved
- Declined
- In Review
- Expired
- Abandoned
- Kyc Expired
- Resubmitted
- Awaiting User
description: >-
会话的当前状态。新创建的会话返回 `Not Started`。如果工作流最新发布的版本上已存在具有相同
`vendor_data` 的未完成会话，则返回的状态反映该现有会话。
example: Not Started
callback:
type: string
format: uri
nullable: true
description: >-
用户完成流程后被重定向到的最终重定向 URL。Didit 会在此 URL 后追加
`?verificationSessionId={session_id}&status={status}`。若请求中未提供，则回退到工作流配置的回调
URL；若两者均未设置则为 `null`。当应用配置了允许的域名且此 URL 是域名列表之外的 Web URL
时（例如在更改列表前设置的工作流默认值），托管流程不会将用户重定向至该 URL。
example: https://example.com/verification/callback
workflow_id:
type: string
format: uuid
description: >-
此会话运行所在工作流的稳定标识符。始终为工作流的稳定分组标识符。即使您在请求中引用了特定工作流版本的
UUID（向后兼容的查找方式），响应中也会包含稳定的
`workflow_id`。使用它可将会话与您在控制台中配置的工作流进行关联。
example: 11111111-2222-3333-4444-555555555555
workflow_version:
type: integer
description: >-
会话在创建时所绑定的已发布工作流版本号。在创建会话时，Didit 会将 `workflow_id`
解析为该工作流最新发布的版本，即使之后重新发布工作流，该会话也会继续运行该版本。
example: 3
examples:
KYC session:
summary: KYC 会话已创建
value:
session_id: 11111111-2222-3333-4444-555555555555
session_number: 43762
session_token: 3FaJ9wLqX2Mz
url: https://verify.didit.me/en/session/3FaJ9wLqX2Mz
vendor_data: user-123
metadata:
user_type: premium
account_id: ABC123
status: Not Started
workflow_id: 11111111-2222-3333-4444-555555555555
workflow_version: 3
callback: https://example.com/verification/callback
KYB session:
summary: KYB 会话已创建
value:
session_id: 22222222-3333-4444-5555-666666666666
session_number: 43763
session_token: Yk7pQ2vN8aBc
url: https://verify.didit.me/en/session/Yk7pQ2vN8aBc
vendor_data: company-acme-001
metadata:
tier: enterprise
status: Not Started
workflow_id: 33333333-4444-5555-6666-777777777777
workflow_version: 1
callback: https://example.com/kyb/callback
'400':
description: >-
错误请求：payload 未通过验证（缺失或未知的 `workflow_id`、无效的 `language`、已列入黑名单的
`vendor_data`、格式错误的 `portrait_image`、缺少 `country`/`poa_country` 的
`address`、无效的 `sandbox_scenario`，或者工作流的电子签名步骤拒绝的 `sign` 证件、字段或值，例如
`signature_document_not_supported`、`signature_document_conversion_failed`、`field_anchor_not_found`
或 `field_value_missing` 等），或者您的组织没有足够的额度来启动会话。
响应体是一个以违规字段名为键的对象（对于非字段错误，键为
`detail`）。输入验证失败（例如缺少必填字段、无效语言、人像图片过大）对应的值为**字符串数组**；创建会话期间检测到的失败（未知的
`workflow_id`、已列入黑名单的
`vendor_data`、人脸比对工作流无可用的参考人脸）对应的值为**纯字符串**。请处理这两种格式。
content:
application/json:
schema:
type: object
additionalProperties: true
properties:
detail:
type: string
description: 非字段错误的便于人类阅读的错误消息（例如额度不足）。字段级失败则改用字段名作为键，对应的值为字符串或字符串数组。
example: >-
You don't have enough credits to perform this request.
Please top up at https://business.didit.me
examples:
Missing workflow_id:
summary: 遗漏了必填字段（字符串数组格式）
value:
workflow_id:
- This field is required.
Invalid workflow_id:
summary: 未知的 workflow_id（纯字符串格式）
value:
workflow_id: Invalid workflow_id.
Insufficient credits:
summary: 组织额度已用尽
value:
detail: >-
You don't have enough credits to perform this request.
Please top up at https://business.didit.me
Blocklisted vendor_data:
summary: vendor_data 已被列入黑名单
value:
vendor_data: >-
This user or business has been blocked and cannot create
new verification sessions.
Portrait image too large:
summary: portrait_image 未通过大小验证
value:
portrait_image:
- Image size exceeds 2MB.
No stored face for vendor_data:
summary: 不带 portrait_image 且没有为 vendor_data 用户存储人脸的人脸比对工作流
value:
portrait_image: >-
No stored face image was found for this user. Send a
portrait_image, or complete an approved verification with
face liveness or an ID document for this vendor_data
first.
Portrait image required without vendor_data:
summary: 不带 portrait_image 且不带 vendor_data 的人脸比对工作流
value:
portrait_image: >-
A portrait image is required to perform face match for
this workflow. Send a portrait_image, or provide the
vendor_data of a user with a previously stored face image
to reuse it.
'403':
description: >-
身份验证或授权失败。错误、已撤销或已过期的密钥将返回 `401`。当缺少 `x-api-key` 请求头，或者 API
密钥有效但客户端无权在此应用中创建会话（例如该 API 密钥属于其他组织）时，该 endpoint 将返回
`403`。这些失败均共享响应体 `{"detail": "You do not have permission to perform
this action."}`。请检查 `x-api-key` 请求头是否存在且属于目标应用，如有需要，可通过 [Auth
API](/zh/auth-api/get-credentials) 重新获取应用 API 密钥，然后重试。
**已删除的应用：**在应用被删除后的几分钟内，使用其 API 密钥发出的请求可能会返回 `{"detail": "This
application was deleted.", "code":
"application_deleted"}`。请勿重试：该应用及其 API
密钥已不复存在。几分钟后，该密钥将像其他无效密钥一样被拒绝。
content:
application/json:
schema:
type: object
properties:
detail:
type: string
example: You do not have permission to perform this action.
code:
type: string
description: 机器可读的原因，仅在某些失败情况下出现。`application_deleted`：API 密钥属于已被删除的应用。
example: application_deleted
required:
- detail
examples:
Missing or invalid API key:
summary: 缺少 `x-api-key` 请求头或 API 密钥无效
value:
detail: You do not have permission to perform this action.
No permission:
summary: 客户端无法创建会话
value:
detail: You do not have permission to perform this action.
Application deleted:
summary: 已删除应用的 API 密钥
value:
detail: This application was deleted.
code: application_deleted
'429':
description: >-
超出速率限制：同一 API 密钥 / IP 在 60 秒时间窗口内发起的会话创建请求超过 600 次。请检查 `Retry-After`
并在重试前进行退避等待。
**注意：**源代码中还在 `PAID_SESSION_RATE_LIMIT=600` 之外定义了 10 次调用/分钟的
`FREE_SESSION_RATE_LIMIT`（`sessions/serializers/session.py`），但该免费额度上限**不适用于此
V3 endpoint**：无论何种套餐，速率限制中间件均执行 600 次/分钟的
`SESSION_CREATE_RATE_LIMIT`。600 次/分钟是您在此处可能触发的唯一限制。
headers:
Retry-After:
description: 调用方在重试请求前必须等待的秒数。
schema:
type: integer
minimum: 1
example: 42
X-RateLimit-Limit:
description: 当前 60 秒时间窗口内针对已触发限制所允许的最大请求数（创建会话为 600）。在沙盒配额变体中不存在。
schema:
type: integer
example: 600
X-RateLimit-Remaining:
description: 对于已超出限制的速率限制，在当前窗口内仍允许的请求次数。在沙盒配额变体中不存在此项。
schema:
type: integer
minimum: 0
example: 0
X-RateLimit-Reset:
description: 当前速率限制窗口重置时的 UTC 纪元秒数。沙盒配额变体中不存在此项。
schema:
type: integer
minimum: 0
example: 1747497600
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: 超出速率限制的便于人类阅读的说明。使用此消息可区分触发了三项限制中的哪一项。
example: >-
Session creation rate limit exceeded. You can make up to
600 requests per minute.
examples:
Session-create limit:
summary: 每分钟创建会话请求超过 600 次
value:
detail: >-
Session creation rate limit exceeded. You can make up to
600 requests per minute.
Sandbox session quota:
summary: 沙盒应用在 24 小时内超过 500 次会话
value:
detail: >-
Sandbox session quota exceeded (500 sessions per 24h).
Wait for the window to reset. Expected available in 3600
seconds.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "11111111-2222-3333-4444-555555555555",
"vendor_data": "user-123",
"callback": "https://example.com/verification/callback",
"callback_method": "both",
"metadata": {"user_type": "premium", "account_id": "ABC123"},
"language": "en",
"contact_details": {
"email": "john.doe@example.com",
"send_notification_emails": true,
"email_lang": "en",
"phone": "+14155552671"
},
"expected_details": {
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"id_country": "USA",
"expected_document_types": ["P", "ID"]
}
}'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.sessions.create(
workflow_id="11111111-2222-3333-4444-555555555555",
vendor_data="user-123",
callback="https://example.com/verification/callback",
callback_method="both",
metadata={"user_type": "premium", "account_id": "ABC123"},
language="en",
contact_details={
"email": "john.doe@example.com",
"send_notification_emails": True,
"email_lang": "en",
"phone": "+14155552671",
},
expected_details={
"first_name": "John",
"last_name": "Doe",
"date_of_birth": "1990-05-15",
"nationality": "USA",
"id_country": "USA",
"expected_document_types": ["P", "ID"],
},
)
print(result)
- lang: javascript
label: Node.js
source: |-
import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.sessions.create({
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
},
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Create(ctx, didit.SessionsCreateParams{\n\tWorkflowID: \"11111111-2222-3333-4444-555555555555\",\n\tVendorData: didit.String(\"user-123\"),\n\tCallback: didit.String(\"https://example.com/verification/callback\"),\n\tCallbackMethod: didit.Some(didit.SessionsCreateParamsCallbackMethod(\"both\")),\n\tMetadata: didit.Some[any](map[string]any{\"user_type\": \"premium\", \"account_id\": \"ABC123\"}),\n\tLanguage: didit.Some(didit.SessionsCreateParamsLanguage(\"en\")),\n\tContactDetails: didit.Some(didit.SessionsCreateParamsContactDetails{\n\t\tEmail: didit.String(\"john.doe@example.com\"),\n\t\tSendNotificationEmails: didit.Bool(true),\n\t\tEmailLang: didit.Some(didit.SessionsCreateParamsContactDetailsEmailLang(\"en\")),\n\t\tPhone: didit.String(\"+14155552671\"),\n\t}),\n\tExpectedDetails: didit.Some(didit.SessionsCreateParamsExpectedDetails{\n\t\tFirstName: didit.String(\"John\"),\n\t\tLastName: didit.String(\"Doe\"),\n\t\tDateOfBirth: didit.String(\"1990-05-15\"),\n\t\tNationality: didit.String(\"USA\"),\n\t\tIDCountry: didit.String(\"USA\"),\n\t\tExpectedDocumentTypes: didit.Some([]didit.SessionsCreateParamsExpectedDetailsExpectedDocumentTypes{\"P\", \"ID\"}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: |-
import java.time.LocalDate;
import java.util.List;
import java.util.Map;
import me.didit.Didit;
import me.didit.types.SessionsCreateParams;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result = client.sessions().create(SessionsCreateParams.builder()
.workflowId("11111111-2222-3333-4444-555555555555")
.vendorData("user-123")
.callback("https://example.com/verification/callback")
.callbackMethod(SessionsCreateParams.CallbackMethod.of("both"))
.metadata(Map.of("user_type", "premium", "account_id", "ABC123"))
.language(SessionsCreateParams.Language.of("en"))
.contactDetails(SessionsCreateParams.ContactDetails.builder()
.email("john.doe@example.com")
.sendNotificationEmails(true)
.emailLang(SessionsCreateParams.ContactDetails.EmailLang.of("en"))
.phone("+14155552671")
.build())
.expectedDetails(SessionsCreateParams.ExpectedDetails.builder()
.firstName("John")
.lastName("Doe")
.dateOfBirth(LocalDate.parse("1990-05-15"))
.nationality("USA")
.idCountry("USA")
.expectedDocumentTypes(List.of(SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("P"), SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of("ID")))
.build())
.build());
System.out.println(result);
- lang: php
label: PHP
source: |-
sessions->create([
'workflow_id' => '11111111-2222-3333-4444-555555555555',
'vendor_data' => 'user-123',
'callback' => 'https://example.com/verification/callback',
'callback_method' => 'both',
'metadata' => ['user_type' => 'premium', 'account_id' => 'ABC123'],
'language' => 'en',
'contact_details' => [
'email' => 'john.doe@example.com',
'send_notification_emails' => true,
'email_lang' => 'en',
'phone' => '+14155552671',
],
'expected_details' => [
'first_name' => 'John',
'last_name' => 'Doe',
'date_of_birth' => '1990-05-15',
'nationality' => 'USA',
'id_country' => 'USA',
'expected_document_types' => ['P', 'ID'],
],
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.sessions.create(
workflow_id: "11111111-2222-3333-4444-555555555555",
vendor_data: "user-123",
callback: "https://example.com/verification/callback",
callback_method: "both",
metadata: { user_type: "premium", account_id: "ABC123" },
language: "en",
contact_details: {
email: "john.doe@example.com",
send_notification_emails: true,
email_lang: "en",
phone: "+14155552671",
},
expected_details: {
first_name: "John",
last_name: "Doe",
date_of_birth: "1990-05-15",
nationality: "USA",
id_country: "USA",
expected_document_types: ["P", "ID"],
}
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Collections.Generic;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.Sessions.CreateAsync(new
SessionsCreateParams
{
WorkflowId = "11111111-2222-3333-4444-555555555555",
VendorData = "user-123",
Callback = "https://example.com/verification/callback",
CallbackMethod = new SessionsCreateParamsCallbackMethod("both"),
Metadata = new Dictionary { ["user_type"] = "premium", ["account_id"] = "ABC123" },
Language = new SessionsCreateParamsLanguage("en"),
ContactDetails = new SessionsCreateParamsContactDetails
{
Email = "john.doe@example.com",
SendNotificationEmails = true,
EmailLang = new SessionsCreateParamsContactDetailsEmailLang("en"),
Phone = "+14155552671",
},
ExpectedDetails = new SessionsCreateParamsExpectedDetails
{
FirstName = "John",
LastName = "Doe",
DateOfBirth = "1990-05-15",
Nationality = "USA",
IdCountry = "USA",
ExpectedDocumentTypes = new SessionsCreateParamsExpectedDetailsExpectedDocumentTypes[] { "P", "ID" },
},
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
schemas:
SessionSignDocument:
type: object
required:
- file_name
- content_base64
properties:
title:
type: string
minLength: 1
maxLength: 255
description: 向签署人显示的标题。默认为 `file_name`。
file_name:
type: string
minLength: 1
maxLength: 255
description: 文件名，以 `.pdf` 或 `.docx` 结尾。
content_base64:
type: string
format: byte
description: >-
经 base64 编码的文件。PDF 文件大小上限为 20 MB 且最多 100 页，不得包含密码、脚本或附加文件。Word
文件（`.docx`）大小上限为 20 MB，在请求执行期间转换为 PDF，耗时最多 25 秒；转换后的 PDF
适用相同的限制。每次会话最多 5 个 Word 文件。包含宏、修订记录、外部内容链接或嵌入式对象的 Word 文件将被拒绝，错误码为
`signature_document_not_supported`；无法转换的文件将返回
`signature_document_conversion_failed`，均附带 `reason`。
fields:
type: array
description: >-
放置在此文档上的可选字段，最多 200 个。页码和位置基于 PDF（Word 文件则基于转换后的
PDF）。若未设置字段，签署人阅读文档并同意。
items:
$ref: '#/components/schemas/SignatureField'
maxItems: 200
SignatureField:
type: object
description: >-
放置在会话证件上的字段：由哪个签署人填写、如何填写以及在何处填写。提供位置（`page`、`x`、`y`、`width` 和
`height`）或 `anchor`。位置是页面显示时以页面左上角为起点的比例，四舍五入保留 4
位小数，且字段必须完全位于页面内部。一个证件最多支持 200 个字段，一个签署人最多支持 500
个字段，且在该证件上拥有字段的每个角色都需要一个 `signature` 或 `initials`
字段。参见[证件上的字段](/zh/core-technology/electronic-signature/overview#文档上的字段)。
required:
- key
- type
properties:
key:
type: string
pattern: ^[a-z][a-z0-9_]{0,63}$
description: 在结果中以及 `sign.field_values` 中命名该字段。在证件内唯一。
type:
type: string
enum:
- signature
- initials
- full_name
- date_signed
- text
- checkbox
- email
- data
description: >-
该字段包含的内容。签署人应用其采用的 `signature` 和 `initials`，输入 `text`，勾选
`checkbox`，并在会话没有已验证邮箱时输入 `email`。Didit 会自动填充
`full_name`（已核验的姓名）、`date_signed`（签署日期，采用签署人所在时区）、`data`（来自
`prefill`）和已验证的 `email`，并以只读方式显示它们。没有日期选择器类型：请使用 `text`。
role:
type: string
enum:
- verified_person
- legal_representative
- key_people
description: 填写该字段的主体，包含 `signature_signer` 的值。一个步骤仅填写并标记属于其自身签署人的字段。默认为该步骤的签署人。
page:
type: integer
minimum: 1
description: 页码，从 1 到证件的总页数。对于 Word 证件，指转换后 PDF 的页码。
x:
type: number
minimum: 0
maximum: 1
description: 左边缘，占页面宽度的比例。
'y':
type: number
minimum: 0
maximum: 1
description: 顶部边缘，以页面高度的比例表示。
width:
type: number
minimum: 0.02
maximum: 1
description: 宽度，占页面宽度的比例。签名宽度至少为 `0.12`。
height:
type: number
minimum: 0.012
maximum: 1
description: 高度，表示为页面高度的比例。签名的最小高度为 `0.035`。
anchor:
$ref: '#/components/schemas/SignatureFieldAnchor'
required:
type: boolean
description: >-
`signature` and `initials` are required unless you set `false`.
`full_name`, `date_signed` and `data` are always required. The
signer can't finish a document until its required fields have a
value, and a required checkbox must be ticked.
label:
type: string
minLength: 1
maxLength: 80
description: 向签署人展示并显示在结果中。默认取自类型。
placeholder:
type: string
nullable: true
maxLength: 80
description: 仅支持 `text` 和 `email`。
validation:
$ref: '#/components/schemas/SignatureFieldValidation'
prefill:
type: string
nullable: true
description: >-
值的来源：`identity.full_name`、`identity.first_name`、`identity.last_name`、`identity.date_of_birth`（`DD/MM/YYYY`）、`identity.nationality`、`identity.document_number`、`identity.document_type`、`identity.issuing_country`、`identity.address`、`contact.email`、`contact.phone`、`company.name`、`company.registration_number`、`company.address`、`company.country`（KYB）、`session.vendor_data`、`metadata.`（会话
`metadata` 的键）或 `api.`（`sign.field_values` 的键）。对 `data`
为必填。`full_name` 始终使用 `identity.full_name`，`email` 使用
`contact.email`。当签署人开始签署时，`data`、`full_name` 和已验证的 `email` 字段的值将被固定。
editable_when_prefilled:
type: boolean
default: false
description: 仅支持 `text` 和 `email`：签署人可以修改预填值。
checked_by_default:
type: boolean
default: false
description: 仅限 `checkbox`：该框默认勾选。
date_format:
type: string
enum:
- DD/MM/YYYY
- MM/DD/YYYY
- YYYY-MM-DD
- D MMMM YYYY
default: DD/MM/YYYY
description: 仅限 `date_signed`。
SignatureFieldAnchor:
type: object
description: >-
根据文档中的一段文本放置字段，而不是使用位置坐标。Didit 不会从 PDF
中移除该文本，因此请将其设置为与页面背景相同的颜色。未找到该文本时，调用将返回 `400` 并附带
`field_anchor_not_found`。请参阅[通过定位文本放置字段](/zh/sessions-api/create-session#按锚点文本放置字段)。
required:
- text
properties:
text:
type: string
minLength: 1
maxLength: 64
description: 在证件中搜索的文本。对于 Word 文件，指在转换后的 PDF 中搜索。
occurrence:
type: string
enum:
- first
- all
default: first
description: '`all` 为每个匹配项放置一个字段；首个匹配项之后的键将附加 `_2`、`_3` 等后缀。'
offset_x:
type: number
description: 添加到文本左边缘，表示为页面宽度的比例。
offset_y:
type: number
description: 添加到文本上边缘，表示为页面高度的比例。
width:
type: number
minimum: 0.02
maximum: 1
description: 字段宽度，占页面宽度的比例。
height:
type: number
minimum: 0.012
maximum: 1
description: 字段高度，表示为页面高度的比例。
SignatureFieldValidation:
type: object
nullable: true
description: '`text` 字段值的规则。控制台预览、签署流程和 API 应用相同的规则。'
properties:
kind:
type: string
enum:
- any
- letters
- number
- email
- pattern
description: >-
`letters`：任何文字系统中的字母、空格、连字符和撇号。`number`：数字以及可选的小数分隔符。`pattern`：值必须与
`pattern` 匹配。
min_length:
type: integer
minimum: 0
maximum: 500
description: 从 `0` 到 `max_length`。
max_length:
type: integer
minimum: 1
maximum: 500
default: 120
pattern:
type: string
nullable: true
minLength: 1
maxLength: 200
description: >-
当 `kind: "pattern"`
时必填。整个值必须匹配的正则表达式。不支持环视（lookarounds）和反向引用（backreferences）。
message:
type: string
nullable: true
maxLength: 120
description: 向签署人展示，替代默认错误信息。
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
您的应用 API 密钥，可在 Business Console 的“开发者 -> API
密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于
IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP
列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF
URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅
https://docs.didit.me/console/api-keys。
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.