> ## 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 > 通过 POST /v3/session/import-shared/ 凭合作方共享令牌导入 KYC 或 KYB 会话。Didit 提供可复用身份，无需重新验证，按次计费。 导入共享会话提示 将提示词复制到剪贴板 \

\`Import a verification session shared by a partner application (Reusable KYC / KYB).

Endpoint:
POST https://verification.didit.me/v3/session/import-shared/

Authentication:
Use the x-api-key header with the receiving application's Didit API key. Privilege: write:sessions.

Request body:
\- share_token (string, required) — JWT minted by the partner via POST /v3/session/{id}/share/. Didit decodes it, reads the embedded session_kind, and clones the matching kind.
\- workflow_id (string, UUID, required) — Workflow in YOUR application to attach the imported session to. KYC token → pass a KYC workflow_id. KYB token → pass a KYB workflow_id.
\- vendor_data (string, optional) — Your stable identifier for the entity. Auto-creates a User or Business entity if it does not already exist.
\- trust_review (boolean, optional, default false) — false → imported session lands in "In Review" so your team can re-review. true → imported session preserves the original status (e.g. "Approved"). Use true only when you fully trust the sharing partner's decision.

curl example:
curl -X POST https://verification.didit.me/v3/session/import-shared/ \
-H "x-api-key: " \
-H "Content-Type: application/json" \
-d '{
"share_token": "",
"workflow_id": "",
"vendor_data": "partner-user-42",
"trust_review": false
}'

Response (201 Created):
\- session_id (UUID) — NEW UUID minted in your application.
\- session_kind ("user" | "business") — same as the original.
\- session_number — fresh sequence in your application.
\- status — original status (if trust_review=true) or "In Review" (if trust_review=false).
\- shared_from_session — pointer to the original session in the source application.
\- vendor_data, workflow_id — what you sent.
\- All cloned feature arrays: KYC tokens clone id_verifications + liveness_checks + face_matches + face + AML + location + POA + phone + email + database_validations + logs; KYB tokens clone registry_checks + key_people_checks + document_verifications + AML + phone + email + location + questionnaire + logs.

Backward compatibility:
Tokens minted before the unified-sharing rollout (no session_kind field) default to "user" when decoded.

Idempotency:
Importing the same share_token twice into the same application is rejected with 403, for user and business sessions alike.

Failure modes:
\- 400 - { "share_token": ["Invalid share token."] } when the token is malformed or was not issued by Didit.
\- 400 - { "share_token": ["Share token has expired."] } when its exp has passed.
\- 400 - { "share_token": ["This token is not valid for this application."] } when the token was issued for another application.
\- 400 - { "share_token": ["Original session does not exist."] } when the shared session was deleted.
\- 403 - { "detail": "This session has already been shared with your application." } when the session was already imported into this application.
\- 404 - { "detail": "Workflow does not exist for this application." } when workflow_id is not a workflow of your application.

When to call:
\- Cross-organization Reusable KYC (bank → fintech, marketplace → payment provider, etc.).
\- Promoting a verified user from your sandbox application to your production application.
\- Group-company sharing across sibling applications.

After import:
\- The new session works like any other session — fetch with GET /v3/session/{session_id}/decision/ (see /sessions-api/retrieve-session) and react to status / data webhooks.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`

\
粘贴到 ## KYC 和 KYB 支持Didit 会解码共享 token，读取其中嵌入的 `session_kind`，并克隆对应类型的会话：- `session_kind: "user"`：克隆用户会话，以及其关联的身份、人脸、活体检测、人脸比对、AML、位置、地址证明、电话、邮箱、数据库核验和日志记录。 - `session_kind: "business"`：克隆企业会话，以及其关联的登记信息核验、关键人员记录、证件、AML 筛查、电话、邮箱、位置、问卷和日志记录。如果该 token 早于统一共享功能上线，且不包含 `session_kind` 字段，Didit 会为了向后兼容而默认使用 `"user"`。## 创建的内容- 在您的应用中创建一个**新会话**，类型与原会话相同，并带有全新的 `session_id`、`session_number` 和 `session_url`。 - 新会话的 `shared_from_session` 字段指向来源应用中的原会话。 - 新会话的状态为原始状态（`trust_review: true`），或为 `IN_REVIEW`（`trust_review: false`）。 - 如果 `vendor_data` 对应的实体（用户或企业）不存在，系统会自动创建该实体。## 示例> [tab] 导入用户验证（KYC）会话 > > ```bash theme={null} > curl -X POST https://verification.didit.me/v3/session/import-shared/ \ > -H "x-api-key: YOUR_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{ > "share_token": "eyJhbGciOiJIUzI1NiJ9...", > "workflow_id": "your-kyc-workflow-id", > "vendor_data": "partner-user-42", > "trust_review": false > }' > ``` > > **响应（201 已创建）：** > > ```json theme={null} > { > "session_id": "new-uuid", > "session_kind": "user", > "shared_from_session": "original-uuid", > "status": "In Review", > "vendor_data": "partner-user-42", > "id_verifications": [...], > "liveness_checks": [...], > "...": "..." > } > ```> [tab] 导入企业验证（KYB）会话 > > ```bash theme={null} > curl -X POST https://verification.didit.me/v3/session/import-shared/ \ > -H "x-api-key: YOUR_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{ > "share_token": "eyJhbGciOiJIUzI1NiJ9...", > "workflow_id": "your-kyb-workflow-id", > "vendor_data": "partner-biz-acme", > "trust_review": true > }' > ``` > > **响应（201 已创建）：** > > ```json theme={null} > { > "session_id": "new-uuid", > "session_kind": "business", > "shared_from_session": "original-uuid", > "status": "Approved", > "vendor_data": "partner-biz-acme", > "registry_checks": [...], > "key_people_checks": [...], > "document_verifications": [...], > "...": "..." > } > ```## `trust_review` 参数| 值 | 效果 | | - | - | | `true` | 导入的会话保留原始状态（例如 `APPROVED`）。当您完全信任共享合作方的决定时使用。 | | `false` | 导入的会话会进入 `IN_REVIEW`，以便您的团队在采取行动前重新审核。对外部合作方而言是安全的默认值。 |## 错误| 状态 | 原因 | | - | - | | `400` | `share_token` 无效、已过期、为其他应用签发，或指向已删除的会话。错误信息位于 `share_token` 键下。 | | `403` | 该会话已导入到您的应用中。 | | `404` | `workflow_id` 不是您应用的工作流。 |## 幂等性对同一应用重复导入同一个 `share_token`，无论是用户会话还是企业会话，都会被拒绝并返回 `403`。## 相关内容- [共享会话](https://docs.didit.me/zh/sessions-api/share-session/share.md) - [可复用 KYC 指南](https://docs.didit.me/zh/core-technology/reusable-kyc/share-kyc-via-api.md) - [会话概览](https://docs.didit.me/zh/sessions-api/overview.md) ## OpenAPI ````yaml zh/openapi-25.json POST /v3/session/import-shared/ 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/import-shared/: post: tags: - Sessions summary: 兑换共享 token，以将验证会话克隆到您的应用中 description: >- 兑换共享 token，以将 KYC 或 KYB 会话克隆到调用应用中并生成全新的 `session_id`。非幂等 — 每个接收方只能兑换一次 token。 operationId: post_v3_session_import_shared requestBody: required: true content: application/json: schema: type: object required: - share_token - trust_review - workflow_id properties: share_token: type: string description: >- 由 [`POST /v3/session/{sessionId}/share/`](/sessions-api/share-session) 签发的 JWT 共享 token。 example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... trust_review: type: boolean description: >- 若为 `true`，克隆的会话将保留源会话的最终 `status`。若为 `false`，则强制置为 `In Review`。 example: false workflow_id: type: string format: uuid description: 调用方应用中工作流的 UUID。跨应用 ID 将被拒绝并返回 `404`。 example: 9f9b1234-aaaa-bbbb-cccc-1234567890ab vendor_data: type: string nullable: true description: 针对克隆会话的 `vendor_data` 的可选覆盖值。 example: user-1 example: share_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... trust_review: false workflow_id: 9f9b1234-aaaa-bbbb-cccc-1234567890ab vendor_data: user-1 responses: '201': description: >- 会话已克隆。响应体是两种类型的 V3 决策 payload，通过 `session_kind` 进行区分：`"user"`（KYC）包含基于列表的功能块，如 `id_verifications`、`liveness_checks`、`aml_screenings`；`"business"`（KYB）包含诸如 `registry_checks` 和 `key_people_checks` 的功能块。两者均包含 `shared_from_session`，即源应用中原始会话的 `session_id`。如果 `trust_review: false`，克隆会话的 `status` 将被强制设为 `In Review`。 content: application/json: schema: $ref: '#/components/schemas/SessionDecision' examples: User session imported: summary: 克隆的 KYC 会话（截断 — 实际为完整的 V3 决策 payload） value: session_id: 11111111-2222-3333-4444-555555555555 session_kind: user shared_from_session: 99999999-8888-7777-6666-555555555555 session_number: 43762 session_url: null status: In Review workflow_id: 9f9b1234-aaaa-bbbb-cccc-1234567890ab vendor_data: user-1 created_at: '2026-05-17T08:42:11Z' expires_at: '2026-05-24T08:42:11Z' Business session imported: summary: 克隆的 KYB 会话（截断 — 实际为完整的 V3 KYB 决策 payload） value: session_id: 22222222-3333-4444-5555-666666666666 session_kind: business shared_from_session: 88888888-7777-6666-5555-444444444444 session_number: 982 session_url: null status: Approved workflow_id: 9f9b1234-aaaa-bbbb-cccc-1234567890ab vendor_data: company-1 '400': description: 验证错误（token 无效、已过期、目标错误，或引用的会话已不存在）。 content: application/json: examples: Invalid Share Token: summary: 无效的 JWT value: share_token: - Invalid share token. Expired Share Token: summary: token 已超过 `exp` value: share_token: - Share token has expired. Wrong audience: summary: token 未绑定到此应用 value: share_token: - This token is not valid for this application. Original missing: summary: 来源会话已被删除 value: share_token: - Original session does not exist. '403': description: 缺少 API 密钥（错误、已撤销或已过期的密钥会收到 `401`），或者该来源会话已被导入到调用方应用中（每个接收方仅可兑换一次）。 content: application/json: examples: Forbidden: summary: 禁止访问 value: detail: You do not have permission to perform this action. Already imported: summary: 来源已导入过一次 value: detail: >- This session has already been shared with your application. '404': description: '`workflow_id` 不属于发起调用的应用。' content: application/json: examples: Workflow not found: summary: 未知工作流 value: detail: Workflow does not exist for this application. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST \ https://verification.didit.me/v3/session/import-shared/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "share_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "trust_review": false, "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab", "vendor_data": "user-1" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.sessions.import_shared( share_token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", trust_review=False, workflow_id="9f9b1234-aaaa-bbbb-cccc-1234567890ab", vendor_data="user-1", ) 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.importShared({ share_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", trust_review: false, workflow_id: "9f9b1234-aaaa-bbbb-cccc-1234567890ab", vendor_data: "user-1", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ImportShared(ctx, didit.SessionsImportSharedParams{\n\tShareToken: \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n\tTrustReview: false,\n\tWorkflowID: \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n\tVendorData: didit.String(\"user-1\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import me.didit.Didit; import me.didit.types.SessionsImportSharedParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.sessions().importShared(SessionsImportSharedParams.builder() .shareToken("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...") .trustReview(false) .workflowId("9f9b1234-aaaa-bbbb-cccc-1234567890ab") .vendorData("user-1") .build()); System.out.println(result); - lang: php label: PHP source: |- sessions->importShared([ 'share_token' => 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...', 'trust_review' => false, 'workflow_id' => '9f9b1234-aaaa-bbbb-cccc-1234567890ab', 'vendor_data' => 'user-1', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.sessions.import_shared( share_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", trust_review: false, workflow_id: "9f9b1234-aaaa-bbbb-cccc-1234567890ab", vendor_data: "user-1" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Sessions.ImportSharedAsync(new SessionsImportSharedParams { ShareToken = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", TrustReview = false, WorkflowId = "9f9b1234-aaaa-bbbb-cccc-1234567890ab", VendorData = "user-1", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: SessionDecision: type: object properties: session_id: type: string format: uuid description: 会话的唯一标识符。 session_kind: type: string enum: - user - business description: >- 指示这是用户验证（KYC）还是企业验证（KYB）会话的鉴别器。当为 `user` 时，KYC 功能数组（`id_verifications`、`nfc_verifications`、`liveness_checks`、`face_matches`、`poa_verifications`、`document_ai_documents`、`database_validations` 等）适用，且企业数组不存在。当为 `business` 时，payload 转为携带 `registry_checks`、`document_verifications`、`key_people_checks` 以及共享数组（`aml_screenings`、`phone_verifications`、`email_verifications`、`ip_analyses`、`questionnaire_responses`）。**当传递 `include=events` 时省略**：事件结构仅存在于用户会话中，因此该变体中去除了此鉴别器。 shared_from_session: type: string format: uuid nullable: true description: >- 对于使用 `POST /v3/session/import-shared/` 克隆的会话：为源应用中原始会话的 `session_id`。对于所有其他会话为 `null`。传入 `include=events` 时省略。 shared_from_session_number: type: integer nullable: true description: 当此会话是从您组织的另一个应用导入时，为源会话的 `session_number`。否则为 `null`。 session_number: type: integer description: 会话编号。 nullable: true session_url: type: string format: uri description: 会话的 URL。 nullable: true status: type: string enum: - Not Started - In Progress - Awaiting User - In Review - Approved - Declined - Resubmitted - Expired - Kyc Expired - Abandoned description: >- 会话的整体生命周期状态，即汇总的工作流结果。终态值为 `Approved`、`Declined`、`In Review`、`Expired`、`Kyc Expired` 和 `Abandoned`；`Not Started`、`In Progress`、`Awaiting User` 和 `Resubmitted` 表示会话仍在工作流流转中。 status_override: type: object nullable: true description: 在审核员手动设置 `status` 时存在。当状态为自动设置时为 `null`。可用于区分人工审核通过与自动通过。 properties: overridden_at: type: string format: date-time nullable: true automatic_status: type: string nullable: true description: 平台自身检查得出的状态。 decision_trace: type: object description: 状态是如何达成的：由谁设置以及触发了哪些警告。 properties: status: type: string description: 会话状态。 decided_by: type: string nullable: true enum: - manual - automatic - investigator - null description: 设置该状态的人员。会话尚未做出决策时为 `null`。 decided_at: type: string format: date-time nullable: true automatic_status: type: string nullable: true description: 平台自身检查得出的结论，在人工决策后该值与 `status` 不同。 terminal_node_id: type: string nullable: true description: 结束会话的工作流状态节点（若有）。 actor: type: object nullable: true description: 负责人工决策的审核员。 properties: user: type: string nullable: true actor_type: type: string nullable: true warning_counts: type: object description: 按 `log_type`（`error`、`warning`、`information`）划分的警告数及 `total`。 additionalProperties: type: integer status_warnings: type: array description: 会将状态设置为 `Declined` 或 `In Review` 的警告。 items: type: object properties: risk: type: string feature: type: string nullable: true node_id: type: string nullable: true log_type: type: string nullable: true check_status: type: string nullable: true source: type: string description: 产生该警告的 payload 列表，例如 `id_verifications`。 short_description: type: string nullable: true linked_records: type: object nullable: true description: 与会话关联的其他记录的摘要。没有可显示内容时以及声明了年龄确认标准的工作流为 `null`。 properties: same_face: type: object nullable: true description: 人脸与本次会话的人脸搜索之一相匹配的其他人员。 properties: count: type: integer best_match: type: object nullable: true properties: session_id: type: string format: uuid nullable: true session_number: type: integer nullable: true vendor_user_id: type: string format: uuid nullable: true similarity_percentage: type: number nullable: true earlier_verifications: type: object nullable: true properties: count: type: integer vendor_user_id: type: string format: uuid nullable: true networks: type: object nullable: true properties: count: type: integer open: type: integer dismissed: type: integer items: type: array items: type: object properties: network_id: type: string format: uuid display_number: type: integer nullable: true name: type: string status: type: string risk_score: type: number nullable: true workflow_id: type: string format: uuid description: 生成此会话的工作流组的稳定标识符。工作流具有多版本，该值标识工作流本身，而非特定版本。 nullable: true features: type: array items: type: string description: 会话的功能。 description: >- 为该会话配置的验证功能列表，显示名称为：`ID_VERIFICATION`、`NFC`、`LIVENESS`、`FACE_MATCH`、`POA`、`PHONE`、`EMAIL_VERIFICATION`、`AML`、`IP_ANALYSIS`、`DATABASE_VALIDATION`、`QUESTIONNAIRE`、`AGE_ESTIMATION`、`FACE_SEARCH`、`GEOLOCATION`（位置验证）（企业验证（KYB）会话使用 KYB 功能集：`KYB_REGISTRY`、`KYB_DOCUMENTS`、`KYB_KEY_PEOPLE`、`AML`、`PHONE`、`EMAIL_VERIFICATION`、`IP_ANALYSIS`、`QUESTIONNAIRE`）。使用 `include=events` 时，每个条目将变为对象 `{feature, node_id}` 而不是纯字符串，并且邮箱功能将被重命名：在事件模式下显示为 `EMAIL`，而不是此处使用的 `EMAIL_VERIFICATION`。 vendor_data: type: string description: 会话的供应商数据。 nullable: true metadata: type: object description: 会话的元数据。 nullable: true expected_details: type: object description: >- 在创建会话时提供的预期详细信息，用于与提取的数据进行交叉比对（KYC）或预填充公司登记搜索（KYB）。原样返回所提供的键；未提供时为 `null`。KYC 会话包含人员字段；企业验证（KYB）会话包含 `company_name`、`registry_country` 和 `registration_number`。 properties: first_name: type: string description: 用户的名。例如 `John`。 last_name: type: string description: 用户的姓。例如 `Doe`。 date_of_birth: type: string format: date description: 用户的出生日期，格式为：YYYY-MM-DD。例如 `1990-05-15`。 gender: type: string nullable: true enum: - M - F default: null description: 用户的性别。必须为 'M'、'F' 或 null。 nationality: type: string description: 代表申请人原籍国家/地区的 ISO 3166-1 alpha-3 国家/地区代码。例如 `USA`。 country: type: string description: >- 代表地址证明文件的国家/地区，或申请人身份证件的国家/地区的 ISO 3166-1 alpha-3 国家/地区代码（可能与国籍不同）。例如 `GBR`。 address: type: string description: >- 人类可读格式的地址，包含尽可能多的详细信息。例如 `123 Main St, San Francisco, CA 94105, USA`。 identification_number: type: string description: 用户的证件号码、个人编号或税号。例如 `123456789`。 ip_address: type: string format: ipv4 description: 会话的预期 IP 地址。如果实际 IP 地址与此值不一致，将记录警告。例如 `192.168.1.100`。 expected_document_types: type: array description: >- 在创建会话时身份证件验证步骤所限定的证件类型。为空/未设置表示无限制。代码：`P`（护照）、`ID`（国民身份证）、`DL`（驾照）、`RP`（居留许可）、`HIC`（健康保险卡）、`TC`（税卡）、`SSC`（社会保障卡）。 items: type: string enum: - P - ID - DL - RP - HIC - TC - SSC id_country: type: string nullable: true description: 创建时受限的预期身份证件签发国家/地区（ISO 3166-1 alpha-3）。 example: ESP poa_country: type: string nullable: true description: 创建时受限的预期地址证明文件国家/地区（ISO 3166-1 alpha-3）。 example: ESP company_name: type: string description: 企业的预期法定名称。仅适用于企业验证（KYB）会话。 registry_country: type: string description: >- 预期登记国家/地区，格式为 `XX` 或 `XX-YY`（ISO 3166-1 alpha-2，针对州级登记可选附带 ISO 3166-2 细分代码，例如 `US-CA`）。仅适用于企业验证（KYB）会话。 registration_number: type: string description: 预期的公司注册号。仅限企业（KYB）会话。 nullable: true contact_details: type: object description: 创建会话时提供的联系方式详情（用于通知邮件、预填的电话/邮箱验证以及沟通语言）。当既未提供邮箱也未提供电话号码时为 `null`。 properties: email: type: string description: >- 用户的邮箱地址（例如 "john.doe@example.com"），将在邮箱验证步骤中使用。如果未提供，用户必须在验证流程中自行提供。 email_lang: type: string description: 邮件通知的语言代码（ISO 639-1）。控制所有邮件通信的语言（例如 "en"、"es"、"fr"）。 send_notification_emails: type: boolean default: false description: >- 若为 true 且提供了邮箱，Didit 会在创建用户验证（KYC）或企业验证（KYB）会话时异步发送初始的“验证您的身份”邮件。对于需要人工审核的会话，Didit 还会向提供的邮箱地址发送验证状态通知。 phone: type: string nullable: true description: >- 用户的电话号码（E.164 格式，若有，例如 +14155552671）。如果会话创建时仅提供了邮箱，则为 `null`。注意：此字段返回会话创建时提供的原始电话号码。如果该号码无效，可能不是 E.164 格式。 nullable: true callback: type: string format: uri description: 会话的回调 URL。 nullable: true id_verifications: type: array nullable: true description: >- **身份证件验证 (OCR) 报告数组**，由工作流图谱中的证件步骤生成。始终为 JSON 数组 — 如果您的工作流可以运行多个证件核查（例如主要核查加上升级核查），请读取 `id_verifications[0]` 并进行遍历。在至少有一个证件步骤生成数据之前为 `null`。每一项均为完整报告，包含 `node_id`、功能级别 `status`、提取的证件字段、图像 URL、质量评分、MRZ、地址解析、跨会话匹配项以及 `warnings[]`。 items: type: object description: >- 单个身份证件验证报告：单个身份证件验证步骤的完整报告。`verification_method` 说明生成该报告所使用的三种方式之一（证件采集、非证件查询或钱包登录），并相应填充特定方式的证据块。 properties: node_id: type: string description: 生成此报告的 OCR 步骤的工作流图谱节点 ID。 verification_method: type: string enum: - document - id_lookup - wallet description: >- 生成此报告的身份证件验证方法。`document` - 用户拍摄了实体证件（默认值，也是在其他方法存在之前创建的每个会话的值）。`id_lookup` - 用户输入其国民身份证号码，并通过该国家/地区的政府登记处或其他权威数据源进行核验（`id_lookup.source` 指明具体数据源）。`wallet` - 用户使用政府或银行数字身份登录。 assurance: type: string enum: - documentary - data_match - cryptographic description: >- 基于 `verification_method` 推导出的保证等级：`documentary` 表示已采集并核查证件，`data_match` 表示详情与所查询数据源中的记录相匹配，`cryptographic` 表示属性由身份提供商完成认证并签名。 wallet_provider: type: string nullable: true description: >- 当 `verification_method` 为 `wallet` 时的目录钱包 ID（`mitid`、`bankid_se`、`itsme` 等）。否则为 `null`。 fallback_from: type: object nullable: true description: >- 非证件方式未能完成证件验证步骤的原因。在查询或钱包登录失败时设置：若该国家/地区的回退开关为 `fallback_to_document`，则记录在用户继续进行的证件验证上（`action` 为 `fallback_to_document`）；若为 `decline`，则记录在已拒绝报告上。其他情况下为 `null`。 properties: method: type: string enum: - id_lookup - wallet description: 失败的方法。 reason: type: string description: >- 导致其终止的结果，例如 `no_match`、`provider_error`、`cancelled`、`timeout`。 action: type: string enum: - fallback_to_document - decline description: 所执行的已配置操作：`fallback_to_document` 或 `decline`。 id_lookup: type: object nullable: true description: 公司登记凭据。仅在 `verification_method` 为 `id_lookup` 时存在；否则为 `null`。 properties: source: type: string description: >- 所查询数据源面向客户的名称，例如 `Department of Home Affairs`（政府登记库）或 `UK credit bureau and financial services records`（非政府登记库）。这是该查询唯一的来源声明；请勿假定为政府来源。 checked_at: type: string format: date-time nullable: true description: 登记机关响应的时间。 attempts: type: integer description: 生成此报告的从 1 开始计数的尝试编号。 max_attempts: type: integer description: 针对该国家/地区配置的尝试配额（1 到 5，默认为 1）。 outcome: type: string enum: - match - partial_match - no_match - provider_error - format_rejected nullable: true description: >- 登记机构返回的结果。只有 `match`、`partial_match` 和 `no_match` 会计入尝试预算并产生计费。 comparison: type: array description: >- 数据源返回的每个可比对字段对应一行，此外每个数据源错误各对应一行。比对行使用下方的标准化字段名称，而非各国家/地区的请求字段键，因为多个请求字段（名字与姓氏，或任何标识符别名）会合并为单次比对。失败的数据源会附加一行 `field: "provider"` 且 `result: "error"`，因此在将某行视为字段判定之前，请先查看 `result`。 items: type: object required: - field - label - provided - record - result properties: field: type: string enum: - identification_number - full_name - date_of_birth - address - provider description: 归一化的比对字段。`provider` 不是用户字段：它用于标记数据源错误行。 label: type: string description: 行的显示标签，例如 `ID number`、`Full name`、`Provider`。 provided: type: string nullable: true description: 用户输入的内容。在 `provider` 错误行上为 `null`。 record: type: string nullable: true description: 数据源包含的内容。在 `provider` 错误行上，此项将替换为错误信息。 result: type: string enum: - match - partial - no_match - error description: >- 逐字段比对结果。`error` 仅出现在 `provider` 行，表示该数据源未响应；请将其视为有关查询本身的信息，绝非字段不匹配。 registry_portrait: type: string format: uri nullable: true description: 数据源返回肖像图像的短期预签名 URL。仅限返回肖像的四个政府登记机构（南非、尼日利亚、阿根廷、巴拿马）。 face_match_score: type: number nullable: true description: 自拍照与登记处肖像比对分数，0-100。仅在登记处返回肖像时提供。 wallet_verification: type: object nullable: true description: 凭证证据。仅当 `verification_method` 为 `wallet` 时存在；否则为 `null`。 properties: provider: type: string description: 目录钱包 ID，例如 `mitid`。 provider_name: type: string nullable: true description: 终端用户知晓的钱包名称，例如 `MitID`。 issuing_authority: type: string nullable: true description: 钱包背后的主管机构，例如 `Danish Agency for Digital Government`。 issuing_country: type: string description: 提供该钱包的 ISO 3166-1 alpha-3 国家/地区。 credential_type: type: string nullable: true description: 钱包出示的凭证，例如 `person_identification`。 level_of_assurance: type: string enum: - low - substantial - high nullable: true description: 钱包声明的保障级别。声明级别低于请求级别的登录会失败，而不是降级。 verified_at: type: string format: date-time nullable: true description: 钱包的认证时刻。 signature_valid: type: boolean nullable: true description: 钱包返回的签名断言是否通过验证。 attributes: type: object additionalProperties: true description: 钱包共享的属性，按钱包目录条目中所列的键名组织。 portrait: type: string format: uri nullable: true description: 钱包所共享肖像图像的短期预签名 URL（若钱包有共享）。 face_match_score: type: number nullable: true description: 自拍照与钱包肖像比对分数，0-100，在钱包共享肖像时提供。 status: type: string enum: - Not Finished - Approved - Declined - In Review - Expired description: >- 此身份证件验证步骤的功能级状态。独立于顶级会话的 `status`：会话可以达成其总体决策，而单个功能仍保持 `In Review`。 document_type: type: string description: 身份证件类型 document_subtype: type: string nullable: true description: >- 工作流证件设置中接受的证件子类型代码，适用时包含证件地区。示例：`ID_CARD_GENERIC`、`QUEENSLAND_DRIVER_LICENSE_GENERIC`。 document_number: type: string description: 证件识别号码 personal_number: type: string description: 个人身份号码 portrait_image: type: string format: uri description: 肖像图像 URL front_image: type: string format: uri description: 证件正面图像 URL front_video: type: string format: uri description: 证件正面视频 URL back_image: type: string format: uri description: 证件背面图像的 URL back_video: type: string format: uri description: 证件背面视频 URL full_front_image: type: string format: uri description: 完整证件正面图像 URL full_back_image: type: string format: uri description: 完整证件背面图像 URL front_image_camera_front: type: string format: uri description: 从前置摄像头捕获的证件正面图像 URL back_image_camera_front: type: string format: uri description: 从前置摄像头捕获的证件背面图像 URL date_of_birth: type: string format: date description: 证件中的出生日期 age: type: integer description: 根据出生日期计算出的年龄 expiration_date: type: string format: date description: 证件到期日期 date_of_issue: type: string format: date description: 证件签发日期 issuing_state: type: string description: 签发州的 ISO 代码 issuing_state_name: type: string description: 签发州的完整名称 first_name: type: string description: 证件中的名 last_name: type: string description: 证件上的姓氏 full_name: type: string description: 证件中的姓名 gender: type: string description: 证件中的性别 address: type: string description: 证件中的原始地址 formatted_address: type: string description: 格式化的完整地址 place_of_birth: type: string description: 证件上的出生地点 marital_status: type: string description: 证件中的婚姻状况 nationality: type: string description: ISO 国籍代码 extra_fields: type: object description: >- 证件附加字段。包括证件专有属性（例如 `dl_categories`、`blood_group`、`sponsor`、`employer`、`dl_class_code_b_from`、`dl_class_code_b_to`）。驾照准驾车型有效期日期以 `dl_class_code__from` 和 `dl_class_code__to` 形式返回，准驾车型的限制/信息代码（例如英国驾照的第 12 栏）以 `dl_class_code__notes` 形式返回。当证件包含多种文字系统的姓名、地址或出生地时，此对象还会包含这些字段的其他文字系统版本。工作流设置 `preferred_characters`（`latin` 或 `non_latin`）控制哪个文字系统填充顶层字段（`first_name`、`last_name`、`full_name`、`address`、`place_of_birth`）；相反的文字系统则放入此处，当 `preferred_characters` 为 `latin` 时记为 `first_name_non_latin` / `last_name_non_latin` / `full_name_non_latin` / `middle_name_non_latin` / `address_non_latin` / `place_of_birth_non_latin`，当 `preferred_characters` 为 `non_latin` 时带 `_latin` 后缀。仅当 OCR 实际提取出真实的备选文字系统值时才会出现对应键；若某个字段的备选值与首选字符集处于同一文字系统（例如，以西里尔字母标注的字段其 OCR 提取值返回了拉丁同形字），则会被跳过。当 `preferred_characters` 为 `latin` 但证件仅包含非拉丁文本时，Didit 会对提取的值进行音译，并提供 `first_name_latin` / `last_name_latin` 等作为后备。 additionalProperties: true properties: dl_categories: type: array items: type: string blood_group: type: string nullable: true first_name_non_latin: type: string description: >- 当 `preferred_characters=latin` 且证件上存在非拉丁文版本时的非拉丁文字系统名（例如吉尔吉斯斯坦身份证上的 `Айна`）。 last_name_non_latin: type: string description: 当 `preferred_characters=latin` 且证件上存在非拉丁字母版本时的非拉丁字母文字系统姓氏。 middle_name_non_latin: type: string description: >- 当 `preferred_characters=latin` 且证件上存在非拉丁字母版本时，采用非拉丁文字系统的中间名 / 父名。 full_name_non_latin: type: string description: 非拉丁文字系统的组合姓名。当名和姓均可用时，从各个组成部分重构。 address_non_latin: type: string description: 当 `preferred_characters=latin` 且证件上存在非拉丁版本时，非拉丁文字系统的地址。 place_of_birth_non_latin: type: string description: >- 当 `preferred_characters=latin` 且证件上存在非拉丁文版本时，以非拉丁文字系统表示的出生地点。 first_name_latin: type: string description: >- 拉丁文字系统的名。在 `preferred_characters=non_latin` 且证件上存在拉丁文版本时填充；或在 `preferred_characters=latin` 但证件仅包含非拉丁文本时，作为音译回退填充。 last_name_latin: type: string description: 拉丁字母文字系统的姓氏。规则同 `first_name_latin`。 middle_name_latin: type: string description: 拉丁字母中间名 / 父名。规则同 `first_name_latin`。 full_name_latin: type: string description: 拉丁文字系统的组合姓名。当名和姓均可用时，始终从各个组成部分重构。 address_latin: type: string description: 拉丁字母系统的地址。规则与 `first_name_latin` 相同。 place_of_birth_latin: type: string description: 以拉丁文字系统表示的出生地点。规则与 `first_name_latin` 相同。 mrz: type: object nullable: true description: 从证件中提取的机读区（MRZ）解析字段。若未检测到 MRZ 则为 `null`。 properties: surname: type: string example: MARTINEZ- 先前会话或人脸黑名单条目中与证件采集期间前置摄像头拍摄的自拍照相匹配的人脸（静默采集人脸搜索）。条目格式与 `liveness_checks[].matches` 相同。对于该字段存在之前创建的会话或未运行搜索的情况为 `null`；当搜索已运行但未找到匹配项时为空数组。`match_image_url` 是会过期的预签名 URL。 items: type: object properties: session_id: type: string format: uuid nullable: true description: >- 匹配人脸的会话 ID。当 `source` 为 `imported`、`list_entry` 或 `retained_template` 时为 `null`。 session_number: type: integer nullable: true similarity_percentage: type: number description: 两张图像之间的人脸相似度，限制在 0–100 之间。 vendor_data: type: string nullable: true description: 匹配会话或导入及保留模板人脸所关联用户的 `vendor_data`。 vendor_user_id: type: string format: uuid nullable: true description: >- 针对 `imported` 和 `retained_template` 匹配以及关联到用户的会话匹配的关联用户 ID。对于名单条目以及未关联用户的会话为 `null`。 biometric_template_id: type: string format: uuid nullable: true description: >- 保留的生物特征模板 ID。仅在 `source` 为 `retained_template` 时设置；否则为 `null`。 verification_date: type: string format: date-time nullable: true description: 匹配的人脸被采集的时间，或保留的模板创建的时间。对于名单条目为 `null`。 user_details: type: object nullable: true description: >- 来自匹配会话或导入的用户档案的身份数据。对于 `retained_template` 和 `list_entry` 匹配始终为 `null`。 properties: full_name: type: string nullable: true document_type: type: string nullable: true document_number: type: string nullable: true match_image_url: type: string format: uri nullable: true description: >- 基于图像比对的参考图像。对于 `retained_template` 比对始终为 `null`，因为保留的模板不包含图像。 status: type: string nullable: true description: 匹配会话的生命周期状态。非会话源为 `null`。 is_blocklisted: type: boolean description: 匹配的人脸是否在黑名单中。 is_allowlisted: type: boolean description: 匹配的人脸是否在白名单中。 api_service: type: string nullable: true description: >- 匹配会话的独立 API 服务（例如 `PASSIVE_LIVENESS`、`FACE_MATCH`）；对于工作流会话和非会话源为 `null`。 source: type: string enum: - session - imported - list_entry - retained_template description: >- 匹配人脸的来源：`session`、`imported`（用户人脸上传）、`list_entry`（允许/黑名单）或 `retained_template`（存储在用户上的无图像生物特征模板，列于 `/v3/biometric-templates/` 下）。 nullable: true front_image_quality_score: type: object nullable: true description: 证件正面图像的质量指标。每个子分数的范围为 0 到 100。 properties: focus_score: type: number description: >- 通过局部拉普拉斯方差最高的 10% 区域测量的图像清晰度。对具有大面积均匀背景的证件具有鲁棒性。较高的值表示图像更清晰、模糊程度更低。 brightness_score: type: number description: 图像的光照良好程度。对过暗或过曝的图像进行扣分，中等范围为理想亮度。 brightness_issue: type: string enum: - ok - too_dark - too_bright description: >- 当 brightness_score 较低时，指示亮度问题的方向。'ok' 表示亮度可接受，'too_dark' 表示图像曝光不足，'too_bright' 表示图像曝光过度。 is_document_fully_visible: type: boolean nullable: true description: >- 如果证件的全部四个角在图像画幅内完全可见，则为 true；如果任何一个角被截断，则为 false。当角的坐标不可用时为 null。 resolution_score: type: number description: 基于总像素数的图像有效分辨率。 overall_score: type: number description: 各子分数的加权综合评分（对焦 45%、亮度 30%、分辨率 25%）。 back_image_quality_score: type: object nullable: true description: 证件背面图像的质量指标。结构与 front_image_quality_score 相同。 properties: focus_score: type: number description: >- 通过局部拉普拉斯方差最高的 10% 区域测量的图像清晰度。对具有大面积均匀背景的证件具有鲁棒性。较高的值表示图像更清晰、模糊程度更低。 brightness_score: type: number description: 图像的光照良好程度。对过暗或过曝的图像进行扣分，中等范围为理想亮度。 brightness_issue: type: string enum: - ok - too_dark - too_bright description: >- 当 brightness_score 较低时，指示亮度问题的方向。'ok' 表示亮度可接受，'too_dark' 表示图像曝光不足，'too_bright' 表示图像曝光过度。 is_document_fully_visible: type: boolean nullable: true description: >- 如果证件的全部四个角在图像画幅内完全可见，则为 true；如果任何一个角被截断，则为 false。当角的坐标不可用时为 null。 resolution_score: type: number description: 基于总像素数的图像有效分辨率。 overall_score: type: number description: 各子分数的加权综合评分（对焦 45%、亮度 30%、分辨率 25%）。 warnings: type: array items: type: object properties: feature: type: string enum: - ID_VERIFICATION - NFC - LIVENESS - FACEMATCH - PROOF_OF_ADDRESS - PHONE - EMAIL - AML - LOCATION - DATABASE_VALIDATION - QUESTIONNAIRE - DOCUMENT_AI - KYB_REGISTRY - KYB_DOCUMENTS - KYB_KEY_PEOPLE - GEOLOCATION - SIGNATURE description: >- 生成此警告的功能（例如 `ID_VERIFICATION`、`NFC`、`LIVENESS`）。该值标识警告所属的功能块。每个模块的警告数组通常使用与其模块匹配的值，但在决策 payload 的所有功能警告中，上述枚举均具有权威性。 risk: type: string additional_data: type: object nullable: true description: 关于警告的其他上下文数据 log_type: type: string description: 日志类型：信息、警告或错误 short_description: type: string long_description: type: string node_id: type: string description: 生成此警告的工作流图节点 ID（适用于基于图的工作流） description: 证件验证警告 matches: type: array description: 在重复/黑名单检测期间找到的匹配证件（最多 5 个匹配项） items: type: object properties: session_id: type: string format: uuid description: 匹配证件的会话 ID session_number: type: integer description: 匹配证件的会话编号 vendor_data: type: string nullable: true description: 与匹配会话关联的厂商数据 verification_date: type: string format: date-time description: 匹配会话通过验证的日期 user_details: type: object properties: name: type: string description: 匹配证件中的姓名 document_type: type: string description: 匹配证件的类型 document_number: type: string description: 匹配证件的证件号码 status: type: string description: 匹配会话的状态 is_blocklisted: type: boolean description: 匹配的证件是否已被列入黑名单 api_service: type: string nullable: true description: 匹配会话的 API 服务类型 front_image_url: type: string format: uri nullable: true description: 来自匹配证件的证件正面图像 URL document_liveness: type: object nullable: true description: 按欺诈类型划分的证件活体评分，无论是否触发警告都会报告，以便仍可对已通过的证件进行审计。未运行该项检查时为 `null`。 properties: portrait_replace: type: object nullable: true properties: score: type: number nullable: true description: >- 该证件针对该欺诈类型为真实的可能性，0-100（数值越高 = 真实可能性越高）。两侧中的较低值，即决策所使用的值。两侧均未产生可用分数时为 `null`。 front: type: number nullable: true description: 正面分数；未捕获或分数被丢弃时为 `null`。 back: type: number nullable: true description: 背面分数；未捕获或分数被丢弃时为 `null`。 decline_threshold: type: number nullable: true description: 评估此证件时保存的拒绝阈值。后续工作流编辑不会更改它。当历史评估证据不可用时为 null。 review_threshold: type: number nullable: true description: 评估此证件时保存的审核阈值。后续的工作流修改不会更改该阈值。当历史评估证据不可用时为 null。 bucket: type: string nullable: true enum: - approve - review - decline - null description: >- 在评估时保存的欺诈类型分桶。当没有可用评分、未应用该检查或历史评估佐证材料不可用时为 null。后续对工作流的修改不会更改此值。 printed_copy: type: object nullable: true properties: score: type: number nullable: true description: >- 该证件针对该欺诈类型为真实的可能性，0-100（数值越高 = 真实可能性越高）。两侧中的较低值，即决策所使用的值。两侧均未产生可用分数时为 `null`。 front: type: number nullable: true description: 正面分数；未捕获或分数被丢弃时为 `null`。 back: type: number nullable: true description: 背面分数；未捕获或分数被丢弃时为 `null`。 decline_threshold: type: number nullable: true description: 评估此证件时保存的拒绝阈值。后续工作流编辑不会更改它。当历史评估证据不可用时为 null。 review_threshold: type: number nullable: true description: 评估此证件时保存的审核阈值。后续的工作流修改不会更改该阈值。当历史评估证据不可用时为 null。 bucket: type: string nullable: true enum: - approve - review - decline - null description: >- 在评估时保存的欺诈类型分桶。当没有可用评分、未应用该检查或历史评估佐证材料不可用时为 null。后续对工作流的修改不会更改此值。 screen_replay: type: object nullable: true properties: score: type: number nullable: true description: >- 该证件针对该欺诈类型为真实的可能性，0-100（数值越高 = 真实可能性越高）。两侧中的较低值，即决策所使用的值。两侧均未产生可用分数时为 `null`。 front: type: number nullable: true description: 正面分数；未捕获或分数被丢弃时为 `null`。 back: type: number nullable: true description: 背面分数；未捕获或分数被丢弃时为 `null`。 decline_threshold: type: number nullable: true description: 评估此证件时保存的拒绝阈值。后续工作流编辑不会更改它。当历史评估证据不可用时为 null。 review_threshold: type: number nullable: true description: 评估此证件时保存的审核阈值。后续的工作流修改不会更改该阈值。当历史评估证据不可用时为 null。 bucket: type: string nullable: true enum: - approve - review - decline - null description: >- 在评估时保存的欺诈类型分桶。当没有可用评分、未应用该检查或历史评估佐证材料不可用时为 null。后续对工作流的修改不会更改此值。 address_validation: allOf: - $ref: '#/components/schemas/AddressValidationResult' nullable: true description: >- 对印刷在此证件上的地址进行的地址核验：是否存在及其在证件读取时的规范化形式（后续更正 `address` 不会再次运行）。当此身份证件验证步骤启用了地址核验附加组件时存在；否则为 `null`。 region: type: string nullable: true description: 证件中注明的签发国家/地区的地区或州/省。 extracted_data: type: object nullable: true additionalProperties: true description: >- 展示给当事人审核的证件提取数据快照，保存在确认值旁边，以便您比对识别读取的内容与当事人确认的内容。若未要求当事人审核则为 `null`。 barcodes: type: array items: type: object additionalProperties: true description: 从证件条形码读取的数据。当证件没有条形码或未读取到任何条形码时为空。 nfc_skip_reason: type: string nullable: true enum: - USER_SKIPPED - DOCUMENT_WITHOUT_CHIP - CHIP_CERTIFICATE_UNAVAILABLE - DEVICE_WITHOUT_NFC - INTEGRATION_WITHOUT_NFC_ACCESS - MRZ_KEY_UNAVAILABLE - JPKI_UNAVAILABLE description: >- NFC 芯片验证未运行的原因，只要工作流包含 NFC 步骤便会填入此字段。NFC 待处理或芯片已被实际读取时为 `null`。取值：`USER_SKIPPED` - 用户在支持 NFC 的设备上选择跳过（由 `allow_nfc_skip` 允许）；`DOCUMENT_WITHOUT_CHIP` - 证件没有可读取的 NFC 芯片（非 ICAO 9303 电子证件）；`CHIP_CERTIFICATE_UNAVAILABLE` - 涵盖证件签发周期的签发国家/地区签名证书（CSCA）不可用，因此无法验证芯片签名；`DEVICE_WITHOUT_NFC` - 设备报告没有 NFC 读取器；`INTEGRATION_WITHOUT_NFC_ACCESS` - 验证在没有原生 SDK 的情况下运行（例如在 Web 浏览器中），因而无法访问手机的 NFC 读取器；`MRZ_KEY_UNAVAILABLE` - 无法从证件的 MRZ 派生芯片访问密钥；`JPKI_UNAVAILABLE` - 证件为日本个人番号卡（My Number Card），其芯片通过 JPKI 读取，且 JPKI 在本次验证中不可用：未启用，或应用的原生 SDK 无法读取个人番号卡。 nfc_verifications: type: array nullable: true description: >- **NFC / 电子护照报告数组**，由工作流图谱中的 NFC 步骤生成。**此字段始终为 JSON 数组，绝非单个 `nfc` 对象** — 如果您的工作流可以运行多次 NFC，请读取 `nfc_verifications[0]` 并进行遍历。在至少有一个 NFC 步骤生成数据之前为 `null`。每一项均为完整报告，包含 `node_id`、功能级别 `status`、`chip_protocol`、`chip_data`、`authenticity`（SOD + DG 完整性）、`certificate_summary` 以及 `warnings[]`。日本个人编号卡（My Number Card）通过 JPKI 而非 ICAO 9303 读取：其条目的 `chip_protocol: "jpki"`，证明数据保存在 `jpki` 下，并将 ICAO 字段保留为 `null`。当 NFC 步骤在提供给用户之前即被绕过（无芯片证件、缺少证书、未报告 NFC 功能、MRZ 密钥无法读取、个人编号卡的 JPKI 不可用），该字段保持为 `null`，且 `nfc_skip_reason` 会说明原因；如果在步骤本身被跳过（用户点击了跳过，或扫描时读卡器不可用），仍会生成一个带有 `is_nfc_skipped: true` 的报告。 items: type: object description: 单个 NFC 报告：单次芯片读取的完整报告（ICAO 9303 电子护照或 eID 芯片，或通过 JPKI 读取的日本个人编号卡）。 properties: node_id: type: string description: 生成此报告的 NFC 步骤的工作流图谱节点 ID。用于将报告与工作流定义进行关联。 status: type: string enum: - Not Finished - Approved - Declined - In Review - Resub Requested description: >- 此 NFC 步骤的功能级状态。独立于顶级会话的 `status`：会话可以达成其总体决策，而单个功能仍保持 `In Review`。 is_nfc_skipped: type: boolean description: 当此 NFC 步骤被明确跳过而非读取时为 `true`；`skip_reason` 会说明原因。 skip_reason: type: string nullable: true enum: - USER_SKIPPED - DOCUMENT_WITHOUT_CHIP - CHIP_CERTIFICATE_UNAVAILABLE - DEVICE_WITHOUT_NFC - INTEGRATION_WITHOUT_NFC_ACCESS - MRZ_KEY_UNAVAILABLE - JPKI_UNAVAILABLE description: >- 跳过此 NFC 步骤的原因。仅在 `is_nfc_skipped` 为 `true` 时设置。与会话级别的 `nfc_skip_reason` 分类相同，后者还额外涵盖 NFC 完全未生成报告的情况。 chip_protocol: type: string enum: - icao - jpki description: >- NFC 步骤读取芯片的方式。`icao`：ICAO 9303 电子护照或 eID 芯片，使用来自 MRZ 的访问密钥读取。`jpki`：日本个人编号卡（My Number Card），持有人在原生 SDK 中输入卡 PIN 码后，卡会对一次性 challenge 进行签名；结果位于 `jpki` 下。在跳过的步骤上也会设置，以便您区分跳过的个人编号卡读取。 jpki: type: object nullable: true description: >- 通过 JPKI 读取的日本个人编号卡（My Number Card）所证明的内容。当 `chip_protocol` 为 `jpki` 且已读取卡片时存在。对于 ICAO 芯片、跳过的步骤以及 NFC 步骤在未读取任何卡片的情况下关闭时（该情况会引发 `JPKI_SIGNATURE_INVALID`）为 `null`。从不包含证书、其序列号、签名或 12 位个人编号。 properties: certificate_types: type: array items: type: string enum: - user_authentication - signature description: >- 读取的卡片证书。始终读取 `user_authentication`（4 位 PIN 码）；当 NFC 节点的 `jpki_request_attributes` 设置开启时读取 `signature`（签名 PIN 码）。 chain_valid: type: boolean description: 当读取的所有证书均链接至 JPKI 认证机构、处于有效期内且属于对应类型的个人编号卡证书时为 `true`。 signature_valid: type: boolean description: >- 当卡片针对一次性质询所作的所有签名均验证通过时为 `true`。卡片仅在输入其 PIN 后才会签名，因此这证明了持有该卡并知晓该 PIN。 revocation_status: type: string enum: - good - revoked - unchecked description: >- 当吊销检查确认每个证书均有效时为 `good`，当任何证书被吊销（例如卡片报告丢失）时为 `revoked`，当无可用的吊销结果时为 `unchecked`。`unchecked` 绝不会被视为 `good`：NFC 节点的 `jpki_revocation_unchecked_action` 决定最终结果（默认为 `REVIEW`）。 ca_generation: type: string nullable: true description: 签发这些证书的 JPKI 认证机构代次，例如 `2023`。无证书链接至其中之一时为 `null`。 certificate_expires_at: type: string format: date-time nullable: true description: 所读取证书中最早的到期日期。 certificates: type: array items: type: object description: 从卡片读取的单张证书所证明的内容。绝不是证书本身或其序列号。 properties: type: type: string enum: - user_authentication - signature description: 此条目描述哪个卡片证书。 chain_valid: type: boolean description: 当证书链接至其所属类型的 JPKI 认证机构、处于有效期内且为该类型的个人编号卡证书时为 `true`。 signature_valid: type: boolean description: 当卡片针对一次性质询的签名通过此证书验证时为 `true`。 ca_generation: type: string nullable: true description: 签发该证书的 JPKI 认证机构代次，例如 `2023`。未找到受信任签发机构时为 `null`。 not_valid_before: type: string format: date-time nullable: true description: 证书有效期的起始时间。无法读取证书时为 `null`。 not_valid_after: type: string format: date-time nullable: true description: 证书有效期的结束时间。无法读取证书时为 `null`。 failure: type: string nullable: true enum: - unreadable_certificate - untrusted_issuer - expired - not_yet_valid - wrong_policy - key_usage - null description: >- `chain_valid` 为 `false` 的原因：`unreadable_certificate`、`untrusted_issuer`（非对应类型的 JPKI 证书颁发机构签发）、`expired`、`not_yet_valid`、`wrong_policy`（非该类型的个人番号卡证书）或 `key_usage`（密钥不可用于签名）。证书链有效时为 `null`。 description: 按证书划分的结果，读取到的每张证书对应一个条目。 attributes: type: object nullable: true description: >- 签名证书中的持有人数据，需在其证书链有效时提供。当未请求签名证书或证书链未连接至 JPKI 认证机构时为 `null`。 properties: full_name: type: string nullable: true description: 登记的名称，通常为日文文字系统。 date_of_birth: type: string format: date nullable: true description: 出生日期，`YYYY-MM-DD`。当登记的日期不完整时为 `null`。 gender: type: string nullable: true enum: - M - F - null description: '`M`、`F`，或在未登记时为 `null`。' address: type: string nullable: true description: 注册地址。 name_substitute_characters: type: string nullable: true description: >- 位置字符串，用于标记 `full_name` 中因原始字符超出标准字符集而被替代的字符。无字符被替换时为 `null`。 address_substitute_characters: type: string nullable: true description: >- 标记 `address` 中替代字符的位置字符串，同 `name_substitute_characters`。 attributes_match_ocr: type: boolean nullable: true description: >- 当属性与从同一张卡片照片中读取的数据匹配时为 `true`，当任何属性不一致时为 `false`（`JPKI_AND_OCR_DATA_NOT_SAME`），当无法进行任何比对（包括 `attributes` 为 `null` 的任何情况）时为 `null`。 mismatched_attributes: type: array items: type: string enum: - full_name - date_of_birth - gender - address description: 与照片数据不一致的属性名称，绝不包含其值。当比对的所有内容均匹配时为空。 portrait_image: type: string format: uri nullable: true description: >- 从芯片（ICAO DG2）读取的肖像预签名 URL。对于 JPKI 读取（`chip_protocol: "jpki"`）以及跳过的步骤为 `null`。 signature_image: type: string format: uri nullable: true description: >- 从芯片（ICAO DG7）读取的持有人签名图像预签名 URL（如果芯片中存储有该图像）。对于 JPKI 读取（`chip_protocol: "jpki"`）以及跳过的步骤为 `null`。 chip_data: type: object nullable: true description: >- 从 ICAO 芯片的数据组中解析出的个人数据。对于 JPKI 读取（`chip_protocol: "jpki"`）和已跳过的步骤为 `null`。 properties: document_type: type: string issuing_country: type: string document_number: type: string expiration_date: type: string format: date first_name: type: string last_name: type: string birth_date: type: string format: date gender: type: string nationality: type: string address: type: string place_of_birth: type: string authenticity: type: object nullable: true description: >- ICAO 被动认证：SOD 签名（`sod_integrity`）和数据组哈希（`dg_integrity`）。对于 JPKI 读取为 `null`，其证明在 `jpki` 下报告。 properties: sod_integrity: type: boolean dg_integrity: type: boolean certificate_summary: type: object nullable: true description: >- ICAO 证件签名者证书（Document Signer Certificate）摘要。对于 JPKI 读取（`chip_protocol: "jpki"`）和跳过的步骤为 `null`。 properties: issuer: type: string subject: type: string serial_number: type: string not_valid_after: type: string format: date-time not_valid_before: type: string format: date-time warnings: type: array items: type: object properties: feature: type: string enum: - ID_VERIFICATION - NFC - LIVENESS - FACEMATCH - PROOF_OF_ADDRESS - PHONE - EMAIL - AML - LOCATION - DATABASE_VALIDATION - QUESTIONNAIRE - DOCUMENT_AI - KYB_REGISTRY - KYB_DOCUMENTS - KYB_KEY_PEOPLE - GEOLOCATION - SIGNATURE description: >- 生成此警告的功能。该值标识警告所属的功能块。每个模块的警告数组通常使用与其模块匹配的值（例如 `phone_verifications[].warnings` 内的 `PHONE`），但上述枚举在决策 payload 的所有功能警告中具有权威性。 risk: type: string additional_data: type: object nullable: true log_type: type: string short_description: type: string long_description: type: string node_id: type: string description: 生成此警告的工作流图节点 ID liveness_checks: type: array nullable: true description: >- **活体检测报告数组**，由工作流图谱中的活体检测步骤生成。始终为 JSON 数组 — 绝非单个 `liveness` 对象。在至少有一个活体检测步骤生成数据之前为 `null`。每一项均为完整报告，包含 `node_id`、功能级别 `status`、`method`、`score`、`reference_image`、`video_url`、可选的 `age_estimation`、跨会话 `matches[]` 以及 `warnings[]`。 items: type: object description: 一份活体检测报告：单次活体检测流程的完整报告。 properties: node_id: type: string description: 生成此报告的活体检测步骤的工作流图谱节点 ID。 status: type: string enum: - Not Finished - Approved - Declined - In Review - Resub Requested description: >- 此活体检测步骤的功能级状态。独立于顶级会话的 `status`：会话可以达成其总体决策，而单个功能仍保持 `In Review`。 method: type: string description: 用于活体检测的方法 score: type: number description: 活体检测的置信度分数 reference_image: type: string format: uri description: 所使用的参考图像 URL video_url: type: string format: uri description: 活体检测视频 URL age_estimation: type: number description: 人员的估算年龄 matches: type: array description: >- 重复人脸搜索找到的相似人脸（最佳匹配项，黑名单/白名单条目优先）。每个条目的 `source` 会告知匹配人脸的来源：`session`（另一个验证会话）、`imported`（针对供应商用户上传的人脸）、`list_entry`（组织管理的白名单/黑名单人脸）或 `retained_template`（存储在用户上的无图像生物特征模板，列于 `/v3/biometric-templates/` 下）。对于非会话来源，`session_id`、`session_number`、`status` 和 `api_service` 均为 `null`。`imported` 匹配项仍会从供应商用户记录中填充 `vendor_data`、`verification_date` 以及（当供应商用户建档有姓名时）`user_details`（仅包含 `full_name`）；`retained_template` 匹配项会填充 `vendor_user_id`、`vendor_data`、`biometric_template_id` 和 `verification_date`，而其图像和身份字段为 `null`；`list_entry` 匹配项将所有这些字段返回为 `null`。 items: type: object properties: session_id: type: string format: uuid nullable: true description: >- 匹配人脸的会话 ID。当 `source` 为 `imported`、`list_entry` 或 `retained_template` 时为 `null`。 session_number: type: integer nullable: true similarity_percentage: type: number description: 两张图像之间的人脸相似度，限制在 0–100 之间。 vendor_data: type: string nullable: true description: 匹配会话或导入及保留模板人脸所关联用户的 `vendor_data`。 vendor_user_id: type: string format: uuid nullable: true description: >- 针对 `imported` 和 `retained_template` 匹配以及关联到用户的会话匹配的关联用户 ID。对于名单条目以及未关联用户的会话为 `null`。 biometric_template_id: type: string format: uuid nullable: true description: >- 保留的生物特征模板 ID。仅在 `source` 为 `retained_template` 时设置；否则为 `null`。 verification_date: type: string format: date-time nullable: true description: 匹配的人脸被采集的时间，或保留的模板创建的时间。对于名单条目为 `null`。 user_details: type: object nullable: true description: >- 来自匹配会话或导入的用户档案的身份数据。对于 `retained_template` 和 `list_entry` 匹配始终为 `null`。 properties: full_name: type: string nullable: true document_type: type: string nullable: true document_number: type: string nullable: true match_image_url: type: string format: uri nullable: true description: >- 基于图像比对的参考图像。对于 `retained_template` 比对始终为 `null`，因为保留的模板不包含图像。 status: type: string nullable: true description: 匹配会话的生命周期状态。非会话源为 `null`。 is_blocklisted: type: boolean description: 匹配的人脸是否在黑名单中。 is_allowlisted: type: boolean description: 匹配的人脸是否在白名单中。 api_service: type: string nullable: true description: >- 匹配会话的独立 API 服务（例如 `PASSIVE_LIVENESS`、`FACE_MATCH`）；对于工作流会话和非会话源为 `null`。 source: type: string enum: - session - imported - list_entry - retained_template description: >- 匹配人脸的来源：`session`、`imported`（用户人脸上传）、`list_entry`（允许/黑名单）或 `retained_template`（存储在用户上的无图像生物特征模板，列于 `/v3/biometric-templates/` 下）。 warnings: type: array items: type: object properties: feature: type: string enum: - ID_VERIFICATION - NFC - LIVENESS - FACEMATCH - PROOF_OF_ADDRESS - PHONE - EMAIL - AML - LOCATION - DATABASE_VALIDATION - QUESTIONNAIRE - DOCUMENT_AI - KYB_REGISTRY - KYB_DOCUMENTS - KYB_KEY_PEOPLE - GEOLOCATION - SIGNATURE description: >- 生成此警告的功能。该值标识警告所属的功能块。每个模块的警告数组通常使用与其模块匹配的值（例如 `phone_verifications[].warnings` 内的 `PHONE`），但上述枚举在决策 payload 的所有功能警告中具有权威性。 risk: type: string additional_data: type: object nullable: true log_type: type: string short_description: type: string long_description: type: string node_id: type: string description: 生成此警告的工作流图节点 ID face_quality: type: number nullable: true description: 人脸图像质量分数（0-100%）。仅适用于被动活体检测。 face_luminance: type: number nullable: true description: 人脸照度/亮度评分（0-100%）。仅适用于被动活体检测。 face_matches: type: array nullable: true description: >- **人脸比对报告数组**，由工作流图谱中的人脸比对步骤生成。始终为 JSON 数组 — 绝非单个 `face_match` 对象。在至少有一个人脸比对步骤生成数据之前为 `null`。每一项均为完整报告，包含 `node_id`、功能级别 `status`、相似度 `score`、`source_image`、`target_image` 以及 `warnings[]`。 items: type: object description: 一份人脸比对报告：完整报告。 properties: node_id: type: string description: 生成此报告的人脸比对步骤的工作流图谱节点 ID。 status: type: string enum: - Not Finished - Approved - Declined - In Review - Resub Requested description: >- 此人脸比对步骤的功能级状态。独立于顶级会话的 `status`：会话可以得出其总体决策，而单个功能仍保持 `In Review`。 score: type: number description: 人脸比对的置信度分数 source_image_session_id: type: string format: uuid nullable: true description: >- 存储源（参考）人像的会话 id。在生物识别认证流程中，这是会话自身的 id（提交的人像存储在新的会话下）。当源图像为同一会话的证件人像时为 `null`。 source_image: type: string format: uri description: 用于比对的源图像 URL target_image: type: string format: uri description: 用于比对的目标图像 URL warnings: type: array items: type: object properties: feature: type: string enum: - ID_VERIFICATION - NFC - LIVENESS - FACEMATCH - PROOF_OF_ADDRESS - PHONE - EMAIL - AML - LOCATION - DATABASE_VALIDATION - QUESTIONNAIRE - DOCUMENT_AI - KYB_REGISTRY - KYB_DOCUMENTS - KYB_KEY_PEOPLE - GEOLOCATION - SIGNATURE description: >- 生成此警告的功能。该值标识警告所属的功能块。每个模块的警告数组通常使用与其模块匹配的值（例如 `phone_verifications[].warnings` 内的 `PHONE`），但上述枚举在决策 payload 的所有功能警告中具有权威性。 risk: type: string additional_data: type: object nullable: true log_type: type: string short_description: type: string long_description: type: string node_id: type: string description: 生成此警告的工作流图节点 ID description: 人脸比对验证警告 face_coverage: type: object nullable: true description: >- 捕获的图像中眼睛、嘴巴和面部是否有遮挡。仅由 `GET /v3/session/{sessionId}/decision/` 返回；不属于 Webhook payload 的一部分。不存在遮挡读取数据时为 `null`。 properties: eyes: type: object properties: covered: type: boolean nullable: true calibrated: type: boolean nullable: true description: '`false` 表示该读数仅作为影子证据，不会触发任何警告。' visibility_score: type: number nullable: true mouth: type: object properties: covered: type: boolean nullable: true calibrated: type: boolean nullable: true description: '`false` 表示该读数仅作为影子证据，不会触发任何警告。' visibility_score: type: number nullable: true face: type: object properties: covered: type: boolean nullable: true calibrated: type: boolean nullable: true description: '`false` 表示该读数仅作为影子证据，不会触发任何警告。' visibility_score: type: number nullable: true phone_verifications: type: array nullable: true description: >- **电话验证报告数组** — 始终为 JSON 数组，绝非单个 `phone` 对象。在至少有一个电话步骤生成数据之前为 `null`。每一项均为完整报告，包含 `node_id`、功能级别 `status`、电话号码与国家/地区元数据、`lifecycle[]`、`matches[]` 以及 `warnings[]`。 items: type: object properties: node_id: type: string description: 工作流图谱中此电话步骤的唯一标识符。 status: type: string description: >- 此电话验证步骤的功能级状态。独立于顶级会话的 `status`：会话可以达成其总体决策，而单个功能仍保持 `In Review`。 enum: - Not Finished - Approved - Declined - In Review - Expired phone_number_prefix: type: string description: 国家/地区国际呼叫代码前缀 phone_number: type: string description: 不带国家/地区前缀的电话号码 full_number: type: string description: 包含国家/地区前缀的完整电话号码 country_code: type: string description: 两字母国家/地区代码（ISO 3166-1 alpha-2） country_name: type: string description: 国家/地区全称 carrier: type: object properties: name: type: string description: 电话运营商名称 type: type: string description: 电话线路类型（移动电话、座机等） is_disposable: type: boolean description: 电话号码是否来自一次性号码服务 is_virtual: type: boolean description: 电话号码是否为虚拟号码 verification_method: type: string description: 用于验证电话号码的方法 verification_attempts: type: integer description: 已进行的验证尝试次数 verified_at: type: string format: date-time description: 电话验证完成的时间戳 lifecycle: type: array description: 电话验证生命周期中按时间顺序排列的事件列表。 items: type: object properties: type: type: string timestamp: type: string format: date-time details: type: object nullable: true description: >- 特定事件的 payload。发送事件包含 `status`、`reason`、`channel`、`actual_channel`；投递事件包含 `channel`、`status`；验证码核验事件包含 `code_tried`、`status`；最终状态事件包含 `reason`，若无需报告原因则为 `null`（例如 `PHONE_VERIFICATION_APPROVED`）。 properties: status: type: string reason: type: string nullable: true channel: type: string nullable: true actual_channel: type: string nullable: true code_tried: type: string fee: type: number warnings: type: array description: 与电话验证相关的警告列表 items: type: object properties: feature: type: string enum: - ID_VERIFICATION - NFC - LIVENESS - FACEMATCH - PROOF_OF_ADDRESS - PHONE - EMAIL - AML - LOCATION - DATABASE_VALIDATION - QUESTIONNAIRE - DOCUMENT_AI - KYB_REGISTRY - KYB_DOCUMENTS - KYB_KEY_PEOPLE - GEOLOCATION - SIGNATURE description: >- 生成此警告的功能。该值标识警告所属的功能块。每个模块的警告数组通常使用与其模块匹配的值（例如 `phone_verifications[].warnings` 内的 `PHONE`），但上述枚举在决策 payload 的所有功能警告中具有权威性。 risk: type: string additional_data: type: object nullable: true log_type: type: string short_description: type: string long_description: type: string node_id: type: string description: 生成此警告的工作流图节点 ID matches: type: array description: >- 针对此电话号码找到的匹配项。每个匹配项都包含一个 `source`：`session`（您的应用中的另一个验证会话匹配到了相同的号码，连同 `session_id`/`session_number`/`vendor_data`/`verification_date` 一同返回）或 `list_entry`（该号码位于组织管理的允许/阻止名单中 — 请参阅 `/management-api/lists/overview`）。跨会话匹配使用不同的 `vendor_data`，上限为 5 项。 items: type: object properties: session_id: type: string format: uuid nullable: true session_number: type: integer nullable: true vendor_data: type: string nullable: true verification_date: type: string format: date-time nullable: true phone_number: type: string status: type: string nullable: true is_blocklisted: type: boolean api_service: type: string nullable: true source: type: string enum: - session - list_entry description: >- 匹配来源。`session` 表示您应用中的另一个验证会话在该值上发生匹配。`list_entry` 表示该值命中了组织管理的名单（允许名单/黑名单），有关如何管理这些名单，请参阅 `/management-api/lists/overview` 处的管理 API 名单概述。 phone_intelligence: allOf: - $ref: '#/components/schemas/PhoneIntelligence' description: 电话智能信号。仅当针对该号码运行了电话智能附加组件时存在。 phone_social: allOf: - $ref: '#/components/schemas/PhoneSocialFootprint' description: 电话号码的社交足迹。仅当为此号码运行了社交足迹附加组件时才会出现。 email_verifications: type: array nullable: true description: >- **邮箱验证报告数组** — 始终为 JSON 数组，绝非单个 `email` 对象。在至少有一个邮箱步骤生成数据之前为 `null`。每一项均为完整报告，包含 `node_id`、功能级别 `status`、邮箱地址、数据泄露信息、`lifecycle[]`、`matches[]` 以及 `warnings[]`。 items: type: object properties: node_id: type: string description: 工作流图谱中此邮箱步骤的唯一标识符。 status: type: string description: >- 此邮箱验证步骤的功能级状态。独立于顶级会话的 `status`：会话可以达成其总体决策，而单个功能仍保持 `In Review`。 enum: - Not Finished - Approved - Declined - In Review - Expired email: type: string description: 正在验证的邮箱地址 is_breached: type: boolean description: 指示邮箱是否出现在已知的数据泄露事件中 breaches: type: array description: 发现该邮箱涉及的已知数据泄露事件列表 items: type: object properties: name: type: string description: 数据泄露事件的名称 domain: type: string description: 受数据泄露影响的域名 logo_path: type: string description: 发生数据泄露服务的徽标 URL breach_date: type: string format: date description: 违规行为发生的日期 description: type: string description: 违规情况说明 is_verified: type: boolean description: 数据泄露是否已核实 data_classes: type: array description: 泄露事件中暴露的数据类型 items: type: string breach_emails_count: type: integer description: 泄露事件中受影响的邮箱地址数量 is_disposable: type: boolean description: 指示邮箱是否来自一次性邮箱提供商 is_undeliverable: type: boolean description: 指示邮箱地址是否不可投递 verification_attempts: type: integer description: 该邮箱的验证尝试次数 verified_at: type: string format: date-time description: 邮箱验证完成的时间戳 warnings: type: array description: 与邮箱验证相关的警告列表 items: type: object properties: feature: type: string enum: - ID_VERIFICATION - NFC - LIVENESS - FACEMATCH - PROOF_OF_ADDRESS - PHONE - EMAIL - AML - LOCATION - DATABASE_VALIDATION - QUESTIONNAIRE - DOCUMENT_AI - KYB_REGISTRY - KYB_DOCUMENTS - KYB_KEY_PEOPLE - GEOLOCATION - SIGNATURE description: >- 生成此警告的功能。该值标识警告所属的功能块。每个模块的警告数组通常使用与其模块匹配的值（例如 `phone_verifications[].warnings` 内的 `PHONE`），但上述枚举在决策 payload 的所有功能警告中具有权威性。 risk: type: string additional_data: type: object nullable: true log_type: type: string short_description: type: string long_description: type: string node_id: type: string description: 生成此警告的工作流图节点 ID lifecycle: type: array description: 邮箱验证生命周期中按时间顺序排列的事件列表。 items: type: object properties: type: type: string timestamp: type: string format: date-time details: type: object nullable: true description: >- 特定事件的 payload。发送事件包含 `status`、`reason`；验证码核验事件包含 `code_tried`、`status`；最终状态事件包含 `reason`，当无需报告原因时为 `null`（例如 `EMAIL_VERIFICATION_APPROVED`）。 properties: status: type: string reason: type: string nullable: true code_tried: type: string fee: type: number matches: type: array description: >- 针对此邮箱地址找到的匹配项。每个匹配项都包含一个 `source`：`session`（您的应用中的另一个验证会话匹配到了相同的邮箱，连同 `session_id`/`session_number`/`vendor_data`/`verification_date` 一同返回）或 `list_entry`（该邮箱位于组织管理的允许/阻止名单中 — 请参阅 `/management-api/lists/overview`）。跨会话匹配使用不同的 `vendor_data`，上限为 5 项。 items: type: object properties: session_id: type: string format: uuid nullable: true session_number: type: integer nullable: true vendor_data: type: string nullable: true verification_date: type: string format: date-time nullable: true email: type: string format: email status: type: string nullable: true is_blocklisted: type: boolean api_service: type: string nullable: true source: type: string enum: - session - list_entry description: >- 匹配来源。`session` 表示您应用中的另一个验证会话在该值上发生匹配。`list_entry` 表示该值命中了组织管理的名单（允许名单/黑名单），有关如何管理这些名单，请参阅 `/management-api/lists/overview` 处的管理 API 名单概述。 email_intelligence: allOf: - $ref: '#/components/schemas/EmailIntelligence' description: 邮箱情报信号。仅在该地址运行了邮箱情报附加组件时存在。 email_social: allOf: - $ref: '#/components/schemas/EmailSocialFootprint' description: 地址的社交足迹。仅当为此地址运行了社交足迹附加组件时才会出现。 poa_verifications: type: array nullable: true description: >- **地址证明（POA）报告数组** — 始终为 JSON 数组，绝非单个 `poa` 对象。在至少有一个 POA 步骤生成数据之前为 `null`。每一项均为完整报告，包含 `node_id`、功能级别 `status`、证件文件 URL、签发方、日期、解析后的地址以及 `warnings[]`。 items: type: object properties: node_id: type: string description: 工作流图谱中该 POA 步骤的唯一标识符。 status: type: string description: >- 此地址证明步骤的功能级状态。独立于顶级会话的 `status`：会话可以达成其总体决策，而单个功能仍保持 `In Review`。 enum: - Not Finished - Approved - Declined - In Review - Resub Requested document_file: type: string format: uri description: 地址证明证件 URL issuing_state: type: string description: 签发国家/地区的两字母代码 document_type: type: string description: 地址证明证件类型 document_subtype: type: string nullable: true description: 检测到时，POA 证件在其 `document_type` 内的更具体分类。否则为 `null`。 document_language: type: string description: 证件的语言代码 document_metadata: type: object properties: file_size: type: integer description: 证件大小 content_type: type: string description: 证件的内容类型 creation_date: type: string format: date description: 证件创建的日期 modified_date: type: string format: date description: 证件修改的日期 overlay_manipulation: type: object nullable: true description: 针对疑似覆盖文本篡改的 PDF 取证分析。当未发现覆盖篡改证据或证件不是 PDF 时为 Null。 properties: detected: type: boolean description: 是否检测到覆盖文本篡改的迹象。 analyzed: type: boolean description: PDF 是否可以被分析。 analysis_incomplete: type: boolean description: >- 仅当文件无法被完整检查时才存在且值为 true。已检查的部分在可能的情况下保留其检查结果，文档会发出未经验证的文本替换警告。 signals: type: array items: type: string description: >- 触发的取证信号，例如 duplicate_font_subset 或 glyph_fragmentation。 manipulated_regions: type: array description: PDF 页面坐标系中疑似被篡改的区域。 items: type: object properties: page: type: integer x: type: number 'y': type: number width: type: number height: type: number page_width: type: number page_height: type: number creator: type: string nullable: true description: 证件元数据中记录的创建者应用。 producer: type: string nullable: true description: PDF 元数据中记录的制作软件。 software: type: string nullable: true description: 文件元数据中记录的编辑/处理软件。 encryption: type: string nullable: true description: 证件加密时的加密方案。 is_signed: type: boolean nullable: true description: PDF 是否带有数字签名。 is_tampered: type: boolean nullable: true description: 签名验证是否表明文件在签名后被修改过。 signature_info: type: object nullable: true description: 数字签名的详细信息（若存在）。 exif_original_date: type: string nullable: true description: EXIF 原始拍摄日期，适用于图片上传。 exif_digitized_date: type: string nullable: true description: EXIF 数字化日期，适用于图片上传。 processed_by_known_editor: type: boolean nullable: true description: 文件元数据是否表明曾由已知的文档编辑器处理过。 has_different_creation_mod_date: type: boolean nullable: true description: 创建日期与修改日期是否不同，这是一种常见的篡改信号。 description: >- 从上传的地址证明（POA）证件中提取的文件取证元数据。始终包含以下键（不适用时值为 `null`，例如 PDF 的 EXIF 日期）。当无法提取元数据时为 `null`。 nullable: true issuer: type: string description: 证件签发机构名称 issue_date: type: string format: date description: 证件签发的日期 expiration_date: type: string format: date nullable: true description: 证件的到期日期（如可用） poa_address: type: string description: 地址证明证件中的原始地址 poa_formatted_address: type: string description: 来自地址证明文件的格式化地址 poa_parsed_address: type: object properties: address_type: type: string description: 地址类型（街道、大道等） street_1: type: string description: 主要街道地址 street_2: type: string nullable: true description: 备用街道地址 city: type: string description: 城市名称 region: type: string description: 地区或州/省名称 country: type: string description: 两字母国家/地区代码 postal_code: type: string description: 邮政编码 document_location: type: object properties: latitude: type: number description: 纬度坐标 longitude: type: number description: 经度坐标 name_on_document: type: string nullable: true description: 从地址证明证件中提取的开户人/收件人姓名，用于姓名比对。无法提取姓名时为 `null`。 name_match_score_expected_details: type: number nullable: true description: >- `name_on_document` 与创建会话时提供的预期姓名之间的相似度分数（0-100）。任一方缺失时为 `null`。 name_match_score_id_verification: type: number nullable: true description: >- `name_on_document` 与身份证件验证步骤提取的姓名之间的相似度分数（0-100）。任一方缺失时为 `null`。 expected_details_address: type: string nullable: true description: 用于验证的预期原始地址 expected_details_formatted_address: type: string nullable: true description: 用于验证的预期格式化地址 expected_details_parsed_address: type: object description: 用于验证的预期已解析地址详细信息 extra_fields: type: object description: 从证件中提取的其他银行和联系方式详情。 properties: bank_account_number: type: string nullable: true bank_iban: type: string nullable: true bank_sort_code: type: string nullable: true bank_routing_number: type: string nullable: true bank_swift_bic: type: string nullable: true bank_branch_name: type: string nullable: true bank_branch_address: type: string nullable: true document_phone_number: type: string nullable: true additional_names: type: array items: type: string extra_files: type: array items: type: string format: uri description: 附加地址证明文件 warnings: type: array items: type: object properties: feature: type: string enum: - ID_VERIFICATION - NFC - LIVENESS - FACEMATCH - PROOF_OF_ADDRESS - PHONE - EMAIL - AML - LOCATION - DATABASE_VALIDATION - QUESTIONNAIRE - DOCUMENT_AI - KYB_REGISTRY - KYB_DOCUMENTS - KYB_KEY_PEOPLE - GEOLOCATION - SIGNATURE description: >- 生成此警告的功能。该值标识警告所属的功能块。每个模块的警告数组通常使用与其模块匹配的值（例如 `phone_verifications[].warnings` 内的 `PHONE`），但上述枚举在决策 payload 的所有功能警告中具有权威性。 risk: type: string additional_data: type: object nullable: true log_type: type: string short_description: type: string long_description: type: string node_id: type: string description: 生成此警告的工作流图节点 ID detected_codes: type: array description: >- 在证件的所有已处理页面中检测到的二维码和条形码。如果未找到任何码则为空。已定位但无法解码的二维码其 `parsed_payload: null`。 items: $ref: '#/components/schemas/DocumentAIDetectedCode' address_validation: allOf: - $ref: '#/components/schemas/AddressValidationResult' nullable: true description: >- 对该地址证明中的地址进行地址核验：是否存在以及证件读取时的规范化形式（后续更正 `poa_address` 不会再次运行）。当此地址证明步骤启用了地址核验附加组件且上传通过了证件检查时存在；否则为 `null`。 document_ai_documents: type: array nullable: true description: >- **按工作流节点分组的 Document AI 报告** — 始终为 JSON 数组，绝不是单个对象。在至少一个 Document AI 步骤生成数据之前为 `null`。仅在 `session_kind = user` 时存在。每项为一个节点组，包含聚合的 `status`、`node_id`、按证件列出的结果组成的 `items[]` 数组（提取的数据以配置的字段键作为键名）以及 `warnings`。 items: type: object description: 按工作流节点分组的 Document AI 结果。 properties: status: type: string description: 此节点的 Document AI 汇总状态，从其 `items[]` 汇总得出。 enum: - Approved - Declined - In Review - Not Finished node_id: type: string nullable: true description: 工作流图谱中该 Document AI 步骤的唯一标识符。 items: type: array items: type: object properties: uuid: type: string format: uuid node_id: type: string nullable: true description: 生成此证件的工作流图谱节点。 document_key: type: string description: 此文件对应的已配置 Document AI 证件的键。 original_filename: type: string nullable: true description: 用户上传时的文件名。 file_size: type: integer nullable: true description: 文件大小（字节）。 file_url: type: string format: uri nullable: true description: 已上传文件的短期预签名链接。 status: type: string enum: - Approved - Declined - In Review - Not Finished description: 按证件划分的 Document AI 状态。 extracted_data: type: object additionalProperties: true nullable: true description: 由 Document AI 提取的值，以配置的字段 `key` 为键。每个值均为字符串、数字或 `null`。 detected_codes: type: array description: >- 在所有已处理页面中检测到的二维码和条形码。未找到时为空。已定位但无法解码的二维码其 `parsed_payload: null`。 items: $ref: '#/components/schemas/DocumentAIDetectedCode' fields: type: array description: 为此证件配置的提取字段。 items: type: object properties: key: type: string description: 用作 `extracted_data` 中键名的稳定字段键名。 name: type: string description: 便于人类阅读的字段名称。 instruction: type: string description: 显示给模型的提取指令。 type: type: string enum: - text - number - date description: 提取字段的预期值类型。 required: type: boolean description: Whether this field is required. document_metadata: type: object nullable: true description: 从上传的证件中提取的文件取证元数据（例如 `is_tampered`）。当无法提取任何内容时为 `null`。 cross_check_result: type: object nullable: true description: 提取的证件字段与其他会话数据的交叉比对。未执行交叉核对时为 `null`。 created_at: type: string format: date-time warnings: type: array nullable: true items: type: object description: 为此 Document AI 节点生成的警告日志。 questionnaire_responses: type: array nullable: true description: >- **问卷响应报告数组** — 始终为 JSON 数组，绝非单个 `questionnaire` 对象。在至少有一个问卷步骤生成数据之前为 `null`。每一项均为完整报告，包含 `node_id`、问卷元数据、包含表单元素的小节以及用户的回答。 items: type: object properties: node_id: type: string description: 工作流图谱中此问卷步骤的唯一标识符。 questionnaire_id: type: string description: 问卷的唯一标识符 title: type: string description: 问卷标题 description: type: string description: 问卷说明 languages: type: array items: type: string description: 支持的语言 default_language: type: string description: 默认语言 is_active: type: boolean description: 该问卷是否处于活跃状态 is_simple_questionnaire: type: boolean description: 该问卷是否为简单的线性表单（无分支图谱）。 questionnaire_group_id: type: string format: uuid nullable: true description: 跨版本问卷组的稳定标识符。 version: type: integer nullable: true description: 已作答问卷的版本号。 published_at: type: string format: date-time nullable: true description: 该问卷版本发布的时间戳。 sections: type: array items: type: object properties: title: type: string nullable: true description: 部分标题 description: type: string nullable: true description: 部分描述 items: type: array items: type: object properties: uuid: type: string description: 项目的唯一标识符 value: type: string nullable: true description: 该表单元素在问卷图谱中的稳定节点标识符。 element_type: type: string description: 问卷元素的类型 is_required: type: boolean description: 该项是否为必填 title: type: string description: 项目的标题 description: type: string nullable: true description: 项目的说明 placeholder: type: string nullable: true description: 占位文本 choices: type: array nullable: true items: type: object properties: label: type: string value: type: string requires_text_input: type: boolean description: 此选项是否需要额外的文本输入 nullable: true required: - label - value description: 下拉列表或单选元素的选项 max_files: type: integer description: 允许的最大文件数量 nullable: true answer: type: object description: 为该项提供的答案 properties: value: type: string nullable: true text: type: string nullable: true files: type: array items: type: string nullable: true required_if: type: object nullable: true description: 条件性必填规则，用于该元素仅在特定答案下才必填的情况。 repeatable_config: type: object nullable: true description: 可重复元素组的配置（如适用）。 required: - uuid - value - element_type - is_required - title status: type: string description: 问卷的状态 bank_verifications: type: array nullable: true description: >- 银行验证结果，每个银行验证步骤对应一项，适用于用户验证和企业验证。在步骤生成结果前为 `null`。每项的 `method` 说明账户的验证方式：`open_banking`（银行登录）或 `account_lookup`（账户核查），或是 `statement` 或 `microdeposits` 回退，如果在评估任何尝试前该人员未使用银行验证即继续，则为 `none`（`continued_without_bank`）。参见[银行验证方式](/zh/core-technology/bank-verification/verification-methods)。 items: $ref: '#/components/schemas/BankVerificationResult' signatures: type: array description: >- 电子签名结果，针对用户验证和企业验证（KYB），每个签署人和签名步骤对应一项。仅在工作流包含电子签名步骤时存在；在签署人到达该步骤前为空数组。请参阅[电子签名报告](/zh/core-technology/electronic-signature/report-electronic-signature)。 items: $ref: '#/components/schemas/SignatureResult' aml_screenings: type: array nullable: true description: >- **AML 筛查报告数组**：始终为 JSON 数组，绝不为单个 `aml` 对象。在至少有一个 AML 步骤生成数据之前为 `null`。每个条目均为完整报告，包含 `node_id`、功能级 `status`、`total_hits`、`entity_type`、`hits[]`、`score`、`screened_data`、`is_ongoing_monitoring_enabled` 以及 `warnings[]`。 items: $ref: '#/components/schemas/AMLScreening' ip_analyses: type: array nullable: true description: >- **设备与 IP 分析报告数组** — 始终为 JSON 数组，绝非单个 `ip_analysis` 对象。在至少有一个 IP 分析步骤生成数据之前为 `null`。每一项均为完整报告，包含 `node_id`、功能级别 `status`、IP 及地理位置数据、设备指纹以及 `warnings[]`。具有重复 `(node_id, ip_address, device_fingerprint)` 的条目会在服务端去重。 items: type: object properties: node_id: type: string description: 工作流图谱中该设备与 IP 分析步骤的唯一标识符。 status: type: string description: >- 此设备与 IP 分析条目的功能级状态。独立于顶级会话的 `status`：会话可以达成其总体决策，而单个功能仍保持 `In Review`。 enum: - Not Finished - Approved - Declined - In Review - Resub Requested device_brand: type: string description: 所使用设备的品牌 device_model: type: string description: 所用设备的型号 browser_family: type: string description: 所使用的浏览器家族 os_family: type: string description: 操作系统系列 platform: type: string description: 平台类型（mobile、desktop 等） device_fingerprint: type: string nullable: true description: 唯一设备指纹标识符 ip_country: type: string description: 根据 IP 检测到的国家/地区 ip_country_code: type: string description: 来自 IP 的两字母国家/地区代码 ip_state: type: string description: 从 IP 检测到的州/地区 ip_city: type: string description: 从 IP 检测到的城市 latitude: type: number description: IP 位置的纬度坐标 longitude: type: number description: IP 位置的经度坐标 ip_address: type: string description: IP 地址 isp: type: string nullable: true description: 互联网服务提供商 organization: type: string nullable: true description: 与 IP 关联的组织 is_vpn_or_tor: type: boolean description: IP 是否来自 VPN 或 Tor 网络 is_data_center: type: boolean description: IP 是否来自数据中心 time_zone: type: string description: 根据 IP 检测到的时区 time_zone_offset: type: string description: 时区偏移量 ip: type: object description: >- 此条目的 IP 地理定位，以及至身份证件地址和地址证明证件地址的大圆距离（km）。当任一方没有可解析的位置时，距离为 `null`。 properties: location: type: object nullable: true properties: latitude: type: number example: 41.2706327 longitude: type: number example: 1.9770097 description: 坐标，不可用时为 `null`。 distance_from_id_document: type: number nullable: true example: 23.4 distance_from_poa_document: type: number nullable: true example: 12.3 id_document: type: object description: >- 从身份证件地址中提取的位置，以及到 IP 地理位置和 POA 证件地址的距离（km）。当无法对证件地址进行地理编码时，`location` 为 `null`。 properties: location: type: object nullable: true properties: latitude: type: number example: 41.2706327 longitude: type: number example: 1.9770097 description: 坐标，不可用时为 `null`。 distance_from_ip: type: number nullable: true example: 23.4 distance_from_poa_document: type: number nullable: true example: 18.7 poa_document: type: object description: >- 从地址证明文件中提取的位置，以及到 IP 地理位置和身份证件地址的距离（km）。当会话没有 POA 步骤或地址无法进行地理编码时，`location` 为 `null`。 properties: location: type: object nullable: true properties: latitude: type: number example: 41.2706327 longitude: type: number example: 1.9770097 description: 坐标，不可用时为 `null`。 distance_from_ip: type: number nullable: true example: 12.3 distance_from_id_document: type: number nullable: true example: 18.7 warnings: type: array items: type: object properties: feature: type: string enum: - ID_VERIFICATION - NFC - LIVENESS - FACEMATCH - PROOF_OF_ADDRESS - PHONE - EMAIL - AML - LOCATION - DATABASE_VALIDATION - QUESTIONNAIRE - DOCUMENT_AI - KYB_REGISTRY - KYB_DOCUMENTS - KYB_KEY_PEOPLE - GEOLOCATION - SIGNATURE description: >- 生成此警告的功能。该值标识警告所属的功能块。每个模块的警告数组通常使用与其模块匹配的值（例如 `phone_verifications[].warnings` 内的 `PHONE`），但上述枚举在决策 payload 的所有功能警告中具有权威性。 risk: type: string additional_data: type: object nullable: true log_type: type: string short_description: type: string long_description: type: string node_id: type: string description: 生成此警告的工作流图节点 ID matches: type: array description: >- 为该条目的地址或设备标识找到的跨会话匹配项。每个匹配项都是您应用中的另一个验证会话（`source` 始终为 `session`），其共享相同的值，且始终属于与当前会话不同的供应商用户 / `vendor_data`，每个收集器上限为 5 个（`device_fingerprint` 汇总两个独立设有上限的收集器，因此最多可能有 10 个条目）。每个项目都包含 `match_source`、`confidence`、`match_mode`、`device_info` 和 `location_info`；键 `recovery_similarity`、`tls_ja4_corroborated` 和 `recovery_gate_reason` 仅在 `match_source` 为 `recovered_high` 时存在。 items: type: object additionalProperties: false properties: session_id: type: string format: uuid description: 匹配会话的会话 ID。 session_number: type: integer description: 匹配会话的序号。 vendor_data: type: string nullable: true description: 匹配会话的 `vendor_data`，始终与当前会话的供应商用户不同。 verification_date: type: string format: date-time nullable: true description: 匹配会话的创建日期（`YYYY-MM-DDTHH:MM:SSZ`）。 match_type: type: string enum: - ip_address - device_fingerprint description: 匹配项是基于 IP 地址还是设备指纹 match_source: type: string enum: - ip_address - persistent_id - legacy_fp - recovered_high description: >- 此匹配项的达成方式：`ip_address`（共享 IP 地址：网络共址，非设备身份断言）、`persistent_id`（存储的精准持久设备标识符）、`legacy_fp`（旧版 `didit-fp-*` 设备指纹哈希）或 `recovered_high`（高置信度模糊指纹恢复命中）。较低置信度的恢复候选仅作为风险警告呈现，绝不会出现在此数组中。 matched_value: type: string nullable: true description: >- 匹配的值：共享的 IP 地址、持久设备标识符或旧版指纹哈希，或者（对于 `recovered_high`）已恢复设备的 UUID。 status: type: string description: 匹配会话的生命周期状态。 is_blocklisted: type: boolean description: 匹配的值是否在黑名单中。对于设备/IP 匹配，当前始终为 `false`。 api_service: type: string nullable: true description: 匹配会话的独立 API 服务；对于工作流会话为 `null`。 source: type: string enum: - session description: 对于设备/IP 匹配，始终为 `session`，每个匹配项都是您应用中的另一个验证会话。 device_info: type: object description: 在匹配会话中观察到的设备详情。 properties: device_brand: type: string nullable: true device_model: type: string nullable: true browser_family: type: string nullable: true os_family: type: string nullable: true platform: type: string nullable: true device_fingerprint: type: string nullable: true location_info: type: object description: 在匹配会话中观察到的网络与地理位置详情。 properties: ip_address: type: string nullable: true ip_country: type: string nullable: true ip_country_code: type: string nullable: true ip_state: type: string nullable: true ip_city: type: string nullable: true is_vpn_or_tor: type: boolean is_data_center: type: boolean confidence: type: number minimum: 0 maximum: 1 description: >- 服务端识别置信度，计算公式为 `1 - P(false positive)`：确定性匹配为 `1.0`（`persistent_id` 或基于硬件根的 `recovered_high`），`legacy_fp` 为 `0.5`，`ip_address`（仅限同一位置）为 `0.0`，概率恢复匹配为低于 `1.0` 的佐证调整值（当 TLS JA4 指纹和 IP 所在国家/地区独立一致时更高）。 match_mode: type: string enum: - deterministic - probabilistic - co_occurrence description: >- 匹配的证据类别：`deterministic`（精确存储或基于硬件的标识符，在物理设备之间无法发生碰撞）、`probabilistic`（模糊指纹证据）或 `co_occurrence`（仅共享网络，无设备身份认定）。 recovery_similarity: type: number description: >- 指纹恢复匹配的余弦相似度，四舍五入保留 4 位小数。仅在 `match_source` 为 `recovered_high` 时存在。 tls_ja4_corroborated: type: boolean description: >- 两次观测的 TLS JA4 指纹是否一致，这是服务器观测到的信号，浏览器无法伪造。仅在 `match_source` 为 `recovered_high` 时存在。 recovery_gate_reason: type: string description: >- 恢复匹配通过误报硬性门禁的原因：`hardware_root_match`（基于硬件根的设备标识符完全匹配），或在允许仅探针证据的配置上为 `exact_composite_plus__families` / `very_high_similarity_plus__families`。仅当 `match_source` 为 `recovered_high` 时存在。 browser_version: type: string nullable: true os_version: type: string nullable: true user_agent: type: string nullable: true description: 浏览器的用户代理字符串。 accept_language: type: string nullable: true description: 浏览器发送的 `Accept-Language` 请求头。 session_identifier: type: string nullable: true description: 运行验证的浏览会话的标识符。 session_age_ms: type: integer nullable: true description: 运行该步骤时该浏览会话的时长（毫秒）。 coords_accuracy: type: number nullable: true description: 设备报告的坐标精度半径（以米为单位）。 raw_device_data: type: object nullable: true additionalProperties: true description: 为此步骤收集的原始设备信号。 geolocation_checks: type: array nullable: true description: >- **位置验证结果数组**，每个位置验证步骤对应一项：即该步骤已接受的尝试。在位置验证步骤生成数据之前为 `null`。同一步骤先前的尝试位于 `geolocation_attempts` 中。 items: $ref: '#/components/schemas/GeolocationCheck' geolocation_attempts: type: array nullable: true description: >- 该会话中每个位置验证步骤的每次尝试，按时间正序排列。被重新提交所取代的尝试会被排除在外。如果工作流通过其响应属性隐去了 `geolocation_checks`，则该列表也会被隐去。 items: $ref: '#/components/schemas/GeolocationAttempt' database_validations: type: array nullable: true description: >- **数据库核验报告数组** — 始终为 JSON 数组，绝非单独的 `database_validation` 对象。在至少有一个数据库核验步骤生成数据之前为 `null`。每一项均为完整报告，包含 `node_id`、功能级别的 `status`、`screened_data`、按服务划分的 `validations[]`（各项均包含其登记机构的 `source_data`）以及 `warnings[]`。`screened_data` 和 `source_data` 字段因国家/地区而异： **ARG（阿根廷）**：screened_data: {document_number, selfie, gender, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name, date_of_birth, date_of_death, tax_id, tax_id_type, face_match_score, sit_1_since, banks, last_position, highest_position, rejected_checks}。使用 RENAPER 生物识别人脸比对核验。当证件（例如驾照）中未包含性别时，会通过人脸分析或名字自动推断性别 **BOL（玻利维亚）**：screened_data: {document_number, date_of_birth, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name, date_of_birth, gender} **BRA（巴西）**：screened_data: {tax_number, first_name, last_name, date_of_birth}。对于成功的 CPF 匹配，source_data 始终包含 {identification_number, first_name, last_name, date_of_birth, lgpd_minor, minor_under_18, minor_under_16}。成功的成年人查询会将这些标志设置为 false。Receita Federal Consulta CPF 服务可能会返回 HTTP 422（未满 18 岁未成年人）或 451（未满 16 岁）并附带因 LGPD 而不提供的数据；在这些情况下，source_data 会相应地将未成年人标志设置为 true，包含上游 HTTP 状态，且字段级核验为 no_match。有关完整代码列表，请参阅数据库核验结果代码参考中的巴西部分。 **CHL（智利）**：screened_data: {personal_number, first_name, last_name, date_of_birth}。source_data: {identification_number, first_name, last_name, date_of_birth, gender} **COL（哥伦比亚）**：screened_data: {document_number, document_type, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name, date_of_birth, document_type} **CRI（哥斯达黎加）**：screened_data: {personal_number, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name} **DOM（多米尼加共和国）**：screened_data: {personal_number}。source_data: {identification_number}（仅返回有效/无效） **ECU（厄瓜多尔）**：screened_data: {personal_number, first_name, last_name}。source_data: {identification_number, first_name, last_name, street, formatted_address, gender, nationality, education, marital_status, spouse, mother_name, father_name, profession} **ESP（西班牙）**：screened_data: {personal_number, document_type, expiration_date, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name, document_type, expiration_date} **GTM（危地马拉）**：screened_data: {document_number, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name} **HND（洪都拉斯）**：screened_data: {document_number, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name} **MEX（墨西哥）**：screened_data: {personal_number (CURP), first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name, date_of_birth, gender, nationality, curp_status, state_of_birth, doc_probatorio, registration_year, registration_state, registration_municipality, num_acta, crip, issuing_state_code, foreign_registry_number, folio_carta, folio_certificado}。使用 RENAPO 民事登记处。对于 MEX，还提供单独的 INE 有效性检查服务作为额外的逐一核验。 **PAN（巴拿马）**：screened_data: {personal_number, selfie}。source_data: {identification_number}。使用 SIB 生物识别核验 **PER（秘鲁）**：screened_data: {personal_number (DNI), first_name, last_name}。source_data: {identification_number, first_name, last_name, paternal_name, maternal_name, verification_number, verification_letter} **PRY（巴拉圭）**：screened_data: {document_number, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name} **SLV（萨尔瓦多）**：screened_data: {document_number, date_of_birth, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name} **URY（乌拉圭）**：screened_data: {personal_number, date_of_birth, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name} **VEN（委内瑞拉）**：screened_data: {document_number, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name, gender, date_of_birth, document_type} items: type: object properties: node_id: type: string description: 工作流图谱中此数据库核验步骤的唯一标识符。 issuing_state: type: string description: >- 已查询其政府/登记机构数据源的国家/地区的 ISO 3166-1 alpha-3 代码（例如 `BRA`、`MEX`、`ESP`、`NGA`、`IDN`）。数据库核验覆盖美洲、欧洲、非洲、中东和亚太地区的 60+ 个国家/地区，以及全球多国数据源；覆盖范围定期扩展，因此请将该值视为开放集合而非固定枚举。 validation_type: type: string enum: - one_by_one - two_by_two - not_enabled description: >- 结果的交叉核验方式：`one_by_one`（单一服务结果）、`two_by_two`（两个或更多不同服务独立完全匹配证件号码）或 `not_enabled`（当没有服务产生可用匹配时保留）。该值绝不为 `null`。专用的生物识别 2x2 验证模式目前适用于 `ECU` 和 `PER`。 screened_data: type: object description: >- 用于核验的输入数据。字段因国家/地区而异，请参阅数据库核验文档（`/core-technology/database-validation/overview`）了解特定国家/地区的格式。 properties: last_name: type: string first_name: type: string tax_number: type: string description: 巴西：CPF（11 位数字） personal_number: type: string description: >- 智利：RUT，多米尼加共和国：Cédula（11 位数字），厄瓜多尔：Cédula（10 位数字），西班牙：DNI/NIE，墨西哥：CURP（18 个字符），秘鲁：DNI（8 位数字），乌拉圭：CI document_number: type: string description: >- ARG: DNI, BOL: CI, COL: Cédula, GTM: DPI, HND: DNI, PAN: Cédula, PRY: CI, SLV: DUI, VEN: Cédula date_of_birth: type: string format: date document_type: type: string description: 'COL: CC/CE/TI/NIT, ESP: ID/PASSPORT' expiration_date: type: string format: date description: ESP 必需 validations: type: array description: >- 返回验证 payload 的每个登记服务对应一个条目。每个条目标识该服务（`service_id`、`service_name`），并包含逐字段的 `validation` 比对结果、服务上报时的 `outcome_code` / `outcome_detail`，以及 `source_data` 中的标准化登记记录。 items: type: object properties: service_id: type: string description: 生成此验证结果的登记处服务的标识符。 example: bra_cpf service_name: type: string description: 登记机构服务便于人类阅读的名称。 example: Brazil - CPF status check validation: type: object description: 字段验证的结果。 properties: full_name: type: string description: 姓名的比对结果（例如，'full_match'、'partial_match'、'no_match'）。 date_of_birth: type: string description: 出生日期的比对结果。 identification_number: type: string description: 身份证件号码的比对结果。 outcome_code: type: string nullable: true description: >- 公司登记查询的机器可读结果（例如 `MATCH`、`NO_MATCH`、`PARTIAL_MATCH`、`INCONCLUSIVE`、特定于数据源的代码）。在服务报告此类结果时提供。 outcome_detail: type: string nullable: true description: '`outcome_code` 的便于人类阅读的说明（由服务提供时）。' source_data: type: object description: >- 从政府数据库返回的数据。通用字段：identification_number、first_name、last_name、full_name、date_of_birth、gender。按国家/地区划分的附加字段：BRA 在 CPF 匹配成功时始终包含 lgpd_minor、minor_under_18 和 minor_under_16；当 CPF 数据根据 LGPD 被扣留时，它还包含上游 HTTP 状态（HTTP 422/451）。ECU 增加 street、formatted_address、nationality、education、marital_status、spouse、mother_name、father_name、profession。PER 增加 paternal_name、maternal_name、verification_number、verification_letter。ESP 增加 document_type、expiration_date。VEN/COL 增加 document_type。 additionalProperties: true errors: type: array description: 核验时登记机构服务返回的错误，每个错误均标记有生成它的 `service_id`。**当没有错误时，该键会被完全省略。** items: type: object description: >- 按原样展开的上游服务错误对象（其键名因服务而异，通常包含 message/code 以及任何提供商特有的详细信息），外加标识出错服务的 `service_id`。 properties: service_id: type: string nullable: true description: 报错的登记处服务的标识符。 additionalProperties: true match_type: type: string enum: - no_match - partial_match - full_match nullable: true description: 所查询各服务的综合匹配结果。在核验被评估之前为 `null`。 status: type: string description: >- 此数据库核验的功能级状态。独立于顶级会话的 `status`：会话可以达成其总体决策，而单个功能仍保持 `In Review`。 enum: - Not Finished - Approved - Declined - In Review - Resub Requested warnings: type: array items: type: object properties: feature: type: string enum: - ID_VERIFICATION - NFC - LIVENESS - FACEMATCH - PROOF_OF_ADDRESS - PHONE - EMAIL - AML - LOCATION - DATABASE_VALIDATION - QUESTIONNAIRE - DOCUMENT_AI - KYB_REGISTRY - KYB_DOCUMENTS - KYB_KEY_PEOPLE - GEOLOCATION - SIGNATURE description: >- 生成此警告的功能。该值标识警告所属的功能块。每个模块的警告数组通常使用与其模块匹配的值（例如 `phone_verifications[].warnings` 内的 `PHONE`），但上述枚举在决策 payload 的所有功能警告中具有权威性。 risk: type: string additional_data: type: object nullable: true log_type: type: string short_description: type: string long_description: type: string node_id: type: string description: 生成此警告的工作流图节点 ID description: 与数据库核验相关的警告。 database_validation_not_performed_reason: type: object nullable: true additionalProperties: true description: >- 已配置的数据库核验未产生结果的原因，格式为 `{code, message}` 加上上下文字段。仅在包含该步骤的工作流中 `database_validations` 为 `null` 时存在，以便您能够区分“登记机构核对一致”与“未运行任何核验”。其他情况下为 `null`。 properties: code: type: string description: 稳定的机器可读原因。 message: type: string description: 便于人类阅读的说明。 reviews: type: array items: type: object properties: user: type: string description: >- 执行审核的人员。通常是控制台审核员的标识符（其邮箱），但对于使用 API 密钥进行的状态更新，该值为 `"API Client"`；当无法解析执行者时，该值为 `"Unknown"`，因此请勿将此字段解析为邮箱地址。 new_status: type: string comment: type: string created_at: type: string format: date-time assignee: type: object nullable: true description: 会话所分配到的控制台审核员，未分配给任何人时为 `null`。 properties: email: type: string format: email assigned_at: type: string format: date-time nullable: true waiting_since: type: string format: date-time nullable: true description: 会话开始等待审核的时间。除非会话为 `In Review` 且您的应用设置了审核截止期限，否则为 `null`。 sla_due_at: type: string format: date-time nullable: true description: 审核截止时间。除非会话为 `In Review` 且您的应用设置了审核截止期限，否则为 `null`。 created_at: type: string format: date-time description: 会话创建时的时间戳（ISO 8601，UTC）。 expires_at: type: string format: date-time nullable: true description: >- 该会话计划过期的时间戳。在创建时配置了过期时间的用户验证（KYC）会话上设置（或者一旦 `Approved` 状态触发 KYC 过期计算）。对于未配置过期的会话以及不使用过期的类型（例如从未接收到 `expires_at` 的企业验证（KYB）会话）为 `null`。 registry_checks: type: array nullable: true description: 公司登记核验。仅在 `session_kind = business` 时存在。每一项都封装了完整的公司登记 payload。 items: type: object description: >- 一次公司登记核验：包含股权结构与警告信息的完整公司登记 payload。仅在 `session_kind = business` 时存在。 properties: status: type: string description: 功能生命周期状态。 node_id: type: string nullable: true data_resolved: type: boolean company: type: object description: 企业的完整公司登记 payload（公司登记记录与任何用户提供或控制台编辑的数据合并）。 properties: uuid: type: string format: uuid node_id: type: string nullable: true status: type: string registry_status: type: string nullable: true data_resolved: type: boolean company_name: type: string registration_number: type: string nullable: true country_code: type: string description: 注册国家/地区（ISO 3166-1 alpha-2，例如 `GB`、`DE`、`US`）。 region: type: string nullable: true description: 适用的 ISO 3166-2 行政区划代码（例如美国各州的 `CA`、`NY`）。 company_type: type: string nullable: true incorporation_date: type: string format: date nullable: true registered_address: type: string nullable: true tax_number: type: string nullable: true risk_level: type: string enum: - LOW - MEDIUM - HIGH nullable: true verification_status: type: string nullable: true is_from_registry: type: boolean fetch_status: type: string nullable: true alternative_names: type: string nullable: true description: 上报时的替代名称、商业名称、曾用名或原始语言公司名称（文本格式）。 nature_of_business: type: string nullable: true registered_capital: type: string nullable: true registered_capital_amount: type: string format: decimal nullable: true description: >- 从公司登记备案中解析出的注册资本/股本金额，表示为十进制字符串（例如 `"100.00"`）。不可用时为 `null`。 registered_capital_currency: type: string nullable: true description: >- `registered_capital_amount` 的 ISO 4217 货币代码（例如 `"GBP"`）。不可用时为 `null`。 website: type: string nullable: true email: type: string format: email nullable: true phone: type: string nullable: true legal_entity_identifier: type: string nullable: true location_of_registration: type: string nullable: true vat_number: type: string nullable: true description: 欧盟增值税号（EU VAT number），在托管登记步骤中收集或随后编辑时提供。 vat_validation_status: type: string enum: - valid - invalid - format_valid - invalid_format - could_not_validate - not_applicable description: >- 在登记提交时验证增值税号（若无，则为 `tax_number`）的结果。`valid` / `invalid`：由相应国家/地区的官方登记处判定（欧盟 VIES、挪威、瑞士、巴西、哥伦比亚、哥斯达黎加、厄瓜多尔、巴拉圭；波兰还由其国内增值税登记册判定）。`format_valid` / `invalid_format`：在无法查询登记处时，由该国家/地区的格式和校验位规则判定。`could_not_validate`：登记处不可用。`not_applicable`：无号码、无登记处或规则的国家/地区，或者沙盒会话。 vat_validated_number: type: string nullable: true description: >- 已核验的号码，格式以数据源所知为准（例如从法国 SIREN 或荷兰 RSIN 派生的增值税号）。若未运行核验，则为 `null`。 vat_validation_source: type: string nullable: true enum: - eu_vies - pl_vat_white_list - no_brreg - ch_uid_register - br_receita_federal - co_rues - cr_hacienda - ec_sri - py_dnit - format_rules - null description: >- 判定 `vat_validation_status` 的来源：官方登记，或 `format_rules`。未运行任何检查时为 `null`。 vat_validated_name: type: string nullable: true description: 向验证该号码的数据源登记的名称（如果该数据源公开名称）。仅当状态为 `valid` 时设置。 vat_validated_address: type: string nullable: true description: 核验该号码的数据源中登记的地址（若该数据源披露）。仅在状态为 `valid` 时设置。 vat_checked_at: type: string format: date-time nullable: true description: 检查的时间戳。未运行检查时为 `null`。 financial_summary: type: object nullable: true officers: type: array items: type: object properties: uuid: type: string format: uuid name: type: string designation: type: string nullable: true role: type: string nullable: true nationality: type: string nullable: true is_active: type: boolean kyc_status: type: string enum: - Approved - Declined - Pending nullable: true kyc_session_url: type: string format: uri nullable: true first_name: type: string nullable: true description: 公司登记明确报告时的名字；并非从全名中推断。 last_name: type: string nullable: true description: 公司登记明确报告时的姓氏。 address: type: string nullable: true description: 登记处报告的官员地址。 appointment_date: type: string nullable: true description: 管理人员被任命的日期。 format: date termination_date: type: string nullable: true description: 任期结束的日期（若有报告）。 format: date date_of_birth: type: string nullable: true description: 公司登记报告的完整出生日期。如果仅已知出生年份或月份，则为 null。 format: date date_of_birth_year: type: integer nullable: true minimum: 1 maximum: 9999 description: 公司登记所报告的出生年份，包括完整日期不可用的情况。 date_of_birth_month: type: integer nullable: true minimum: 1 maximum: 12 description: 公司登记所报告的出生月份。仅知晓年份时为 null。 beneficial_owners: type: array items: type: object properties: uuid: type: string format: uuid name: type: string first_name: type: string nullable: true last_name: type: string nullable: true entity_type: type: string enum: - person - company roles: type: array items: type: string ownership_min_shares: type: string nullable: true description: >- 公司登记报告的股权百分比下限。自由格式字符串（例如 `"25.00"`、`"50"`）；使用 `effective_ownership_percent` 获取解析后的数值。 ownership_max_shares: type: string nullable: true description: >- 公司登记报告的持股比例上限。自由格式字符串；解析后的数值请使用 `effective_ownership_percent`。 is_active: type: boolean kyc_status: type: string enum: - Approved - Declined - Pending nullable: true kyc_session_url: type: string format: uri nullable: true effective_ownership_percent: type: number nullable: true company_name: type: string nullable: true registration_number: type: string nullable: true country_of_birth: type: string nullable: true email: type: string nullable: true nationality: type: string nullable: true designation: type: string nullable: true voting_min_shares: type: string nullable: true voting_max_shares: type: string nullable: true date_of_birth: type: string nullable: true description: 完整的出生日期（如有报告）。 format: date appointment_date: type: string nullable: true description: 有报告时的委任日期。 format: date shareholding: $ref: '#/components/schemas/KYBRegistryShareholding' addresses: type: array nullable: true description: 登记处注明的每个地址，采用标准规范格式。如果未注明，则为 null。 items: $ref: '#/components/schemas/KYBRegistryAddress' industries: type: array nullable: true description: 登记机构对企业进行分类的业务活动，采用一种规范化格式。若未注明则为 null。 items: $ref: '#/components/schemas/KYBRegistryIndustry' accounts: type: object nullable: true additionalProperties: true description: >- 公司登记备案日期（如可用）。年度申报表和大会使用 last_annual_return_date 与 last_agm_date；它们与财务账目不同。 registry_data: $ref: '#/components/schemas/KYBRegistryData' user_provided_data: type: object description: 由终端用户确认或编辑的数据。 confirmed_by_user_at: type: string format: date-time nullable: true last_console_edit_at: type: string format: date-time nullable: true is_editable: type: boolean ownership: $ref: '#/components/schemas/KYBRegistryOwnership' registry_tier: type: string nullable: true description: >- 工作流订购的公司登记等级：`basic`、`shareholders` 或 `ubo`。也可在 `ownership.tier_requested` 中查看。 registry_tier_delivered: type: string nullable: true description: 登记机构交付且计费的等级。亦包含在 `ownership.tier_delivered` 中。 registry_ownership_status: type: string nullable: true description: >- `not_requested`、`pending`、`delivered`、`not_held` 或 `unavailable`。同样适用于 `ownership.status`。 registry_monitoring: type: object nullable: true description: 该企业的最新登记监控，不存在时为 `null`。 properties: uuid: type: string format: uuid status: type: string unavailable_reason: type: string nullable: true enrolled_at: type: string format: date-time nullable: true cancelled_at: type: string format: date-time nullable: true last_bill_date: type: string format: date nullable: true next_bill_date: type: string format: date nullable: true last_event_at: type: string format: date-time nullable: true events_count: type: integer watched_fields: description: 监控器监视的企业字段。 ownership_structure: $ref: '#/components/schemas/KYBOwnershipStructure' warnings: type: array items: type: object key_people_checks: type: array nullable: true description: >- 汇总的关键人员核验。仅在 `session_kind = business` 时存在。每个条目均使用双分组格式（`registry`、`submitted`、`ubo_kyc_summary`）。 items: type: object description: >- 对公司高级管理人员 + 实际受益人的综合核验。使用 `registry` / `submitted` 格式。仅在 session_kind = business 时提供。 properties: status: type: string node_id: type: string nullable: true registry: type: object description: 通过登记处核验发现的当事方。 properties: officers: type: array description: 通过公司登记核验发现的官员，每位官员均附带有为其生成的子 KYC 会话和 AML 筛查的状态。 items: type: object properties: uuid: type: string format: uuid name: type: string description: 登记处记录的官员姓名。 designation: type: string nullable: true description: 来自登记机构的自由文本职务（例如 `Director`、`Company Secretary`）。 role: type: string enum: - director - non_executive_director - secretary - chairman - ubo - shareholder - representative - founder - legal_advisor - authorized_signatory - trustee - beneficiary - settlor - protector - company_officer - investor - other description: 归一化的职员角色。 nationality: type: string nullable: true appointment_date: type: string nullable: true description: 管理人员被任命的日期。 format: date termination_date: type: string nullable: true description: 任期结束的日期（若有报告）。 format: date is_active: type: boolean address: type: string nullable: true description: 登记处报告的官员地址。 aml_status: type: string enum: - Not Finished - Approved - Declined - In Review - Resub Requested nullable: true description: 为此负责人运行的 AML 筛查状态。未运行 AML 筛查时为 `null`。 kyc_status: type: string enum: - Not Started - In Progress - Approved - Declined - In Review - Expired - Abandoned - Kyc Expired - Resubmitted - Awaiting User nullable: true description: >- 为此管理人员生成的子 KYC 会话的原始生命周期状态。这是完整的会话状态枚举（并非缩减的 Approved/Declined/Pending 集合）。如果不存在子 KYC 会话，则为 `null`。 kyc_session_url: type: string format: uri nullable: true description: 子 KYC 会话的可共享 URL。不存在子会话时为 `null`。 kyc_session_id: type: string format: uuid nullable: true description: >- 子 KYC 会话的会话 id。将其传递给同一个决策 endpoint 以获取该人员的完整 KYC 报告。如果不存在子会话，则为 `null`。 verification_workflow_type: type: string nullable: true description: 子会话工作流的基础工作流类型（例如 `kyc`）。对于基于图谱的工作流或不存在子会话时为 `null`。 verification_workflow_id: type: string format: uuid nullable: true description: 子会话使用的工作流 ID。不存在子会话时为 `null`。 verification_workflow_label: type: string nullable: true description: 子会话工作流便于人类阅读的标签。未设置时为 `null`。 verification_workflow_features: type: array nullable: true description: >- 子验证会话按功能划分的进度，例如 `[{"feature": "ID_VERIFICATION", "status": "Approved"}]`。当子会话没有可解析的功能列表时为 `null`。 items: type: object properties: feature: type: string description: 功能显示名称（例如 `ID_VERIFICATION`、`LIVENESS`、`AML`）。 status: type: string enum: - Not Finished - Approved - Declined - In Review - Resub Requested description: 子会话内的功能级状态。 didit_internal_id: type: string nullable: true description: >- 子会话背后已验证个人的稳定内部标识符 — 用于跨会话关联。当子会话不存在或用户尚未解析时为 `null`。 kyc_document_type: type: string nullable: true description: >- 子 KYC 会话中出示的证件类型（例如 `P`、`ID`、`DL`）。在子会话获得身份证件验证结果之前为 `null`。 kyc_nationality: type: string nullable: true description: 从子 KYC 会话中的证件提取的国籍。在可用前为 `null`。 kyc_liveness_passed: type: boolean nullable: true description: 子 KYC 会话的活体检测是否通过。未运行活体检测时为 `null`。 kyc_verified_at: type: string format: date-time nullable: true description: 子 KYC 会话达到 `Approved` 的时间。当子会话处于任何其他状态时为 `null`。 kyc_aml_categories: type: object nullable: true description: 根据个人的 AML 命中情况按类别汇总的摘要。无命中时为 `null`。 properties: sanctions: type: string enum: - match - clear pep: type: string enum: - match - clear adverse_media: type: string enum: - match - clear warnings: type: string enum: - match - clear kyc_notification_sent_at: type: string nullable: true description: 为该人员的子会话发送上一条验证邀请通知的 ISO 8601 时间戳。未发送时为 `null`。 first_name: type: string nullable: true description: 公司登记明确报告时的名字；并非从全名中推断。 last_name: type: string nullable: true description: 公司登记明确报告时的姓氏。 date_of_birth: type: string nullable: true description: 公司登记报告的完整出生日期。如果仅已知出生年份或月份，则为 null。 format: date date_of_birth_year: type: integer nullable: true minimum: 1 maximum: 9999 description: 公司登记所报告的出生年份，包括完整日期不可用的情况。 date_of_birth_month: type: integer nullable: true minimum: 1 maximum: 12 description: 公司登记所报告的出生月份。仅知晓年份时为 null。 beneficial_owners: type: array description: 通过登记处核查发现的实际受益人，每个受益人均补充了为其生成的任何子 KYC 会话和 AML 筛查的状态。 items: type: object properties: uuid: type: string format: uuid name: type: string description: 实际受益人姓名（如果是企业 UBO 则为公司名称）。 first_name: type: string nullable: true last_name: type: string nullable: true date_of_birth: type: string nullable: true description: 完整的出生日期（如有报告）。 format: date country_of_birth: type: string nullable: true email: type: string nullable: true company_name: type: string nullable: true registration_number: type: string nullable: true entity_type: type: string enum: - person - company nationality: type: string nullable: true designation: type: string nullable: true roles: type: array description: 该所有者持有的角色名称，例如 `["ubo", "shareholder"]`。 items: type: string ownership_min_shares: type: string nullable: true description: >- 公司登记报告的股权百分比下限。自由格式字符串（例如 `"25"`、`"25-50%"`）；使用 `effective_ownership_percent` 获取解析后的数值。 ownership_max_shares: type: string nullable: true description: >- 公司登记报告的持股比例上限。自由格式字符串；解析后的数值请使用 `effective_ownership_percent`。 is_active: type: boolean aml_status: type: string enum: - Not Finished - Approved - Declined - In Review - Resub Requested nullable: true description: 为此实际受益人运行的 AML 筛查状态。未运行 AML 筛查时为 `null`。 kyc_status: type: string enum: - Not Started - In Progress - Approved - Declined - In Review - Expired - Abandoned - Kyc Expired - Resubmitted - Awaiting User nullable: true description: >- 为此实际受益人生成的子 KYC 会话的原始生命周期状态。这是完整的会话状态枚举（并非缩减的 Approved/Declined/Pending 集合）。如果不存在子 KYC 会话，则为 `null`。 kyc_session_url: type: string format: uri nullable: true description: 子 KYC 会话的可共享 URL。不存在子会话时为 `null`。 kyc_session_id: type: string format: uuid nullable: true description: >- 子 KYC 会话的会话 id。将其传递给同一个决策 endpoint 以获取该人员的完整 KYC 报告。如果不存在子会话，则为 `null`。 verification_workflow_type: type: string nullable: true description: 子会话工作流的基础工作流类型（例如 `kyc`）。对于基于图谱的工作流或不存在子会话时为 `null`。 verification_workflow_id: type: string format: uuid nullable: true description: 子会话使用的工作流 ID。不存在子会话时为 `null`。 verification_workflow_label: type: string nullable: true description: 子会话工作流便于人类阅读的标签。未设置时为 `null`。 verification_workflow_features: type: array nullable: true description: >- 子验证会话按功能划分的进度，例如 `[{"feature": "ID_VERIFICATION", "status": "Approved"}]`。当子会话没有可解析的功能列表时为 `null`。 items: type: object properties: feature: type: string description: 功能显示名称（例如 `ID_VERIFICATION`、`LIVENESS`、`AML`）。 status: type: string enum: - Not Finished - Approved - Declined - In Review - Resub Requested description: 子会话内的功能级状态。 didit_internal_id: type: string nullable: true description: >- 子会话背后已验证个人的稳定内部标识符 — 用于跨会话关联。当子会话不存在或用户尚未解析时为 `null`。 kyc_document_type: type: string nullable: true description: >- 子 KYC 会话中出示的证件类型（例如 `P`、`ID`、`DL`）。在子会话获得身份证件验证结果之前为 `null`。 kyc_nationality: type: string nullable: true description: 从子 KYC 会话中的证件提取的国籍。在可用前为 `null`。 kyc_liveness_passed: type: boolean nullable: true description: 子 KYC 会话的活体检测是否通过。未运行活体检测时为 `null`。 kyc_verified_at: type: string format: date-time nullable: true description: 子 KYC 会话达到 `Approved` 的时间。当子会话处于任何其他状态时为 `null`。 kyc_aml_categories: type: object nullable: true description: 根据个人的 AML 命中情况按类别汇总的摘要。无命中时为 `null`。 properties: sanctions: type: string enum: - match - clear pep: type: string enum: - match - clear adverse_media: type: string enum: - match - clear warnings: type: string enum: - match - clear kyc_notification_sent_at: type: string nullable: true description: 为该人员的子会话发送上一条验证邀请通知的 ISO 8601 时间戳。未发送时为 `null`。 child_beneficial_owners: type: array description: 对于企业 UBO：拥有实体自身的实际受益人，表示为从登记机构提取的原始对象。不适用时为空数组。 items: type: object effective_ownership_percent: type: number nullable: true description: 解析出的数值型股权百分比：可用时为上限值，否则为下限值。当两个边界都无法解析时为 `null`。 voting_min_shares: type: string nullable: true voting_max_shares: type: string nullable: true appointment_date: type: string nullable: true description: 有报告时的委任日期。 format: date submitted: type: object description: 企业管理员在关键人员流程中提交的当事方（source=USER 的 BusinessParty 行）。 properties: parties: type: array items: type: object description: 企业管理员通过关键人员流程提交的当事方（source=USER）。 properties: uuid: type: string format: uuid entity_type: type: string enum: - person - company source: type: string enum: - USER description: >- 此处始终为 `USER` — 此存储桶仅包含终端用户在关键人员流程中输入或确认的主体（从公司登记中发现的人员显示在 `registry` 下）。 name: type: string first_name: type: string nullable: true last_name: type: string nullable: true company_name: type: string nullable: true registration_number: type: string nullable: true email: type: string format: email nullable: true nationality: type: string nullable: true description: 个人为国籍；企业主体为注册成立国家/地区。 phone_number: type: string nullable: true date_of_birth: type: string format: date nullable: true position: type: string nullable: true description: 自由文本职位/头衔（仅限个人）。 custom_fields: type: object description: 为此方收集的工作流定义自定义字段；键由工作流的关键人员字段描述符定义。 is_active: type: boolean is_skipped: type: boolean description: 当终端用户跳过了对此当事方的验证时为 true（仅当角色允许跳过时才可能）。 requires_verification: type: boolean description: 根据角色设置和股权结构阈值，需要为此当事方创建子 KYC / KYB 子会话时为 true。 roles: type: array description: >- 该主体担任的所有角色，每个角色均有其自身的股权结构百分比和投票权百分比。主体本身没有标量 `role`/`ownership_percent`。 items: type: object properties: role: type: string enum: - director - non_executive_director - secretary - chairman - ubo - shareholder - representative - founder - legal_advisor - authorized_signatory - trustee - beneficiary - settlor - protector - company_officer - investor - other ownership_percent: type: number nullable: true voting_percent: type: number nullable: true kyc_session_id: type: string format: uuid nullable: true description: 需要验证的个人当事方的子 KYC 会话 ID。否则为 `null`。 kyc_session_status: type: string enum: - Not Started - In Progress - Approved - Declined - In Review - Expired - Abandoned - Kyc Expired - Resubmitted - Awaiting User nullable: true description: 子 KYC 会话的生命周期状态。不存在子 KYC 会话时为 `null`。 kyc_session_url: type: string format: uri nullable: true kyb_sub_session_id: type: string format: uuid nullable: true description: 需要验证的企业当事方的子 KYB 子会话 ID。否则为 `null`。 kyb_sub_session_status: type: string enum: - Not Started - In Progress - Approved - Declined - In Review - Expired - Abandoned - Kyc Expired - Resubmitted - Awaiting User nullable: true description: KYB 子会话的生命周期状态。不存在子会话时为 `null`。 kyb_sub_session_url: type: string format: uri nullable: true description: 子 KYB 子会话的可共享 URL。不存在子会话时为 `null`。 verification_workflow_type: type: string nullable: true description: >- 子会话工作流的基础工作流类型（优先取 KYC 会话，回退到 KYB 子会话）。对于基于图谱的工作流或不存在子会话时为 `null`。 verification_workflow_id: type: string format: uuid nullable: true description: 子会话使用的工作流 ID。不存在子会话时为 `null`。 verification_workflow_label: type: string nullable: true description: 子会话工作流便于人类阅读的标签。未设置时为 `null`。 verification_workflow_features: type: array nullable: true description: >- 子验证会话按功能划分的进度，例如 `[{"feature": "ID_VERIFICATION", "status": "Approved"}]`。当子会话没有可解析的功能列表时为 `null`。 items: type: object properties: feature: type: string description: 功能显示名称（例如 `ID_VERIFICATION`、`LIVENESS`、`AML`）。 status: type: string enum: - Not Finished - Approved - Declined - In Review - Resub Requested description: 子会话内的功能级状态。 didit_internal_id: type: string nullable: true description: 子会话背后已验证个人的稳定内部标识符。未解析时为 `null`。 ubo_kyc_summary: type: object nullable: true description: 汇总的实际受益人 KYC 进度；当没有实际受益人关联 KYC 会话时为 null。 properties: total: type: integer approved: type: integer flagged: type: integer description: KYC 状态为已拒绝或审核中的实际受益人。 pending: type: integer warnings: type: array items: type: object document_verifications: type: array nullable: true description: 按工作流节点分组的证件验证检查。仅在 `session_kind = business` 时提供。 items: type: object description: 按工作流节点分组的证件。仅在 session_kind = business 时提供。 properties: status: type: string node_id: type: string nullable: true items: type: array items: type: object properties: uuid: type: string format: uuid document_type: type: string enum: - LEGAL_PRESENCE - COMPANY_DETAILS - OWNERSHIP_STRUCTURE - REPRESENTATIVES_AUTHORIZATION - OTHER nullable: true description: 该文件被分类归入的高级 KYB 证件组。未分类时为 `null`。 document_subtype: type: string nullable: true description: >- OCR 检测出的特定子类型（例如 `CERTIFICATE_OF_INCORPORATION`、`SHAREHOLDER_REGISTRY`）；当 OCR 无法高置信度分类证件时为 `UNKNOWN`。 document_group: type: string enum: - LEGAL_PRESENCE - COMPANY_DETAILS - OWNERSHIP_STRUCTURE - REPRESENTATIVES_AUTHORIZATION - OTHER nullable: true description: >- `document_type` 的别名：`groups` 和 `required_groups` 使用的分组名称。 file_url: type: string format: uri nullable: true description: >- 已上传文件的短期预签名链接。对于分析师创建且尚未完成的证件请求占位符（`is_requested = true`），此值为 `null`。 original_filename: type: string nullable: true description: 用户或分析师上传时的文件名。 file_size: type: integer nullable: true description: 文件大小（字节）。 status: type: string enum: - Not Finished - Approved - Declined - In Review - Resub Requested description: 按证件划分的验证状态。 created_at: type: string format: date-time cross_check_result: type: object nullable: true description: >- OCR 提取的证件字段与公司登记企业档案的交叉比对。一个包含 `critical`、`non_critical` 和 `people` 部分的对象，各部分将字段名称（例如 `company_name`、`registration_number`、`incorporation_date`、`registered_address`）映射到形如 `{"document": "...", "registry": "...", "match": true, "score": 0.97}` 的比对记录。当证件没有 OCR 数据或没有可比对的公司登记企业时为 `null`。 document_metadata: type: object nullable: true description: >- 从上传的企业证件中提取的元数据。当元数据提取成功时，所有 16 个键均始终存在（对该文件类型不适用的个别值设为 `null`）；当无法提取任何内容时，整个对象为 `null`。对于 PDF，`overlay_manipulation` 包含图层覆盖文本的取证分析。 properties: file_size: type: integer nullable: true description: 证件大小。 content_type: type: string nullable: true description: 证件的内容类型。 creation_date: type: string nullable: true description: 证件创建的日期。 modified_date: type: string nullable: true description: 证件修改的日期。 creator: type: string nullable: true description: 文件元数据中记录的编写工具/用户（PDF `Creator`）。 producer: type: string nullable: true description: 生成文件的软件（PDF `Producer`）。 software: type: string nullable: true description: 文件元数据中记录的编辑软件。 encryption: type: string nullable: true description: 文件加密时的加密方案。 is_signed: type: boolean nullable: true description: 证件是否带有数字签名。 is_tampered: type: boolean nullable: true description: 数字签名是否验证失败（签名后被篡改）。 signature_info: type: object nullable: true description: 数字签名的详细信息（若存在）。 exif_original_date: type: string nullable: true description: EXIF 原始拍摄日期，适用于图片上传。 exif_digitized_date: type: string nullable: true description: EXIF 数字化日期，适用于图片上传。 processed_by_known_editor: type: boolean nullable: true description: 元数据是否表明该文件曾经过已知的图像/PDF 编辑器处理。 has_different_creation_mod_date: type: boolean nullable: true description: 创建日期与修改日期是否存在差异，这是一种可能的（但非决定性的）编辑信号。 overlay_manipulation: type: object nullable: true description: 针对疑似覆盖文本篡改的 PDF 取证分析。当未发现覆盖篡改证据或证件不是 PDF 时为 Null。 properties: detected: type: boolean description: 是否检测到覆盖文本篡改的迹象。 analyzed: type: boolean description: PDF 是否可以被分析。 analysis_incomplete: type: boolean description: >- 仅当文件无法被完整检查时才存在且值为 true。已检查的部分在可能的情况下保留其检查结果，文档会发出未经验证的文本替换警告。 signals: type: array items: type: string description: >- 触发的取证信号，例如 duplicate_font_subset 或 glyph_fragmentation。 manipulated_regions: type: array description: PDF 页面坐标系中疑似被篡改的区域。 items: type: object properties: page: type: integer x: type: number 'y': type: number width: type: number height: type: number page_width: type: number page_height: type: number description: type: string nullable: true description: 分析师提供的证件请求标签或原因。常规上传为 `null`。 is_requested: type: boolean description: 如果为分析师创建且等待上传的证件请求占位项，则为 true。 ocr_data: type: object nullable: true is_console_upload: type: boolean description: 如果是从控制台而非终端用户流程上传的证件，则为 true。控制台上传绝不会更改功能级别的汇总状态。 is_confirmed: type: boolean description: Console 上传初始为 `false`，管理员确认后转为 `true`；终端用户上传始终为 `true`。 groups: type: object description: 按组划分的进度计数器，以组名称为键（例如 legal_presence、ownership_structure）。 additionalProperties: type: object properties: total: type: integer approved: type: integer pending: type: integer declined: type: integer in_review: type: integer other: type: integer missing: type: integer description: 已请求但尚未上传文件的占位符。 required_groups: type: array items: type: string warnings: type: array items: type: object environment: type: string enum: - live - sandbox description: 会话是由生产环境应用（`live`）还是沙盒应用（`sandbox`）创建。沙盒会话是免费且完全模拟的，绝不会扣除额度。 sandbox_scenario: type: string nullable: true description: 创建会话时使用的沙盒场景。对于生产环境会话以及创建时未指定场景的沙盒会话，该值为 `null`。 resubmissions: type: array description: >- 仅在携带 `include=resubmissions` 时返回，适用于用户和企业会话。每次重新提交请求对应一个条目，按最早优先排序。每个条目都包含重新提交步骤在请求之前返回的结果，因此早期的提交内容仍可读取。删除会话将删除所有提交记录。 items: type: object properties: number: type: integer description: 会话第一次重新提交为 1，第二次为 2，以此类推。 created_at: type: string format: date-time description: 请求重新提交的时间。 previous_status: type: string description: 紧接请求发起前的会话状态。 nodes: type: array description: 返回给用户的工作流步骤。 items: type: object properties: node_id: type: string feature: type: string reasons: type: object nullable: true additionalProperties: type: string description: 各步骤给出的原因，以 `node_id` 为键。 requested_by: type: object nullable: true description: 请求重新提交的人员。 properties: name: type: string email: type: string type: type: string results: type: object additionalProperties: true description: >- 重新提交的步骤在请求前返回的内容，其键名和结构与此响应的当前结果相同（`id_verifications`、`nfc_verifications`、`liveness_checks`、`face_matches`、`poa_verifications`、`phone_verifications`、`email_verifications`、`aml_screenings`、`ip_analyses`、`database_validations`、`questionnaire_responses`、`document_ai_documents`、`geolocation_checks`；企业会话还包括 `document_verifications`）。仅显示被回传步骤的键名。 biometric_consent: type: object nullable: true description: >- 会话在进行人脸采集前是否要求明确的生物识别同意、原因以及答复凭据。仅适用于用户验证（KYC）会话；该对象同样包含在会话 Webhook 的 `decision` 中。若会话从未经过评估（例如不含人脸采集的工作流），则为 `null`。未记录值的字段为 `null`。低于 4.10.0 的原生 SDK，或未上报版本的原生 SDK，无法显示同意步骤：其人脸采集将照常运行，而需要同意的会话随后将报告 `status: "pending"` 及 `reason: "BIOMETRIC_CONSENT_UNSUPPORTED_SDK"`。请参阅 [生物识别同意](/zh/getting-started/biometric-consent)。 properties: required: type: boolean description: >- Whether the session must collect explicit biometric consent. Never goes back to `false`. trigger: type: string nullable: true enum: - declared_state - ip_state - ip_unknown - document_issuer - forced - customer_collected description: >- 需要同意的原因，或其满足方式。`declared_state`：您声明了适用的州（`user_state`，或 `expected_details` 中的美国地址）。`ip_state`：该用户的 IP 位于适用的州（伊利诺伊州、得克萨斯州、科罗拉多州）。`ip_unknown`：证据表明该用户位于美国，但无法确定具体的州（IP 位于美国但没有具体州信息，或者无法定位且您的详细信息或证件表明该用户位于美国）。`document_issuer`：身份证件由适用的州签发。`forced`：应用的模式为 Always。`customer_collected`：您在创建会话时发送了 `biometric_consent`。非必需时为 `null`。 status: type: string enum: - not_required - pending - given - declined description: >- `not_required`；`pending`（必填但未提供：该人员尚未回答，或 `reason` 说明了未收集的原因）；`given`；`declined`（已记录拒绝，会话以 `Declined` 结束；目前 Didit 页面不提供拒绝选项）。 given_at: type: string format: date-time nullable: true description: 给予同意的时间。对于 `customer_collected`，为您发送的 `given_at`。 declined_at: type: string format: date-time nullable: true description: 记录拒绝的时间。 text_version: type: string nullable: true description: 该人员答复的同意文本版本 ID，或您发送的版本 ID。 text_hash: type: string nullable: true description: 所展示的确切同意文本（以所展示的语言）的 SHA-256（十六进制）。 locale: type: string nullable: true description: 同意声明文本显示的语言。 policy_url: type: string format: uri nullable: true description: 同意步骤所链接的生物识别数据策略。 step: type: string nullable: true description: 当事人回答时会话所在的工作流步骤，例如 `LIVENESS`。 node_id: type: string nullable: true description: 当事人回答时会话所在的工作流图谱节点。 ip_address: type: string nullable: true description: 答案来源的 IP。 ip_country_code: type: string nullable: true description: 答案的 IP 所在国家/地区的 ISO 3166-1 alpha-2 代码。 ip_state: type: string nullable: true description: 答案所在 IP 的 ISO 3166-2 行政区划，例如 `US-IL`。 ip_city: type: string nullable: true description: 答案所用 IP 所在的城市。 user_agent: type: string nullable: true description: 提交回答请求的 User-Agent。 detected_ip_address: type: string nullable: true description: 上次评估该要求时该人员所用的 IP。如果该人员在其他设备上进行了作答，可能与 `ip_address` 不同。 detected_country_code: type: string nullable: true description: 检测到的 IP 所在国家/地区的 ISO 3166-1 alpha-2 代码。 detected_state: type: string nullable: true description: 检测到的 IP 对应的 ISO 3166-2 行政区划。 detected_city: type: string nullable: true description: 检测到的 IP 所在的城市。 declared_state: type: string nullable: true description: 您声明的 ISO 3166-2 行政区划：`user_state`，或 `expected_details` 中美国地址的州。 document_state: type: string nullable: true description: 签发身份证件的 ISO 3166-2 行政区划，于证件采集时读取。 jurisdictions: type: array items: type: string description: >- 其生物识别法律涵盖该人员的美国各州（USPS 代码，例如 `IL`）。当证据表明该人员位于美国但州未知时为 `US`。不适用时为空。 retention_months: type: integer nullable: true description: '`jurisdictions` 中最短的生物特征保留限制（以月为单位）。当均不适用时为 `null`。' reason: type: string nullable: true enum: - BIOMETRIC_CONSENT_UNSUPPORTED_SDK - BIOMETRIC_CONSENT_DECLINED description: >- `BIOMETRIC_CONSENT_UNSUPPORTED_SDK`：需要同意，但低于 4.10.0 版本的原生 SDK 或未上报版本的 SDK 在没有同意步骤的情况下捕获了人脸；`status` 保持为 `pending`，如果用户稍后在托管流程中同意则变为 `given`。`BIOMETRIC_CONSENT_DECLINED`：记录了拒绝（这会替换 SDK 原因）。其他情况下为 `null`，且当会话不需要同意时始终为 `null`。 decline_reason: type: string nullable: true enum: - BIOMETRIC_CONSENT_DECLINED description: 当记录的拒绝导致会话终止时为 `BIOMETRIC_CONSENT_DECLINED`，否则为 `null`。 face_data_deleted_at: type: string format: date-time nullable: true description: 拒绝操作删除该会话的人脸图像、视频和人脸模板的时间。除非记录了拒绝，否则为 `null`。 investigator: $ref: '#/components/schemas/InvestigatorBlock' biometric_retention: $ref: '#/components/schemas/BiometricRetention' fraud_check: type: object nullable: true additionalProperties: true description: Fraud Check API 调用的结果。对于所有其他会话均为 `null`。 full_session_video: type: string format: uri nullable: true description: 完整会话录屏的会过期 URL。仅当您的组织录制完整会话视频时返回。 full_session_video_recorded_at: type: string format: date-time nullable: true description: 录制完整会话的时间。仅在您的组织录制完整会话视频时返回。 AddressValidationResult: type: object description: 单次地址验证的结果：地址是否存在，以及其规范化形式。它仅确认地址；绝不会将地址与个人关联。 required: - status - verification_level - address - formatted_address - latitude - longitude properties: status: type: string enum: - verified - partially_verified - not_verified - unavailable description: >- `verified`：地址已确认具体到建筑物（或单元/公寓、邮政信箱）。`partially_verified`：仅确认到街道，或确认到该地点邮政参考数据所能支持的最精确级别。`not_verified`：仅匹配到地区或城市，或完全未匹配。`unavailable`：无法执行核验（例如参考服务未响应）；该状态不计费，且绝不会影响验证。 verification_level: type: string nullable: true enum: - administrative_area - locality - thoroughfare - premise - delivery_point - null description: 地址匹配到的最高精确度级别。未匹配到任何内容或 `status` 为 `unavailable` 时为 `null`。 address: type: object nullable: true description: 标准化地址。当 `status` 为 `unavailable` 时为 `null`。 properties: address_line_1: type: string nullable: true description: 投递地址第一行，按该国家/地区的书写习惯书写。 example: 1600 Amphitheatre Pkwy address_line_2: type: string nullable: true description: 第二行投递地址（公寓、楼栋或社区，若地址包含）。 city: type: string nullable: true example: Mountain View region: type: string nullable: true description: 州、省或地区。 example: CA postal_code: type: string nullable: true example: 94043-1351 country: type: string nullable: true description: ISO 3166-1 alpha-2 国家/地区代码。 example: US formatted_address: type: string nullable: true description: 单行格式的标准化地址。 example: 1600 Amphitheatre Pkwy, Mountain View CA 94043-1351 latitude: type: number nullable: true example: 37.422022 longitude: type: number nullable: true example: -122.08429 PhoneIntelligence: type: object description: 归一化的电话情报区块。仅在本次查询运行了情报附加组件时存在；存在时还会以相同值的 `enrichment` 别名提供。 properties: score: type: number nullable: true description: 归一化的 0-100 风险评分。分值越高风险越大。 phone_type_risk: type: string nullable: true description: 由评分推导出的 `Low`、`Medium` 或 `High`。 phone_trust_index: type: number nullable: true description: 分数的反向值，适用于偏好数值越高越好的仪表板。 network_stability_index: type: number nullable: true description: 线路网络的稳定性。 is_disposable: type: boolean nullable: true description: 当号码疑似一次性号码或虚拟号码时为 `true`。 is_ported: type: boolean nullable: true description: 当号码已更换运营商时为 `true`。 is_recently_ported: type: boolean nullable: true description: 当转网发生在近期时为 `true`。 carrier_type: type: string nullable: true description: 查询报告的线路分类（例如 `mobile`）。 reason_codes: type: array items: type: object properties: code: type: string description: 信号的稳定 Didit 标识符，例如 `IR-5AC67A32`。不透明标识：可据此分组和过滤，请勿解析其内容。 value: nullable: true description: >- 对于风险标记（例如 `voip`、`leaked`、`disposable`、`spam_trap`），为其对应的值：布尔值、等级或日期。对于计分原因代码则为 null。 direction: type: string enum: - risk - trust description: 该信号是增加了风险还是提升了信任度。 message: type: string description: 信号的便于人类阅读的说明（英文）。 impact_level: type: string nullable: true description: 该信号对评分的影响强度，例如 `low`、`medium` 或 `high`。 description: >- 解释评分的信号，每个信号包含一个固定的 Didit 代码、一个方向、一条消息和一个影响级别。新代码可能会随着时间推移而出现，因此请勿拒绝未知代码。 PhoneSocialFootprint: type: object nullable: true description: >- 电话号码的社交足迹：其注册的在线平台。仅当设置了 `enable_social` 且检查完成时才会出现。若未返回对应数据，各计数项可能为 null。`profiles_registered: 0` 表示已检查相关平台且未在任何平台上发现该电话号码，这是一个有效的计费结果，也是合成身份的常见信号。 properties: profiles_registered: type: integer nullable: true description: 已确认该电话号码已注册的平台。 example: 5 profiles_checked: type: integer nullable: true description: 已评估注册情况的平台。 example: 14 names_found: type: integer nullable: true description: 返回了关联姓名的平台。 example: 0 photos_found: type: integer nullable: true description: 返回了个人资料头像的平台。 example: 0 communication_breadth: type: integer nullable: true description: 检测到存在活动的通信平台。 example: 2 digital_footprint_diversity: type: integer nullable: true description: 检测到存在记录的不同平台类别。 example: 5 digital_sophistication_index: type: integer nullable: true description: 综合数字成熟度指标，0-10。 example: 5 engagement_depth_index: type: integer nullable: true description: 个人资料丰富度指标，0-10。 example: 3 subscription_affordability_index: type: integer nullable: true description: 免费与付费平台混合比例，0-10。 example: 2 free_platforms: type: integer nullable: true description: 在免费平台上的注册数。 example: 4 full_paid_platforms: type: integer nullable: true description: 在完全付费平台上的注册数。 example: 0 partial_paid_platforms: type: integer nullable: true description: 在免费增值平台上的注册数。 example: 1 whatsapp_profile_completeness: type: string nullable: true enum: - Basic - Partial - Complete - Not Present - null description: WhatsApp 资料的完整性。仅限电话；邮箱为 null。 example: Partial registered_platforms: type: array description: 已确认注册的平台。 items: $ref: '#/components/schemas/SocialFootprintPlatform' not_registered_platforms: type: array description: 检查结果为阴性的平台。 items: $ref: '#/components/schemas/SocialFootprintPlatform' categories: type: object description: 每个平台类别的注册数量和比例。 additionalProperties: $ref: '#/components/schemas/SocialFootprintCategorySummary' profiles: type: object description: 各平台个人资料详情，以平台为键（在平台公开这些信息时返回）。 additionalProperties: $ref: '#/components/schemas/SocialFootprintProfile' EmailIntelligence: type: object description: 归一化的邮箱情报区块。仅在该邮箱运行了情报附加组件时存在；存在时还会以相同值的 `enrichment` 别名提供。 properties: score: type: number nullable: true description: 归一化的 0-100 风险评分。分值越高风险越大。 deliverable: type: string nullable: true description: 可投递性等级（例如 `high`）。 breach_risk_level: type: string nullable: true description: '`Low`、`Medium` 或 `High`。' breach_risk_index: type: number nullable: true description: 泄露风险数值指数。 is_recent_breach: type: boolean nullable: true description: 当该地址出现在近期泄露事件中时为 `true`。 is_frequent_breached: type: boolean nullable: true description: 当该地址出现在多次泄露事件中时为 `true`。 is_disposable: type: boolean nullable: true description: 当域名属于一次性邮箱服务商时为 `true`。 is_free_domain: type: boolean nullable: true description: 当域名属于免费邮箱服务商时为 `true`。 is_breached: type: boolean nullable: true description: 当该地址出现在已知泄露事件中时为 `true`。 no_of_breaches: type: number nullable: true description: 包含该地址的已知泄露事件数量。 reason_codes: type: array items: type: object properties: code: type: string description: 信号的稳定 Didit 标识符，例如 `IR-5AC67A32`。不透明标识：可据此分组和过滤，请勿解析其内容。 value: nullable: true description: >- 对于风险标记（例如 `voip`、`leaked`、`disposable`、`spam_trap`），为其对应的值：布尔值、等级或日期。对于计分原因代码则为 null。 direction: type: string enum: - risk - trust description: 该信号是增加了风险还是提升了信任度。 message: type: string description: 信号的便于人类阅读的说明（英文）。 impact_level: type: string nullable: true description: 该信号对评分的影响强度，例如 `low`、`medium` 或 `high`。 description: >- 解释评分的信号，每个信号包含一个固定的 Didit 代码、一个方向、一条消息和一个影响级别。新代码可能会随着时间推移而出现，因此请勿拒绝未知代码。 EmailSocialFootprint: type: object nullable: true description: >- 邮箱地址的社交足迹：其注册的在线平台。仅当设置了 `enable_social` 且检查完成时才会出现。若未返回对应数据，各计数项可能为 null。`profiles_registered: 0` 表示已检查相关平台且未在任何平台上发现该邮箱地址，这是一个有效的计费结果，也是合成身份的常见信号。 properties: profiles_registered: type: integer nullable: true description: 已确认该邮箱地址已注册的平台。 example: 5 profiles_checked: type: integer nullable: true description: 已评估注册情况的平台。 example: 14 names_found: type: integer nullable: true description: 返回了关联姓名的平台。 example: 0 photos_found: type: integer nullable: true description: 返回了个人资料头像的平台。 example: 0 communication_breadth: type: integer nullable: true description: 检测到存在活动的通信平台。 example: 2 digital_footprint_diversity: type: integer nullable: true description: 检测到存在记录的不同平台类别。 example: 5 digital_sophistication_index: type: integer nullable: true description: 综合数字成熟度指标，0-10。 example: 5 engagement_depth_index: type: integer nullable: true description: 个人资料丰富度指标，0-10。 example: 3 subscription_affordability_index: type: integer nullable: true description: 免费与付费平台混合比例，0-10。 example: 2 free_platforms: type: integer nullable: true description: 在免费平台上的注册数。 example: 4 full_paid_platforms: type: integer nullable: true description: 在完全付费平台上的注册数。 example: 0 partial_paid_platforms: type: integer nullable: true description: 在免费增值平台上的注册数。 example: 1 whatsapp_profile_completeness: type: string nullable: true enum: - Basic - Partial - Complete - Not Present - null description: WhatsApp 资料的完整性。仅限电话；邮箱为 null。 example: Partial registered_platforms: type: array description: 已确认注册的平台。 items: $ref: '#/components/schemas/SocialFootprintPlatform' not_registered_platforms: type: array description: 检查结果为阴性的平台。 items: $ref: '#/components/schemas/SocialFootprintPlatform' categories: type: object description: 每个平台类别的注册数量和比例。 additionalProperties: $ref: '#/components/schemas/SocialFootprintCategorySummary' profiles: type: object description: 各平台个人资料详情，以平台为键（在平台公开这些信息时返回）。 additionalProperties: $ref: '#/components/schemas/SocialFootprintProfile' DocumentAIDetectedCode: type: object required: - type - page_number - position - x - 'y' - width - height - page_width - page_height - raw_payload - parsed_payload properties: type: type: string description: 检测到的符号系统，例如 `QR_CODE`、`CODE_128`、`EAN_13`、`DATA_MATRIX` 或 `PDF_417`。 page_number: type: integer minimum: 1 description: 从 1 开始的页码。 position: type: array nullable: true description: 在渲染页面的像素坐标中检测到的多边形。当没有可靠的位置可用时为 `null`。 items: type: array minItems: 2 maxItems: 2 items: type: integer x: type: integer nullable: true description: 边界框的左边缘（以渲染页面的像素为单位）。 'y': type: integer nullable: true description: 边界框的顶部边缘（以渲染页面像素为单位）。 width: type: integer nullable: true description: 渲染页面像素中的边界框宽度。 height: type: integer nullable: true description: 渲染页面像素中的边界框高度。 page_width: type: integer description: 渲染页面的宽度（以像素为单位）。 page_height: type: integer description: 渲染页面的高度（以像素为单位）。 raw_payload: type: string description: 原始解码器 payload（base64 字符串形式，如可用）；否则为空字符串。 parsed_payload: nullable: true description: 解码后的字符串或结构化值。当定位到代码但无法解码时为 `null`。 BankVerificationResult: type: object description: >- 单个银行验证步骤的结果，适用于用户验证和企业验证（KYB）。`method` 说明了账户是如何验证的，`none` 表示该人员在评估任何尝试之前未绑定银行即继续操作。`continued_without_bank` 表示该人员在评估尝试后仍未绑定银行继续操作。请参阅[银行验证方式](/zh/core-technology/bank-verification/verification-methods)和[当用户无法验证其银行时](/zh/core-technology/bank-verification/fallbacks)。 properties: schema_version: type: integer description: 此结果结构的当前版本。目前为 `1`。 bank_verification_id: type: string format: uuid description: 此结果的 ID。 node_id: type: string description: 此结果所属的工作流节点。 status: type: string enum: - Not Finished - Approved - Declined - In Review - Expired description: 在执行其操作和状态规则后，该步骤的裁定结果。 original_status: type: string nullable: true description: 该步骤达成的首个裁决结果，早于任何后续变更（例如人工审核）。 method: type: string nullable: true enum: - open_banking - account_lookup - microdeposits - statement - none description: >- 账户的验证方式：`open_banking`（银行登录：用户在其银行登录）、`account_lookup`（账户核查：用户输入账户详情，银行确认姓名）、`microdeposits` 或 `statement`（上传银行对账单）。当用户在评估任何尝试前选择在没有银行的情况下继续时为 `none`，此时未验证任何账户。在完成一次已评估的尝试后，它将保持该尝试的方式。在评估账户之前以及工作流限制其返回的数据时为 `null`。工作流规则读取与 `bank.method` 相同的值。 provider: type: string nullable: true description: 运行连接的路由密钥。读取 `method` 而非此密钥，以确定账户的验证方式。 credential_source: type: string nullable: true enum: - native - byok description: '`native`：Didit 自身的路由，从您的 Didit 余额中扣费。`byok`：您使用自己的凭据连接的应用市场服务商。' route: type: object nullable: true description: 同意前选择的路由。此后绝不更改。 properties: provider_key: type: string nullable: true description: 路由的键。 credential_source: type: string enum: - native - byok is_fallback: type: boolean description: Didit 的自有路由是否替代了无法连接的市场提供商。 provider_connection_id: type: string nullable: true description: 用于 `byok` 的应用市场连接。 requested_scopes: type: array items: type: string description: 连接请求的数据，例如 `ownership` 或 `balances`。 connection: type: object nullable: true description: 最新尝试的连接。在首次尝试前为 `null`。 properties: status: type: string enum: - pending - connected - cancelled - timeout - failed - unsupported - revoked - expired institution_id: type: string nullable: true description: 银行的 ID。对于未选择银行的账户核验，该值为 `null`。 institution_name: type: string nullable: true description: 银行名称。对于账户核验，该值为 `null`。 institution_country: type: string nullable: true description: 账户所在的国家/地区，采用 ISO 3166-1 alpha-3 格式。 oauth: type: boolean nullable: true description: 银行登录是通过 OAuth 还是应用间（app-to-app）运行。账户核对时为 `null`。 connected_at: type: string format: date-time nullable: true description: 连接成功的时间。 consent_expires_at: type: string format: date-time nullable: true description: 银行同意有效期结束的时间，用于银行登录。 last_refreshed_at: type: string format: date-time nullable: true description: 上次重新读取财务数据的时间。 attempts: type: integer description: 该用户在此步骤中尝试的次数，所有方式累计计算。 reason_code: type: string nullable: true description: >- 连接状态并非仅为 `connected` 的原因，例如 `USER_CANCELLED`、`INSTITUTION_DOWN`、`ACCOUNT_NOT_FOUND`、`REFERENCE_IDENTITY_MISSING` 或 `VERIFICATION_COMPLETED`。 account: type: object nullable: true description: 已评估的账户。在账户被评估之前为 `null`。 properties: account_id_masked: type: string nullable: true description: 脱敏后的账号。 iban_masked: type: string nullable: true description: 已脱敏的 IBAN。 sort_code: type: string nullable: true description: 英国的银行代码（sort code）。 routing_number_masked: type: string nullable: true description: 已脱敏的路由号码。 type: type: string nullable: true enum: - checking - current - savings - business - other subtype: type: string nullable: true description: 银行自有的账户子类型。 currency: type: string nullable: true description: 账户的 ISO 4217 货币。 holder_type: type: string nullable: true enum: - person - business - unknown holders_count: type: integer nullable: true is_joint: type: boolean nullable: true is_business: type: boolean nullable: true ownership: type: object nullable: true description: 账户持有人与已验证身份的比对情况。在评估账户之前为 `null`。 properties: result: type: string enum: - match - partial_match - no_match - unknown - not_verifiable description: >- `partial_match` 表示相近匹配。`not_verifiable`：银行返回响应但没有可供比对的账户持有人。`unknown`：无法读取凭证，或者没有可供比对的身份信息。 reference_identity_source: type: string nullable: true description: >- 将持有者与之进行身份比对的步骤：`kyc`、`database_validation`、`expected_details`、`questionnaire`、`document_ai` 或 `kyb`。 name_score: type: integer minimum: 0 maximum: 100 nullable: true description: Didit 的持有人姓名分数。 provider_name_score: type: integer minimum: 0 maximum: 100 nullable: true description: 银行自有的账户持有人姓名分数（若已返回）。 address_score: type: integer minimum: 0 maximum: 100 nullable: true description: 持有人地址评分（当执行了地址匹配时）。 email_score: type: integer minimum: 0 maximum: 100 nullable: true description: 持有人邮箱评分（当执行了邮箱匹配时）。 phone_score: type: integer minimum: 0 maximum: 100 nullable: true description: 持有人电话评分（当执行了电话匹配时）。 dob_score: type: integer minimum: 0 maximum: 100 nullable: true description: 持有人出生日期评分（当银行提供了该信息时）。 close_match: type: boolean nullable: true description: 姓名是否落在近似匹配区间内。 holder_confirmation: type: string nullable: true enum: - pending - confirmed - rejected description: 要求确认近似匹配姓名时该人员的回答。如果从未询问则为 `null`。 method: type: string nullable: true enum: - exact - token_set - nickname - transliteration - fuzzy - provider_only - microdeposits description: 生成该分数的姓名比对方式。这不是验证方法：验证方法请查看顶层的 `method`。 matched_holder_index: type: integer nullable: true holders: type: array items: type: object description: 银行列出的每个持有人及其评分。 owner_identity_available: type: boolean nullable: true evidence_freshness: type: string nullable: true enum: - live - cached - refreshed evaluated_at: type: string format: date-time nullable: true description: 计算得出裁定的时间。 financial_data: type: object description: 该步骤读取的财务数据。仅银行登录会读取此数据。 properties: balances: type: object nullable: true description: 带有 `balances` 权限范围。 transactions: type: object nullable: true description: 带有 `transactions` 权限范围。 income: type: object nullable: true description: 带有 `income` 权限范围。 categorization: type: object nullable: true description: Didit 对读取交易的分类。如果没有则为 `null`。 not_collected: type: array items: type: string enum: - balances - income - transactions description: >- 该步骤请求但验证账户的方法未收集的数据。余额、交易和收入仅来自银行登录，因此通过账户核查验证的账户会在此处列出它们。绝非失败。否则为空。 billing: type: object nullable: true properties: route: type: string enum: - native - byok billed: type: boolean marketplace_fee: type: string nullable: true description: 针对 `byok` 收取的应用市场平台费用。 usage_type: type: string nullable: true description: >- 计费所记入的使用量项目：`bank_verification` 对应银行登录或账户核验，`bank_statement_upload` 对应此前没有扣费银行尝试的对账单上传，`bank_byok_fee` 对应您自带提供商的市场服务费。未产生费用时为 `null`。 reference_identity: type: object nullable: true description: 持有人比对所依据的身份及其来源。 signals: type: object nullable: true description: 从交易历史记录中读取的账户信号（当该步骤读取了交易历史记录时）。 connection_abandoned: type: boolean nullable: true description: 在用户离开银行页面后，该步骤是否在未匹配的情况下结束。 not_covered: type: boolean nullable: true description: >- 在此步骤中是否无法连接到该用户的银行或国家/地区。当用户因没有可核验其国家/地区或银行的方式而选择不关联银行直接继续时，也为 `true`。 continued_without_bank: type: boolean description: >- 用户是否通过 **Continue without your bank** 离开了该步骤。此时 `continuation` 会说明原因。若在用户继续之前未评估任何尝试，则 `method` 为 `none`。在评估尝试（例如持有人不匹配）之后，`method` 将保持该尝试的验证方式，其判定和原因代码仍然有效。即使工作流缩小了返回数据的范围，也会返回此字段。 continuation: type: object nullable: true description: >- 用户在没有银行的情况下继续的方式。若未如此操作则为 `null`。当工作流限制其返回的数据时，仍会返回 `reason`，其他所有键均为 `null`。 properties: reason: type: string enum: - no_route - institution_unsupported - attempts_exhausted - person_choice description: >- 原因，由 Didit 在该人员继续操作时判断：`no_route`（没有适用于其国家/地区的银行登录或账户核验服务）、`institution_unsupported`（他们选择的银行无法在此步骤中使用）、`attempts_exhausted`（所有尝试均已用尽且无正在进行的尝试），或 `person_choice`（存在核验方式但他们选择继续，也包括当前无法连接其银行的情况）。除非已评估的尝试已对该步骤做出决策，否则 `no_route` 和 `institution_unsupported` 遵循 `bank_unsupported_action`，`attempts_exhausted` 遵循 `bank_attempts_exhausted_action`，`person_choice` 遵循 `bank_skipped_action`。 country: type: string nullable: true description: 该人进行验证所在的国家/地区，ISO 3166-1 alpha-3 格式。若在选择前继续操作，则为 `null`。 offered: type: array items: type: string enum: - statement - microdeposits nullable: true description: >- 该人在继续操作时该国家/地区向其提供的其他验证方式，按提供顺序排列：`statement`（对账单上传），然后是 `microdeposits`（微额存款）。若未提供任何方式则为空。 institution_id: type: string nullable: true description: >- 对于 `institution_unsupported`，为该用户无法使用的银行 ID：其选择的银行，或其最后一次尝试最终落在的银行。Didit 从其自有的银行列表中获取该信息，绝不会从用户的设备中获取，因此该列表中不存在的银行将显示为 `null`。对于所有其他原因均为 `null`。 institution_name: type: string nullable: true description: >- 对于 `institution_unsupported`，为该银行的名称，来自与 `institution_id` 相同的列表。当该列表不包含该银行时以及对于所有其他原因，均为 `null`。 continued_at: type: string format: date-time nullable: true description: 当事人继续操作的时间。 evidence_purged_at: type: string format: date-time nullable: true description: 根据 `bank_evidence_retention_days` 删除银行凭证的时间。否则为 `null`。 warnings: type: array items: type: string description: 信息性代码，例如 `holder_declared`。警告本身绝不会改变状态。 reason_codes: type: array items: type: string description: >- 得出该判定的原因，例如 `OWNER_NAME_PARTIAL`。可能适用多项。`NOT_COVERED`：由于没有任何方法可核验其国家/地区或银行，该人员在未绑定银行的情况下继续。`SKIPPED`：存在核验方式，但该人员选择在未绑定银行的情况下继续。如果已评估的尝试已对该步骤做出决策，则两者均不添加。 created_at: type: string format: date-time updated_at: type: string format: date-time SignatureResult: type: object description: >- 单个电子签名步骤中一位签名人的结果。请参阅[电子签名报告](/zh/core-technology/electronic-signature/report-electronic-signature)。 properties: id: type: string format: uuid description: 将其作为 `signature_id` 传入以下载该签署人的证据或核验其签名。 node_id: type: string description: 生成它的工作流步骤。 status: type: string enum: - intro - review - code - signing - signed - declined description: 签署人在该步骤中所处的进度。仅 `signed` 表示文件已签署。 verdict: type: string enum: - Not Finished - Approved - In Review - Declined description: 步骤的结果。警告会通过其规则对其进行设置；自定义状态规则在此之后应用。 level: type: string enum: - simple - aes - qes description: '`simple`（默认）或 `aes`。`qes`（合格电子签名，QES）是尚未开放的附加功能。' format: type: string enum: - pdf - pades description: Simple 签名对应 `pdf`，Advanced (AES) 对应 `pades`。 profile: type: string nullable: true description: 高级（AES）签名完成签署后为 `PAdES-B-LT`，否则为 null。 signer: type: object properties: name: type: string nullable: true description: >- 签署人的姓名。已验证（来自已通过的身份证件验证或会话），但 Simple 等级且没有已验证会话姓名的情况除外，此时为签署人输入的姓名且未经核验。 capacity: type: string enum: - self - company company: type: string nullable: true role: type: string nullable: true description: 关键人员的职务（按申报）。 roles: type: array items: type: string description: 关键人员的结构化角色（针对企业申报）。 identity_session_id: type: string format: uuid description: 验证了签署人的 KYC 会话。 identity_used: type: object description: 签名所依赖的已验证身份。对于未关联已验证身份的 Simple 签名，该项为空。 properties: session_id: type: string format: uuid kyc_id: type: string format: uuid nullable: true verified: type: boolean expected_name: type: string nullable: true description: 签署人必须匹配的姓名。 certificate: type: object nullable: true description: 签署文件所用的证书。签署前为 `null`，对于简单签名则始终为 `null`。 properties: issuer: type: string issued_to: type: string serial: type: string description: 序列号，十六进制。 valid_from: type: string format: date-time valid_until: type: string format: date-time confirmation: type: object properties: channel: type: string nullable: true enum: - email - sms description: 对于没有代码的 Simple 签名，该值为 `null`。 destination: type: string nullable: true description: 验证码发送至的已脱敏联系方式。 confirmed_at: type: string format: date-time nullable: true attempts: type: integer description: 已输入的验证码，其中包括正确的验证码。 timestamp: type: object nullable: true description: >- 签名中的 RFC 3161 时间戳，由 Didit 签发。完成签名之前为 `null`，对于简单签名（Simple signature）始终为 `null`。 properties: time: type: string format: date-time qualified: type: boolean description: 对于 AES 始终为 `false`。 valid: type: boolean documents: type: array items: type: object properties: id: type: string format: uuid description: 此签署人副本上的证件。用于下载已签署的文件。 uuid: type: string format: uuid description: 与 `id` 相同。 title: type: string file_name: type: string pages: type: integer description: 已签署的证件页码。对于 Word 证件，指转换后的 PDF 页码。 size_bytes: type: integer sha256_original: type: string description: 向签署人展示的文档的 SHA-256。 sha256_signed: type: string nullable: true description: 签署后的 PDF 的 SHA-256。 status: type: string enum: - signed - declined - not_signed - not_reached description: '`not_signed`：已打开但未签署。`not_reached`：从未打开。' opened_at: type: string format: date-time nullable: true read_at: type: string format: date-time nullable: true description: 当步骤有要求时，签署人到达无字段证件末尾的时间。 read_to_end: type: boolean consented_at: type: string format: date-time nullable: true description: 签署人同意无字段证件的时间，或完成有字段证件中各个字段的时间。 consent: type: boolean signed_file: type: string nullable: true description: >- 签署后的 PDF 路径（签署完成后）。参见[下载已签署证件](/zh/sessions-api/electronic-signature/download-signed-document)。 mode: type: string enum: - fields - read_and_agree description: 带有字段的证件为 `fields`，没有字段的证件为 `read_and_agree`。 source_format: type: string enum: - pdf - docx description: '`pdf`，或者对于 Didit 转换为 PDF 的 Word 文档为 `docx`。' conversion: type: object nullable: true description: PDF 文件为 `null`。对于 Word 文档，则包含原始文件和转换后的文件。 properties: from: type: string enum: - docx file_name: type: string description: 您的原始 Word 文件名。 sha256: type: string description: 您原始 Word 文件的 SHA-256。 size_bytes: type: integer description: 您的原始 Word 文件的大小。 converter: type: string description: 生成该 PDF 的转换器版本。 fields: type: array description: 证件上的字段及其对应值。对于没有字段的证件，该项为空。 items: $ref: '#/components/schemas/SignatureFieldResult' adopted_signature: type: object nullable: true description: 签署人为签名和首字母字段采用的签名及首字母。在签署人采用之前为 `null`。 properties: method: type: string enum: - typed - drawn description: '`typed`：手写体风格的已验证姓名。`drawn`：使用手指或鼠标绘制。' font: type: string nullable: true description: 键入签名的手写样式。手绘签名时为 `null`。 adopted_at: type: string format: date-time electronic_signature_consent_at: type: string format: date-time nullable: true description: 签署人在审核屏幕上同意对证件进行电子签名的时间。当任何证件包含字段时设置。 evidence_file: type: string nullable: true description: >- 签名完成后证据 PDF 的路径。参见[下载签名证据](/zh/sessions-api/electronic-signature/download-evidence)。 warnings: type: array description: >- 针对该签名人的警告。请参阅[电子签名警告](/zh/core-technology/electronic-signature/warnings-electronic-signature)。 items: type: object properties: code: type: string enum: - SIGNATURE_DECLINED - SIGNATURE_OTP_FAILED - SIGNATURE_NAME_MISMATCH - SIGNATURE_IDENTITY_NOT_VERIFIED - SIGNATURE_DOCUMENT_CHANGED - SIGNATURE_FIELD_DATA_MISSING node_id: type: string validation: type: object nullable: true description: >- 已签名证件的最新加密核验结果。在证件签名之前为 `null`。如果 Didit 无法确认签名结果，则为 `{"valid": null, "reason": "signature_provider_outcome_unknown", "checked_at": ...}`，且 `status` 保持为 `signing`：请将其视为未签名。 properties: valid: type: boolean nullable: true description: 当所有证件均有效时为 `true`。当无法确认签名结果时为 `null`。 reason: type: string description: 当 `valid` 为 `null` 时设置：`signature_provider_outcome_unknown`。 checked_at: type: string format: date-time documents: type: array items: type: object properties: id: type: string format: uuid checked_at: type: string format: date-time valid: type: boolean description: 当签名和时间戳均有效且可信时为 `true`。 integrity: type: boolean description: 当证件自签名后未发生更改时为 `true`。 trusted: type: boolean description: 当签名证书链接到受信任的根证书时为 `true`。 revoked: type: boolean trusted_list: type: object description: >- 欧盟信任列表（EU Trusted List）检查。对于 AES：`{"status": "not_applicable", "reason": "aes_not_qualified"}`。 properties: status: type: string reason: type: string certificate: type: object nullable: true description: 签署文件所用的证书。签署前为 `null`，对于简单签名则始终为 `null`。 properties: issuer: type: string issued_to: type: string serial: type: string description: 序列号，十六进制。 valid_from: type: string format: date-time valid_until: type: string format: date-time timestamp: type: object nullable: true description: >- 签名中的 RFC 3161 时间戳，由 Didit 签发。完成签名之前为 `null`，对于简单签名（Simple signature）始终为 `null`。 properties: time: type: string format: date-time qualified: type: boolean description: 对于 AES 始终为 `false`。 valid: type: boolean declined_at: type: string format: date-time nullable: true declined_action: type: string enum: - DECLINE - REVIEW - NO_ACTION signed_at: type: string format: date-time nullable: true expires_at: type: string format: date-time description: 签名链接失效的时间。 email_sent_at: type: string format: date-time nullable: true email_unavailable_reason: type: string nullable: true ip_address: type: string nullable: true description: 签署人请求验证码时的地址。 place: type: string nullable: true description: 未采集：始终为 `null`。 place_unavailable_reason: type: string nullable: true enum: - not_collected AMLScreening: type: object properties: node_id: type: string description: 工作流图谱中该 AML 步骤的唯一标识符。 status: type: string description: 此 AML 筛查的功能级状态。独立于顶级会话的 `status`：会话可以达成其总体决策，而单个功能仍保持 `In Review`。 enum: - Not Finished - Approved - Declined - In Review - Resub Requested total_hits: type: integer description: 找到的匹配总数 entity_type: type: string description: 被筛查实体的类型：个人或企业 hits: type: array items: type: object properties: id: type: string description: >- Didit 对命中的稳定标识符：`hit_` 后跟 24 个十六进制字符。再次对主体进行筛查时，相同的匹配实体保留相同的 `id`。在调用 AML 命中审核 endpoint 时作为 `hit_id` 传递。 url: type: string format: uri description: 匹配项的来源 URL match: type: boolean description: 这是否为已确认的匹配项 score: type: number format: float nullable: true minimum: 0 maximum: 1 description: 已弃用的加权匹配分数，取值范围为 0-1（例如 `0.73`）。请改用 `match_score`（0-100）。 deprecated: true target: type: boolean nullable: true description: 匹配的实体是否为名录收录的直接目标（而非关联方）。来源未指定时为 `null`。 caption: type: string description: 匹配项的说明或标题 datasets: type: array items: type: string enum: - PEP - PEP Level 1 - PEP Level 2 - PEP Level 3 - PEP Level 4 - Sanctions - Adverse Media - Warnings and Regulatory Enforcement - Fitness and Probity - SIP - SIE - Insolvency - Other Lists description: >- 发现匹配项的数据集类别列表。指明该实体是否出现在政治公众人物名单（含等级）、制裁名单数据库、负面新闻、警告/监管执法或其他合规数据集中。当实体的来源未指明这些类别中的任何一项时，为 `Other Lists`。 features: type: object nullable: true description: 匹配项的附加特征 rca_name: type: string description: RCA 名称（如果适用） last_seen: type: string format: date-time description: 最后一次发现匹配项的日期 risk_view: type: object properties: crimes: type: object properties: score: type: integer weightage: type: integer risk_level: type: string risk_scores: type: object countries: type: object properties: score: type: integer weightage: type: integer risk_level: type: string risk_scores: type: object categories: type: object properties: score: type: integer weightage: type: integer risk_level: type: string risk_scores: type: object custom_list: type: object first_seen: type: string format: date-time description: 首次发现匹配项的日期 properties: type: object properties: name: type: array items: type: string alias: type: array items: type: string notes: type: array items: type: string title: type: string nullable: true gender: type: array items: type: string height: type: string nullable: true topics: type: string nullable: true weight: type: string nullable: true address: type: string nullable: true country: type: string nullable: true website: type: string nullable: true eyeColor: type: string nullable: true keywords: type: string nullable: true lastName: type: array items: type: string position: type: string nullable: true religion: type: string nullable: true birthDate: type: array items: type: string education: type: array items: type: string ethnicity: type: string nullable: true firstName: type: array items: type: string hairColor: type: string nullable: true weakAlias: type: string nullable: true birthPlace: type: array items: type: string modifiedAt: type: string nullable: true wikidataId: type: string nullable: true citizenship: type: string nullable: true nationality: type: string nullable: true match_score: type: number description: 根据姓名相似度、出生日期和国家/地区匹配计算得出的加权身份置信度分数（0-100）。用于确定命中是误报还是可能匹配。 format: float nullable: true risk_score: type: number description: >- 主体风险评分（0-100）。用于根据非误报命中项中的最高 risk_score 确定最终 AML 状态（Approved/In Review/Declined）。 review_status: type: string description: >- 此命中项的审核状态。可以为 'Unreviewed'、'Confirmed Match'、'False Positive' 或 'Inconclusive'。 enum: - Unreviewed - Confirmed Match - False Positive - Inconclusive score_breakdown: type: object description: match_score 的详细计算明细。 properties: name_score: type: integer description: 原始姓名相似度百分比（0-100）。 name_weight: type: integer description: 配置中姓名的原始权重（0-100）。 name_weight_normalized: type: number description: 针对缺失数据重新加权后的姓名归一化权重（0-100）。 name_contribution: type: number description: 姓名对总分的贡献点数。 dob_score: type: integer description: 出生日期匹配分数（-100 到 100）。 dob_weight: type: integer description: 配置中出生日期的原始权重（0-100）。 dob_weight_normalized: type: number description: 针对缺失数据重新加权后的出生日期归一化权重（0-100）。 dob_contribution: type: number description: 出生日期对总分的贡献点数。 country_score: type: integer description: 国家/地区匹配分数（-100 到 100）。 country_weight: type: integer description: 配置中国家/地区的原始权重（0-100）。 country_weight_normalized: type: number description: 针对缺失数据重新加权后的国家/地区归一化权重（0-100）。 country_contribution: type: number description: 国家/地区对总分的贡献点数。 document_number_match_type: type: string description: 证件号码“Golden Key”评估的结果。 enum: - MATCH - NEUTRAL - HARD_MISMATCH document_number_effect: type: string description: 证件号码对评分影响的便于人类阅读的描述。 total_score: type: integer description: 最终加权匹配分数（0-100）。 pep_matches: type: array items: type: object properties: aliases: type: array items: type: string education: type: array items: type: string list_name: type: string publisher: type: string source_url: type: string format: uri description: type: string matched_name: type: string pep_position: type: string date_of_birth: type: string other_sources: type: array items: type: string place_of_birth: type: string linked_entities: type: array items: type: object properties: name: type: array items: type: string active: type: array items: type: string status: type: array items: type: string details: type: array items: type: string relation: type: array items: type: string warning_matches: type: array description: >- 警告和监管执法匹配项列表。包括来自以下类别的条目：Warning、SIP、Warnings and Regulatory Enforcement、Fitness and Probity、SIE 以及 Insolvency。 items: type: object properties: list_name: type: string description: 警告名单发布者的名称 matched_name: type: string description: 在警告名单中匹配到的名称 description: type: string description: 警告条目说明 publisher: type: string description: 警告的发布者或来源 source_url: type: string format: uri description: 警告来源的 URL other_sources: type: array items: type: string description: 其他来源 URL countries: type: array items: type: string nullable: true description: 与该警告关联的国家/地区 created_at: type: string nullable: true description: 警告条目创建的日期 updated_at: type: string nullable: true description: 警告条目上次更新的日期 additional_data: type: object description: 来自警告数据源的其他数据。可能包含带有 `case_details` 数组的 `data` 对象。 properties: data: type: object properties: case_details: type: array description: 与此匹配项相关的警告案件详情 items: type: object properties: case_type: type: string description: 警告案件的类型 enum: - Accusation - Arrest - Bribery - Criminal - Fraud - Illegal Fundraising - Non-conviction Terror - Proclaimed Offender - Regulatory Enforcement - Terrorism - Terrorism-related - Terrorism-related listing sanction_matches: type: array description: 为此实体找到的制裁名单匹配项列表。 items: type: object properties: list_name: type: array items: type: string nullable: true description: 制裁名单的名称 matched_name: type: string description: 在制裁名单中匹配到的名称 description: type: string description: 制裁条目说明 reason: type: string nullable: true description: >- 该实体受到制裁的自由文本原因。由制裁名单中的原因条目拼接而成。示例：'Executive Order 13224 (Terrorism)'、'Support for actions undermining Ukraine's sovereignty'、'Listed due to national security concerns。' source_url: type: string format: uri description: 制裁来源的 URL other_sources: type: array items: type: string description: 其他来源 URL details: type: array items: type: string description: 关于制裁的其他详情 legal_basis: type: array items: type: string description: 制裁的法律依据 listed_on: type: array items: type: string nullable: true description: 该实体被列入名单的日期 sanction_list: type: array items: type: string nullable: true description: 制裁名单标识符 sanction_program: type: array items: type: string description: 该实体所列入的制裁项目 sanctioning_authority: type: array items: type: string description: 实施制裁的机构 updated_on: type: array items: type: string description: 制裁条目最后更新的日期 additional_data: type: object description: 未在主要字段中捕获的来自制裁数据源的其他数据 adverse_media_details: type: object properties: sentiment: type: string entity_type: type: string sentiment_score: type: integer adverse_keywords: type: object additionalProperties: type: integer adverse_media_matches: type: array items: type: object properties: country: type: string summary: type: string headline: type: string sentiment: type: string thumbnail: type: string format: uri source_url: type: string format: uri author_name: type: string nullable: true other_sources: type: array items: type: string adverse_keywords: type: array items: type: string sentiment_score: type: integer publication_date: type: string format: date-time additional_information: type: object score: type: number format: float nullable: true minimum: 0 maximum: 100 description: 综合 AML 筛查分数：所有命中项中的最高风险评分（浮点数，0-100）。计算完成前为 `null`。 screened_data: type: object properties: full_name: type: string nationality: type: string date_of_birth: type: string format: date document_number: type: string nullable: true is_ongoing_monitoring_enabled: type: boolean description: 该筛查是否启用了持续 AML 监控。如果为 `true`，系统将定期对该实体重新筛查，且任何新的命中都会更新报告。 next_ongoing_monitoring_bill_date: type: string format: date nullable: true description: >- 此持续监控订阅下次计费的日期（YYYY-MM-DD）。当 `is_ongoing_monitoring_enabled = true` 时，计算方式为上次持续监控计费日期加上 365 天；否则为 `null`。这是计费日期，并非筛查日期，筛查日期请使用 `last_ongoing_screening_at`。 last_ongoing_screening_at: type: string format: date-time nullable: true description: >- 持续监控上次完成对该记录重新筛查的时间，无论结果是否发生变化。如果该记录从未被重新筛查过，则为 `null`；绝不会从启用日期或计费日期进行回填。 last_ongoing_screening_datasets_updated_at: type: string format: date-time nullable: true description: 提供商在进行该次筛查时报告的最新 AML 数据集更新日期。提供商未报告数据集日期时为 `null`；绝不进行估算。 warnings: type: array items: type: object properties: feature: type: string enum: - ID_VERIFICATION - NFC - LIVENESS - FACEMATCH - PROOF_OF_ADDRESS - PHONE - EMAIL - AML - LOCATION - DATABASE_VALIDATION - QUESTIONNAIRE - DOCUMENT_AI - KYB_REGISTRY - KYB_DOCUMENTS - KYB_KEY_PEOPLE - GEOLOCATION - SIGNATURE description: >- 生成此警告的功能。该值标识警告所属的功能块。在 AML 筛查中，这通常是 `AML`，但上述枚举在决策 payload 的所有功能警告中具有权威性。 risk: type: string additional_data: type: object nullable: true log_type: type: string short_description: type: string long_description: type: string node_id: type: string description: 生成此警告的工作流图节点 ID GeolocationCheck: type: object description: 单个位置验证结果，即一个工作流节点已接受的尝试。测量值、不确定性和真实性是独立的键，因此精确的未证明定位与不精确的已证明定位读取结果不同。 properties: node_id: type: string nullable: true description: 生成此结果的工作流节点，从而使包含两个位置验证步骤的工作流保持清晰易读。 status: type: string enum: - Not Finished - Approved - Declined - In Review - Resub Requested description: 此位置验证步骤的功能级状态，根据其警告解析得出。独立于会话的 `status`。 outcome: type: string nullable: true description: 本次尝试中发生的情况。 enum: - verified - low_accuracy - accuracy_undetermined - stale - approximate - denied - restricted - unavailable - timeout - mock_detected - outside_geofence - in_blocked_area - anonymizer_detected - skipped - replay_rejected - unsupported_client - null permission: type: string nullable: true description: 操作系统或浏览器授予的权限。`not_requested` 表示该步骤仅使用连接的 IP 位置，因此绝不会向用户请求权限。 enum: - granted_precise - granted_approximate - denied - restricted - unavailable - timeout - dismissed - not_requested - null latitude: type: number nullable: true description: 定位点的 WGS84 纬度。无定位点时为 `null`。 format: double longitude: type: number nullable: true description: 定位点的 WGS84 经度。无定位点时为 `null`。 format: double accuracy_m: type: number nullable: true description: 不确定性半径（米），基于 `accuracy_confidence` 中的置信度水平。 format: double accuracy_confidence: type: string nullable: true description: >- 平台附加到 `accuracy_m` 的置信度水平：`p95`（浏览器）、`p68`（Android）或 `unspecified`（iOS）。 enum: - p95 - p68 - unspecified - null measured_at: type: string nullable: true description: 设备按自身时钟获取定位的时间。 format: date-time age_seconds: type: integer nullable: true description: 设备完成定位与 Didit 接收到定位之间的秒数间隔。 source: type: string nullable: true description: 定位的来源（当平台指明时）。`ip` 表示位置为连接的 IP 位置。 enum: - gps - fused - network - wifi - cell - browser - unknown - ip - null platform: type: string nullable: true description: 生成该修复的客户端。 enum: - web - ios - android - react_native - flutter - null sdk_version: type: string nullable: true description: 生成该修复的 SDK 版本。 is_mock: type: boolean nullable: true description: >- 当设备指示定位结果来自模拟位置提供程序或模拟软件时为 `true`。当平台未报告该信息时为 `null`（浏览器无法识别）；`null` 不等同于 `false`。 produced_by_accessory: type: boolean nullable: true description: 仅限 iOS：当定位数据来自外部配件时为 `true`。其他情况为 `null`。 integrity: type: string enum: - attested - not_attested - failed - unsupported - not_determined description: 设备证明是否为该修复提供支持。`unsupported` 为浏览器所报告的值，因为 Web 没有证明机制；这并非故障。 country_code: type: string nullable: true description: 定位所在的国家/地区的 ISO 3166-1 alpha-2 代码。 region_code: type: string nullable: true description: 定位点所在的 ISO 3166-2 行政区划。 city: type: string nullable: true description: 最近的有人口聚居地，供审核员参考的标签。 geofence: type: object description: 该步骤的国家/地区及区域规则的结果。 properties: enabled: type: boolean description: 该步骤是否应用了任何国家/地区或区域规则。 result: type: string nullable: true description: >- 该位置相对于规则所处的状态。`undetermined` 表示精度圆跨越了边界或位置未解析到任何国家/地区；这并不能证明其处于范围之外。 enum: - inside - outside - undetermined - null inside_geofence: type: boolean nullable: true description: >- 当 `geofence.result` 为 `inside` 时为 `true`，为 `outside` 时为 `false`，否则为 `null`。 geofence_basis: type: string nullable: true description: 区域结果所判定的位置来源：`device` 定位或连接的 `ip` 位置。 enum: - device - ip - null inside_areas: type: array items: type: string description: 该位置所在的已配置允许区域的 ID 列表。 blocked_areas: type: array items: type: string description: 该位置所在的已配置拦截区域的 ID 列表。 position_source: type: string nullable: true description: 该步骤获取位置的来源，按配置而定：设备与 IP 位置对照检查、仅设备，或仅 IP 位置。 enum: - device_and_ip - device_only - ip_only - null anonymizers: type: object nullable: true description: 连接和设备的情况，各项为 `true`、`false`，若来源无法判断则为 `null`。 properties: vpn: type: boolean nullable: true proxy: type: boolean nullable: true tor: type: boolean nullable: true spoofing: type: boolean nullable: true emulator: type: boolean nullable: true ip_distance_km: type: number nullable: true description: 减去两个不确定性半径后到会话 IP 位置的距离；重叠时为 `0`。 format: double ip_distance_uncertainty_km: type: number nullable: true description: 扣除的合并半径：IP 定位半径加上此次定位修正的准确度。 format: double ip_consistent: type: boolean nullable: true description: '`ip_distance_km` 是否在步骤中配置的距离范围内。当任一方未知时为 `null`。' document_distance_km: type: number nullable: true description: 到身份证件或地址证明上经地理编码地址的距离。若无留存地址则为 `null`。 format: double travel_excused: type: boolean nullable: true description: 该步骤的行程容差是否豁免了与地址的距离。容差关闭时为 `null`。 consecutive_mismatches: type: integer nullable: true description: 在最后一次尝试中：此检查加上同一人先前连续的不匹配项。 attempts: type: integer description: 该节点内的尝试次数序号，从 1 开始。 consent: type: object nullable: true description: 该人在系统提示前给出的同意，记录了他们所看到的用词版本和语言。 properties: accepted_at: type: string format: date-time version: type: string nullable: true locale: type: string nullable: true warnings: type: array items: type: object properties: feature: type: string enum: - ID_VERIFICATION - NFC - LIVENESS - FACEMATCH - PROOF_OF_ADDRESS - PHONE - EMAIL - AML - LOCATION - DATABASE_VALIDATION - QUESTIONNAIRE - DOCUMENT_AI - KYB_REGISTRY - KYB_DOCUMENTS - KYB_KEY_PEOPLE - GEOLOCATION - SIGNATURE description: >- 生成此警告的功能。该值标识警告所属的功能块。每个模块的警告数组通常使用与其模块匹配的值（例如 `phone_verifications[].warnings` 内的 `PHONE`），但上述枚举在决策 payload 的所有功能警告中具有权威性。 risk: type: string additional_data: type: object nullable: true log_type: type: string short_description: type: string long_description: type: string node_id: type: string description: 生成此警告的工作流图节点 ID description: 该位置验证步骤生成的警告，`feature` 设置为 `GEOLOCATION`。警告代码以 `LOCATION_` 开头。 GeolocationAttempt: type: object description: >- 位置验证步骤的一次尝试：字段与 `geolocation_checks[]` 相同（`warnings` 除外），另加 Didit 接收该尝试的时间。 properties: node_id: type: string nullable: true description: 生成此结果的工作流节点，从而使包含两个位置验证步骤的工作流保持清晰易读。 status: type: string enum: - Not Finished - Approved - Declined - In Review - Resub Requested description: 此位置验证步骤的功能级状态，根据其警告解析得出。独立于会话的 `status`。 outcome: type: string nullable: true description: 本次尝试中发生的情况。 enum: - verified - low_accuracy - accuracy_undetermined - stale - approximate - denied - restricted - unavailable - timeout - mock_detected - outside_geofence - in_blocked_area - anonymizer_detected - skipped - replay_rejected - unsupported_client - null permission: type: string nullable: true description: 操作系统或浏览器授予的权限。`not_requested` 表示该步骤仅使用连接的 IP 位置，因此绝不会向用户请求权限。 enum: - granted_precise - granted_approximate - denied - restricted - unavailable - timeout - dismissed - not_requested - null latitude: type: number nullable: true description: 定位点的 WGS84 纬度。无定位点时为 `null`。 format: double longitude: type: number nullable: true description: 定位点的 WGS84 经度。无定位点时为 `null`。 format: double accuracy_m: type: number nullable: true description: 不确定性半径（米），基于 `accuracy_confidence` 中的置信度水平。 format: double accuracy_confidence: type: string nullable: true description: >- 平台附加到 `accuracy_m` 的置信度水平：`p95`（浏览器）、`p68`（Android）或 `unspecified`（iOS）。 enum: - p95 - p68 - unspecified - null measured_at: type: string nullable: true description: 设备按自身时钟获取定位的时间。 format: date-time age_seconds: type: integer nullable: true description: 设备完成定位与 Didit 接收到定位之间的秒数间隔。 source: type: string nullable: true description: 定位的来源（当平台指明时）。`ip` 表示位置为连接的 IP 位置。 enum: - gps - fused - network - wifi - cell - browser - unknown - ip - null platform: type: string nullable: true description: 生成该修复的客户端。 enum: - web - ios - android - react_native - flutter - null sdk_version: type: string nullable: true description: 生成该修复的 SDK 版本。 is_mock: type: boolean nullable: true description: >- 当设备指示定位结果来自模拟位置提供程序或模拟软件时为 `true`。当平台未报告该信息时为 `null`（浏览器无法识别）；`null` 不等同于 `false`。 produced_by_accessory: type: boolean nullable: true description: 仅限 iOS：当定位数据来自外部配件时为 `true`。其他情况为 `null`。 integrity: type: string enum: - attested - not_attested - failed - unsupported - not_determined description: 设备证明是否为该修复提供支持。`unsupported` 为浏览器所报告的值，因为 Web 没有证明机制；这并非故障。 country_code: type: string nullable: true description: 定位所在的国家/地区的 ISO 3166-1 alpha-2 代码。 region_code: type: string nullable: true description: 定位点所在的 ISO 3166-2 行政区划。 city: type: string nullable: true description: 最近的有人口聚居地，供审核员参考的标签。 geofence: type: object description: 该步骤的国家/地区及区域规则的结果。 properties: enabled: type: boolean description: 该步骤是否应用了任何国家/地区或区域规则。 result: type: string nullable: true description: >- 该位置相对于规则所处的状态。`undetermined` 表示精度圆跨越了边界或位置未解析到任何国家/地区；这并不能证明其处于范围之外。 enum: - inside - outside - undetermined - null inside_geofence: type: boolean nullable: true description: >- 当 `geofence.result` 为 `inside` 时为 `true`，为 `outside` 时为 `false`，否则为 `null`。 geofence_basis: type: string nullable: true description: 区域结果所判定的位置来源：`device` 定位或连接的 `ip` 位置。 enum: - device - ip - null inside_areas: type: array items: type: string description: 该位置所在的已配置允许区域的 ID 列表。 blocked_areas: type: array items: type: string description: 该位置所在的已配置拦截区域的 ID 列表。 position_source: type: string nullable: true description: 该步骤获取位置的来源，按配置而定：设备与 IP 位置对照检查、仅设备，或仅 IP 位置。 enum: - device_and_ip - device_only - ip_only - null anonymizers: type: object nullable: true description: 连接和设备的情况，各项为 `true`、`false`，若来源无法判断则为 `null`。 properties: vpn: type: boolean nullable: true proxy: type: boolean nullable: true tor: type: boolean nullable: true spoofing: type: boolean nullable: true emulator: type: boolean nullable: true ip_distance_km: type: number nullable: true description: 减去两个不确定性半径后到会话 IP 位置的距离；重叠时为 `0`。 format: double ip_distance_uncertainty_km: type: number nullable: true description: 扣除的合并半径：IP 定位半径加上此次定位修正的准确度。 format: double ip_consistent: type: boolean nullable: true description: '`ip_distance_km` 是否在步骤中配置的距离范围内。当任一方未知时为 `null`。' document_distance_km: type: number nullable: true description: 到身份证件或地址证明上经地理编码地址的距离。若无留存地址则为 `null`。 format: double travel_excused: type: boolean nullable: true description: 该步骤的行程容差是否豁免了与地址的距离。容差关闭时为 `null`。 consecutive_mismatches: type: integer nullable: true description: 在最后一次尝试中：此检查加上同一人先前连续的不匹配项。 attempts: type: integer description: 该节点内的尝试次数序号，从 1 开始。 consent: type: object nullable: true description: 该人在系统提示前给出的同意，记录了他们所看到的用词版本和语言。 properties: accepted_at: type: string format: date-time version: type: string nullable: true locale: type: string nullable: true received_at: type: string nullable: true description: Didit 收到此次尝试的时间。 format: date-time created_at: type: string format: date-time KYBRegistryShareholding: type: object nullable: true description: >- 所有人持有的权益，对所有国家/地区和登记来源采用相同的结构。当登记来源未声明持股时为 Null。区间（例如英国 PSC 的 25-50%）不属于持股权益：`percentage` 为 null，区间保留在 `ownership_min_shares` / `ownership_max_shares` 中。 properties: share_class: type: string nullable: true description: 登记机构命名的股份类别或类型。 number_of_shares: type: number nullable: true description: 持有的股份数量。 currency: type: string nullable: true description: 以下数值对应的 ISO 4217 货币。 nominal_value: type: number nullable: true description: 每股面值。 total_value: type: number nullable: true description: 持仓总价值。 percentage: type: number nullable: true description: 以百分比表示的精确持股比例，精确到小数点后四位。 required: - share_class - number_of_shares - currency - nominal_value - total_value - percentage KYBRegistryAddress: type: object description: 登记机构声明的地址，对于每个国家/地区和登记来源均采用相同格式。每个键始终存在；登记机构未公布的部分为 null。 properties: type: type: string nullable: true description: >- 小写形式的地址类型：注册办事处为 `registered`；其他类型按登记处的命名方式（例如 `postal`、`office`）。当登记处未说明该地址是什么类型时为 `null`。 address: type: string description: 单行格式的完整地址。每个地址中始终都提供该完整地址。 street: type: string nullable: true description: 街道与门牌号。 city: type: string nullable: true description: 城市或地区。 postal_code: type: string nullable: true description: 邮政编码。 region: type: string nullable: true description: 地区、州或省。 country_code: type: string nullable: true description: ISO 3166-1 alpha-2 国家/地区代码。 description: type: string nullable: true description: 登记处针对该地址自有的标签（如有）。 required: - type - address - street - city - postal_code - region - country_code - description KYBRegistryIndustry: type: object description: 登记机构对企业进行分类的经营活动，对于每个国家/地区和登记来源均采用相同格式。 properties: code: type: string nullable: true description: 公司登记载明的活动代码（例如 `73110`）。 description: type: string nullable: true description: 活动标签（若公司登记已发布）。 scheme: type: string nullable: true description: >- 分类体系，无论哪个来源报告，每个体系对应一个名称：`UK SIC 2007`、`US SIC`、`NACE Rev. 2`、`NACE Rev. 2.1`、`NAF Rev. 2`、`CNAE`、`SBI`、`NOGA 2008`、`CAE Rev. 4`、`Canada SIC 1977`；其他国家体系保留登记机构自身的名称。当登记机构未指明体系名称时为 Null。 is_primary: type: boolean description: 如果是公司的主要业务活动，则为 true。列表非空时恰好有一项为主活动。 required: - code - description - scheme - is_primary KYBRegistryData: type: object nullable: true description: >- Didit 为该企业标准化的公司登记详情：股权结构结果（`ownership_error`、`section_errors`、`ubo_resolution`、`lite_enrichment`）、使用 update-data 所做的更正，以及没有专属字段的公司登记事实。它绝不会携带登记来源自身的记录。每个键均为可选，且仅在企业具有相应值时才存在；可能会添加新键。对于规范字段（`addresses`、`industries`、`ownership`、`beneficial_owners[].shareholding`）涵盖的任何内容，请直接读取这些规范字段。 properties: company_name: type: string description: 在控制台中更正后的企业名称。 registration_number: type: string description: 公司登记或控制台更正注明的注册号。 country_code: type: string description: 登记处或控制台更正所声明的注册国家/地区。 region: type: string description: 注册的地区或州/省。 incorporation_date: type: string description: 注册成立日期（ISO 8601）。 registration_date: type: string description: 公司登记注明的注册日期（ISO 8601，独立于成立日期时提供）。 dissolution_date: type: string description: 注销日期（ISO 8601），由登记机构提供时包含。 tax_number: type: string description: 税号。 vat_number: type: string description: 增值税号。 legal_address: type: string description: 在控制台中更正后的法定地址。 registered_address: type: string description: 登记机构列明的注册地址。 company_type: type: string description: 法律形式。 registry_status: type: string description: 企业在公司登记的状态。 verification_status: type: string description: 验证状态。 alternative_names: type: string description: 该公司当前或曾经使用的其他商业名称。 nature_of_business: type: string description: 活动描述。 registered_capital: type: string description: 印示的注册资本。 registered_capital_amount: type: string description: 注册资本金额，以十进制字符串表示。 registered_capital_currency: type: string description: 注册资本货币（ISO 4217）。 website: type: string description: 网站。 email: type: string description: 联系邮箱。 phone: type: string description: 联系电话。 legal_entity_identifier: type: string description: 全球法人机构识别编码（LEI）。 location_of_registration: type: string description: 注册地。 control_scheme: type: string description: 公司登记提供该信息时的治理方案。 ownership_error: type: string enum: - no_owners_on_record - no_natural_person_owner - ownership_section_unavailable - company_not_found - ambiguous_company_match - missing_registration_number - entity_type_not_covered - provider_unavailable - other description: >- 所请求的股权结构等级未能交付的原因，代码与 `ownership.unavailable_reason` 相同。`no_owners_on_record`（登记机构已响应但未列出任何所有人）与 `ownership_section_unavailable`（登记机构未返回股权结构部分）是不同的结果。 section_errors: type: object description: >- 公司登记未返回的板块，以板块（`officers`、`shareholders`、`group_structure`）为键。此处列出的板块从未投递过：其旁的空列表并不表示关于该企业的任何信息。 additionalProperties: $ref: '#/components/schemas/KYBRegistrySectionError' ubo_resolution: $ref: '#/components/schemas/KYBRegistryUboResolution' lite_enrichment: $ref: '#/components/schemas/KYBRegistryLiteEnrichment' registry_metadata: type: object additionalProperties: oneOf: - type: string - type: number - type: boolean description: 公司登记处针对该企业自有的原始字段，以登记处命名为键，作为普通值返回（旧版记录）。仅包含审核确认为登记事实的字段。 registry_sources: type: array description: 读取该记录的官方登记册（历史遗留记录）。未标明其他来源名称。 items: $ref: '#/components/schemas/KYBRegistrySource' previous_names: type: array items: type: string description: 企业以往注册所使用的名称（历史记录）。 parent_companies: type: array items: type: string description: 登记处列出的母公司（历史记录）。 documents_available: type: integer description: 登记处为该公司提供的备案记录数量（历史记录）。 KYBRegistryOwnership: type: object description: 股权结构（股东 / UBO）等级的结果，对所有国家/地区和登记册来源采用相同的结构。 properties: status: type: string nullable: true enum: - not_requested - pending - delivered - not_held - unavailable - null description: >- 当登记处发布股权结构时为 `delivered`；当股权登记处已响应且完全未列出该企业时为 `not_held`（参见 `unavailable_reason`）；当由于任何其他原因未提供股权结构数据时为 `unavailable`（参见 `unavailable_reason`）；当登记处仍在获取数据时为 `pending`；对于 Basic 等级为 `not_requested`。 tier_requested: type: string nullable: true enum: - basic - shareholders - ubo - null description: 工作流订购的等级。 tier_delivered: type: string nullable: true enum: - basic - shareholders - ubo - null description: 登记机构交付（且计费）的等级。仅返回直接股东的 UBO 请求为 `shareholders`。 unavailable_reason: type: string nullable: true enum: - no_owners_on_record - no_natural_person_owner - ownership_section_unavailable - company_not_found - ambiguous_company_match - missing_registration_number - entity_type_not_covered - provider_unavailable - other - null description: 所请求的股权结构等级未能交付的原因。除非 `status` 为 `unavailable` 或 `pending`，否则为 null。 direct_ownership_complete: type: boolean nullable: true description: >- 当直接股东申报的持股比例总和等于 100%（允许 1 个百分点的四舍五入误差）时为 true；否则为 false；未提供股权结构或未申报持股比例时为 null。 unresolved: type: array description: 登记处无法解析的股权链部分，例如记录中直接所有者之上不存在集团架构。 items: type: object properties: reason: type: string section: type: string nullable: true required: - status - tier_requested - tier_delivered - unavailable_reason - direct_ownership_complete - unresolved KYBOwnershipStructure: type: object nullable: true description: >- 登记处证明的股权结构表，以交付股权结构等级时的状态为准：直接 `shareholders` 和 `beneficial_owners`。当登记处未证明任何股权结构时为 null。它从不携带登记处来源本身的行；如需获取当前记录，请读取 `company.beneficial_owners` 和 `company.ownership`。 properties: shareholders: type: array items: $ref: '#/components/schemas/KYBOwnershipStructureOwner' beneficial_owners: type: array items: $ref: '#/components/schemas/KYBOwnershipStructureOwner' required: - shareholders - beneficial_owners InvestigatorBlock: type: object nullable: true description: >- 该项最新的调查员审核结果，若从未审核过则为 null。由 V3 会话和企业会话决策携带（并通过 `status.updated` Webhook 发送）。 properties: run_id: type: string format: uuid status: type: string enum: - running - completed - failed stage: type: string enum: - shadow - live queue: type: string enum: - kyc - kyb - aml - transactions - cases is_open: type: boolean recommendation: type: string enum: - approve - decline - escalate - request nullable: true recommendation_detail: type: string nullable: true confidence: type: string enum: - high - moderate - low nullable: true summary: type: string nullable: true ready_to_accept: type: boolean prepared_at: type: string format: date-time nullable: true automated: type: boolean description: 调查员自行做出的决策，即使该决策随后被覆盖。 decided_by: type: string enum: - investigator - member nullable: true decision: nullable: true allOf: - $ref: '#/components/schemas/InvestigatorDecision' type: object BiometricRetention: type: object description: 此会话的实时生物特征数据被删除的时间。 required: - jurisdictions - deletes_at properties: jurisdictions: type: array items: type: string description: 其生物识别规则对该人员设定了删除时限的美国州代码（若州未知则为 `US`）。若不适用则为空。 deletes_at: type: string format: date-time nullable: true description: >- 根据您应用的数据保留设置以及该人员所在管辖区的法定限制（如果适用），此会话的活体生物特征数据（人脸图像和模板）被删除的日期。尚无适用日期时为 `null`。 SocialFootprintPlatform: type: object properties: platform: type: string description: 平台标识符。 example: whatsapp category: type: string description: >- 平台类别，例如 MESSAGING、SOCIAL_MEDIA、ECOMMERCE、PROFESSIONAL、EMAIL_PROVIDER。 example: MESSAGING scope: type: string enum: - global - local description: 全球平台为 `global`，特定区域平台为 `local`。 example: global SocialFootprintCategorySummary: type: object properties: registered: type: integer nullable: true description: 该类别中已确认注册的平台。 example: 2 ratio: type: number format: float nullable: true description: 该类别已检查平台中已注册的比例，0.0-1.0。 example: 0.6667 SocialFootprintProfile: type: object properties: name: type: string nullable: true description: 个人资料名称（若平台公开）。 photo: type: string nullable: true description: 个人资料照片 URL（若平台公开）。 about: type: string nullable: true description: 个人资料简介/生平文本（若平台公开）。 privacy_status: type: string nullable: true enum: - PUBLIC - PRIVATE - null description: 个人资料公开范围（若平台公开）。 business_account: type: boolean nullable: true description: 该资料是否为企业账户（若平台提供该信息）。 SignatureFieldResult: type: object description: >- 已签署证件的一个字段，包含其在此签署人副本上的值。请参阅 [Fields](/zh/core-technology/electronic-signature/report-electronic-signature#字段)。 properties: key: type: string description: 字段的键，与 `sign.field_values` 中使用的相同。 type: type: string enum: - signature - initials - full_name - date_signed - text - checkbox - email - data role: type: string enum: - verified_person - legal_representative - key_people label: type: string page: type: integer description: 页码，从 1 开始。对于 Word 证件，指转换后 PDF 的页码。 x: type: number description: 左边缘，占页面宽度的比例。 'y': type: number description: 顶部边缘，以页面高度的比例表示。 width: type: number description: 宽度，占页面宽度的比例。 height: type: number description: 高度，表示为页面高度的比例。 required: type: boolean value: nullable: true description: >- `text`、`email`、`full_name`、`date_signed` 和 `data` 为字符串，`checkbox` 为布尔值，应用的签名或缩写签名为 `true`。为空时为 `null`。 display_value: type: string nullable: true description: 页面上印刻的值：日期采用字段的 `date_format`，复选框为 `Yes` 或 `No`，签名或姓名缩写为 `Signed`。 value_source: type: string nullable: true enum: - signer - identity - contact - company - session - metadata - api - signing_time - null description: >- 该值的来源：`signer`（由签署人输入、勾选或应用）、`identity`（核验的证件）、`contact`（核验的邮箱或电话）、`company`（核验的公司）、`session`（`vendor_data`）、`metadata`、`api`（`sign.field_values`）或 `signing_time`（签署日期）。 filled_at: type: string format: date-time nullable: true image_url: type: string nullable: true description: >- 仅限签名和姓名首字母：所应用图像的路径。请参阅[下载签名图像](/zh/sessions-api/electronic-signature/download-field-image)。 value_unavailable_reason: type: string nullable: true enum: - source_empty - null description: >- 当预填字段在会话中没有值且 `signature_field_data_missing_action` 允许签署人仍然签名时，为 `source_empty`。 KYBRegistrySectionError: type: object description: 公司登记未返回的部分。 properties: status_code: type: integer nullable: true description: 登记机关针对该板块返回的状态。 required: - status_code KYBRegistryUboResolution: type: object description: UBO 层级遍历公司上层股权结构链的方式。 properties: parent_chain: type: array description: 从最终母公司到该公司的企业母实体层级。 items: $ref: '#/components/schemas/KYBRegistryGroupCompany' subsidiaries: type: array description: 企业集团内直接隶属于该企业的下级公司。 items: $ref: '#/components/schemas/KYBRegistryGroupCompany' unresolved: type: array description: 登记处无法解析的股权链部分（与 `ownership.unresolved` 条目相同）。 items: type: object properties: reason: type: string description: >- 原因，例如 `no_group_structure_on_record`、`selected_company_not_in_group_structure` 或 `section_error`。 section: type: string nullable: true description: 相关的部分，例如 `group_structure`。 required: - reason - section required: - parent_chain - subsidiaries - unresolved KYBRegistryLiteEnrichment: type: object description: 由该国家/地区的其他登记数据源填充的空白 Lite 档案字段。数据源名称未公开。 properties: fields: type: array items: type: string description: 已填写的企业字段。 people_added: type: integer description: 添加的高管或所有者数量。 required: - fields - people_added KYBRegistrySource: type: object description: 读取该记录的官方登记册。仅列出官方政府登记册、监管机构和官方标识符系统；忽略任何其他来源。 properties: name: type: string description: 登记机构名称，例如 `UK Companies House`。 source_type: type: string enum: - official description: 始终为 `official`。 required: - name - source_type KYBOwnershipStructureOwner: type: object description: >- 股权结构快照中的一个所有者：与 `company.beneficial_owners[]` 具有相同的登记身份与持股份额，以及其规范化的 `shareholding`。 properties: name: type: string nullable: true description: 登记处注明的所有者名称。 first_name: type: string nullable: true description: 自然人的名字（当公司登记注明时）。 last_name: type: string nullable: true description: 自然人的姓氏，当公司登记有明确载明时提供。 date_of_birth: type: string nullable: true description: 公司登记处公布时的出生日期（ISO 8601）。 country_of_birth: type: string nullable: true description: 出生国家/地区（若登记处公布）。 company_name: type: string nullable: true description: 企业名称，适用于企业所有者。 registration_number: type: string nullable: true description: 企业所有者的注册号。 entity_type: type: string nullable: true enum: - person - company - null description: 所有者是自然人还是公司。 nationality: type: string nullable: true description: 登记处注明的国籍。 designation: type: string nullable: true description: 登记册上载明的所有人头衔或角色。 roles: type: array items: type: string description: 直接持有人为 `shareholder`，实际受益人为 `ubo`。 ownership_min_shares: type: string nullable: true description: 持股比例下限，以百分比表示（对于确定比例，其值等于上限）。 ownership_max_shares: type: string nullable: true description: 持股比例上限，以百分比表示。 voting_min_shares: type: string nullable: true description: 投票权下限，以百分比表示。 voting_max_shares: type: string nullable: true description: 投票权上限，以百分比表示。 appointment_date: type: string nullable: true description: 持股或任命开始的日期（ISO 8601）。 is_active: type: boolean nullable: true description: 对于前所有者为 False。 shareholding: $ref: '#/components/schemas/KYBRegistryShareholding' required: - name - first_name - last_name - date_of_birth - country_of_birth - company_name - registration_number - entity_type - nationality - designation - roles - ownership_min_shares - ownership_max_shares - voting_min_shares - voting_max_shares - appointment_date - is_active - shareholding InvestigatorDecision: type: object description: >- 该项离开调查员队列的方式。`decided_by`、`original_outcome` 和 `overrides` 由接受和覆盖 endpoint 以及报告返回；会话决策的 `investigator` 块包含其他字段。 properties: outcome: type: string enum: - accepted - edited - overridden - decided_elsewhere - automated description: >- `accepted` 或 `edited` 采纳了建议（`edited` 包含重写的陈述），`overridden` 采取了其他操作，`decided_elsewhere` 是在报告打开期间在 Investigator 之外做出的决策，`automated` 是 Investigator 自行做出的决策。 action: type: string enum: - approve - decline - escalate - request actor_email: type: string nullable: true actor_name: type: string nullable: true override_category: type: string enum: - missing_context - needs_information - policy_differs - evidence_misread - other - '' nullable: true override_reason: type: string nullable: true final_status: type: string description: 作出决策后该项目的状态。 agreed: type: boolean description: 决策是否与建议一致。 nullable: true decided_at: type: string format: date-time billed: type: boolean description: 该审核已扣费。 decided_by: type: string enum: - investigator - member original_outcome: type: object description: Investigator 自行做出的决策，未受后续覆盖修改。对于团队做出的决策，该值为 null。 properties: action: type: string final_status: type: string decided_at: type: string format: date-time nullable: true overrides: type: array description: 调查员自行做出的决策的每次覆盖，按时间正序排列。 items: type: object properties: action: type: string actor_email: type: string nullable: true actor_name: type: string nullable: true override_category: type: string override_reason: type: string previous_status: type: string final_status: type: string agreed: type: boolean nullable: true overridden_at: type: string format: date-time KYBRegistryGroupCompany: type: object description: 根据公司登记身份确定的企业集团所属公司。 properties: name: type: string nullable: true description: 企业名称。 country_code: type: string nullable: true description: 注册国家/地区。 registration_number: type: string nullable: true description: 注册号。 required: - name - country_code - registration_number 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.