数据模型 (Data Models)

概述

每个针对具体功能的报告均遵循 service-didit-verification 中定义的 V3 序列化器结构。同一对象出现在三个位置，因此您在此处看到的架构是这些位置之间唯一的真实信息来源：

GET /v3/session/{sessionId}/decision/：每个功能均作为复数形式的数组返回（id_verifications[]、nfc_verifications[]、liveness_checks[]、face_matches[]、poa_verifications[]、phone_verifications[]、email_verifications[]、aml_screenings[]、ip_analyses[]、database_validations[]、questionnaire_responses[]、signatures[]、bank_verifications[]（请参阅银行验证方式），以及 KYB 对应的 registry_checks[]、document_verifications[]、key_people_checks[]）。
Webhook payload（status.updated、data.updated）：在 decision 外层结构中使用相同的格式。
独立 API：单对象响应（人脸搜索、年龄估算、生物识别认证）复用相同的字段集。

V3 引入了多实例工作流：每个功能对象都包含一个 node_id，用于将报告锚定到生成它的工作流图谱节点。V2 endpoint（单数形式的 kyc、face、aml 等）保持向后兼容，但仅返回第一个实例。

常见字段

每个报告对象都会公开以下字段：

字段	类型	描述
`status`	string	功能级生命周期状态：状态枚举中的值之一。来源：`common/config/choices.py:FeatureStatusChoices`（第 343-348 行）。父会话的顶层 `status` 使用更广泛的会话枚举（`StatusChoices`，第 106-117 行）。
`node_id`	string \| null	工作流图谱节点标识符。针对 V3 多实例工作流填充；对于旧版单功能会话为 `null`。
`warnings`	警告对象数组	针对此功能和 `node_id` 过滤的风险信号。由 `Session.get_logs(...)`（`sessions/models/session.py:1611`）返回。

媒体字段（portrait_image、front_image、document_file，…）是具有有限有效期的预签名 URL，请及时下载它们，而不是持久保存该 URL。示例中将其显示为 https://<media-host>/...。

警告对象

每个 warnings[] 数组中都会返回。架构来自 logs/serializers/log.py:8-65（LogV3Serializer）。

字段	类型	可为空	描述	示例
`feature`	string (enum)	否	发出警告的功能。取值来自 `LogWarningChoices`（`common/config/choices.py:190-204`）：`ID_VERIFICATION`、`NFC`、`LIVENESS`、`FACEMATCH`、`PROOF_OF_ADDRESS`、`PHONE`、`EMAIL`、`AML`、`LOCATION`、`DATABASE_VALIDATION`、`QUESTIONNAIRE`、`KYB_REGISTRY`、`KYB_DOCUMENTS`、`KYB_KEY_PEOPLE`。	`"ID_VERIFICATION"`
`risk`	string	否	稳定的风险代码（例如 `DOCUMENT_EXPIRED`、`LOW_LIVENESS_SCORE`）。取值来自 `logs/choices.py:RiskChoices`。用作描述表的键。	`"DOCUMENT_EXPIRED"`
`additional_data`	object \| null	是	风险专属上下文（例如分数阈值、匹配字段）。格式因风险代码而异。	`{ "score": 42.1, "threshold": 70 }`
`log_type`	string (enum)	否	`error`、`warning`、`information` 之一。来自 `LogTypeChoices`（`common/config/choices.py:207-210`）。	`"error"`
`short_description`	string	否	人类可读的风险标签。来自 `logs/choices.py:RISK_SHORT_DESCRIPTIONS`。	`"Document expired"`
`long_description`	string	否	适合展示给终端用户的较长人类可读解释。来自 `logs/choices.py:RISK_LONG_DESCRIPTIONS`。	`"The document's expiration date has passed, rendering it no longer valid for use."`
`node_id`	string \| null	是	触发该警告对应的工作流图谱节点。对于没有 `node_id` 的旧版 V2 日志为 `null`。	`"first_id_verification"`

{
  "feature": "ID_VERIFICATION",
  "risk": "DOCUMENT_EXPIRED",
  "additional_data": null,
  "log_type": "error",
  "short_description": "Document expired",
  "long_description": "The document's expiration date has passed, rendering it no longer valid for use.",
  "node_id": "first_id_verification"
}

报告对象

其余章节分别介绍各功能对应的报告对象。三级标题文字特意保持稳定，以便其他文档直接深度链接到这些标题。

身份证件验证

用户每提交一份 KYC/身份证件，都会返回此对象。它会出现在 GET /v3/session/{sessionId}/decision/ 的 id_verifications[] 中，也会出现在 V2 响应的 kyc 字段内。来源：kyc/serializers/kyc.py:383-414（IDVerificationV3Serializer，继承自 kyc/serializers/kyc.py:320-380 中的 IDVerificationV2Serializer）。

字段	类型	可为空	说明	示例
`status`	字符串	否	参见状态枚举。	`"Approved"`
`document_type`	字符串	是	便于阅读的证件类别（`Passport`、`Identity Card`、`Driver's License`、`Residence Permit`、`Health Insurance Card`、`Tax Card`、`Social Security Card`、`Work Permit`、`Visa`、`Public Service Card`、`Birth Certificate`、`Firearm License`、`Other`）。来源：`DOC_TYPE_MAPPING`（`common/config/choices.py:1275-1289`）。	`"Passport"`
`document_subtype`	字符串	是	来自 Didit 证件注册表的证件子类型代码，已按工作流的证件设置进行过滤。特定地区的证件代码中包含地区信息。完整代码列表：证件子类型。	`"QUEENSLAND_DRIVER_LICENSE_GENERIC"`
`document_number`	字符串	是	OCR 提取的证件号码。	`"AB1234567"`
`personal_number`	字符串	是	OCR 提取的个人或国家身份标识号。	`"99999999R"`
`portrait_image`	字符串（URL）	是	人脸裁剪图的预签名 URL。	`"https://<media-host>/.../portrait.jpg?..."`
`front_image`	字符串（URL）	是	清理后证件正面的预签名 URL。	`"https://<media-host>/.../front.jpg?..."`
`front_video`	字符串（URL）	是	证件正面采集视频的预签名 URL（如有）。	`"https://<media-host>/.../front.mp4?..."`
`back_image`	字符串（URL）	是	清理后证件背面的预签名 URL。	`"https://<media-host>/.../back.jpg?..."`
`back_video`	字符串（URL）	是	证件背面采集视频的预签名 URL。	`null`
`full_front_image`	字符串（URL）	是	未裁剪（全画面）的证件正面采集图像。	`"https://<media-host>/.../full_front.jpg?..."`
`full_back_image`	字符串（URL）	是	未裁剪（全画面）的证件背面采集图像。	`null`
`front_image_camera_front`	字符串（URL）	是	与证件正面同时拍摄的前置摄像头图像。	`null`
`back_image_camera_front`	字符串（URL）	是	与证件背面同时拍摄的前置摄像头图像。	`null`
`front_image_camera_front_face_match_score`	浮点数（0-100）	是	证件人像与前置摄像头采集图像之间的相似度。	`null`
`back_image_camera_front_face_match_score`	浮点数（0-100）	是	同上，但针对背面采集图像。	`null`
`document_selfie_face_matches`	数组	是	与证件采集时拍摄的自拍照匹配的历史会话或人脸黑名单条目。条目格式与 `liveness_checks[].matches` 相同。搜索未执行时为 `null`，无匹配时为 `[]`。	`null`
`front_image_quality_score`	对象	是	正面图像的质量指标：0 至 100 分的评分（`focus_score`、`brightness_score`、`resolution_score`、`overall_score`），以及 `brightness_issue`（`ok`、`too_dark`、`too_bright`）和 `is_document_fully_visible`（布尔值）。	`{ "focus_score": 91.0, "overall_score": 88.5 }`
`back_image_quality_score`	对象	是	结构与 `front_image_quality_score` 相同。	`null`
`date_of_birth`	字符串（YYYY-MM-DD）	是	OCR 提取的出生日期。	`"1990-05-12"`
`age`	整数	是	提取时按年计算的年龄。	`35`
`expiration_date`	字符串（YYYY-MM-DD）	是	证件到期日期。	`"2032-05-11"`
`date_of_issue`	字符串（YYYY-MM-DD）	是	证件签发日期。	`"2022-05-11"`
`issuing_state`	字符串（ISO 3166-1 alpha-3）	是	签发国家/地区代码。	`"ESP"`
`issuing_state_name`	字符串	是	本地化的签发国家/地区名称。	`"Spain"`
`first_name`	字符串	是	OCR 提取的名字。	`"María"`
`last_name`	字符串	是	OCR 提取的姓氏。	`"García López"`
`full_name`	字符串	是	完整的标准化姓名（由供应商提供）。	`"María García López"`
`gender`	字符串	是	`M`、`F` 或供应商提供的其他值。	`"F"`
`address`	字符串	是	OCR 提取的原始地址行。	`"Calle Mayor 1, 28001 Madrid"`
`formatted_address`	字符串	是	地理编码后的格式化地址（可解析时）。	`"Calle Mayor 1, 28001 Madrid, Spain"`
`parsed_address`	对象	是	结构化的地理编码地址：`street_1`、`street_2`、`city`、`region`、`country`、`postal_code`、`address_type`、`formatted_address`、`document_location`（`{latitude, longitude}`）、`raw_results`、`is_best_match`。来源：`kyc/utils/address.py:147-197`。	`{ "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001", "country": "ES" }`
`place_of_birth`	字符串	是	OCR 提取的出生地。	`"Madrid"`
`marital_status`	字符串	是	可提取时提供。	`null`
`nationality`	字符串（ISO 3166-1 alpha-3）	是	OCR 提取的国籍。	`"ESP"`
`extra_fields`	对象	是	标准架构未涵盖的特定证件类型字段（例如驾照类别）。	`{ "DL Class": "B" }`
`mrz`	对象	是	存在时的已解析 MRZ 字段（`document_number`、`birth_date`、`expiry_date`、`surname`、`given_names`、…）。	`{ "document_number": "AB1234567", "surname": "GARCIA", "given_names": "MARIA" }`
`extra_files`	字符串（URL）数组	否	任何其他已上传文件的预签名 URL。	`[]`
`matches`	对象数组	否	跨会话证件匹配结果。每一项为：`{ session_id, session_number, vendor_data, verification_date, user_details: { name, document_type, document_number }, status, is_blocklisted, api_service, front_image_url }`。`front_image_url` 为预签名 URL。	`[]`
`verification_method`	string	否	生成此行的身份证件验证方式：`document`、`id_lookup` 或 `wallet`。对于拍摄的证件，始终为 `document`，包括在其他方式推出之前创建的所有会话。	`"id_lookup"`
`assurance`	string	否	根据 `verification_method` 得出的保证等级：`documentary`、`data_match` 或 `cryptographic`。	`"data_match"`
`wallet_provider`	string \| null	是	生成此行的钱包在钱包目录中的 ID（`mitid`、`bankid_se`、`itsme` 等）。否则为 `null`。	`"mitid"`
`fallback_from`	object \| null	是	非证件方式结束身份证件验证步骤的原因：`{ method, reason, action }`。当数据源查询或钱包登录失败时设置：如果该国家/地区的开关为 `decline`（`action: "decline"`），则设置在已拒绝的行上；如果为 `fallback_to_document`（`action: "fallback_to_document"`），则设置在用户继续使用的证件验证上。未记录更早的非证件失败时为 `null`。	`{ "method": "id_lookup", "reason": "no_match", "action": "decline" }`
`id_lookup`	object \| null	是	来源证据，仅当 `verification_method` 为 `id_lookup` 时存在：`source`（所查询的确切数据源，多数国家为政府登记处，部分国家为信用局或居住记录档案）、`checked_at`、`attempts`、`max_attempts`、`outcome`（`match`、`partial_match`、`no_match`、`provider_error`、`format_rejected`）、`comparison[]`（`{ field, label, provided, record, result }`；`field` 为 `identification_number`、`full_name`、`date_of_birth`、`address` 之一，`result` 为 `match`、`partial` 或 `no_match`；早期版本可能包含带有 `error` 的 `provider` 行）、`source_errors[]`（当前预发布环境：独立的来源诊断信息；请确认生产环境的推出情况）、`registry_portrait`（预签名 URL，仅适用于返回该内容的数据源）以及 `face_match_score`。	见下文
`wallet_verification`	object \| null	是	凭证证据，仅当 `verification_method` 为 `wallet` 时存在：`provider`、`provider_name`、`issuing_authority`、`issuing_country`、`credential_type`、`level_of_assurance`（`low`、`substantial`、`high`）、`verified_at`、`signature_valid`、`attributes`（钱包共享的内容）、`portrait`（钱包共享人像时的预签名 URL）以及 `face_match_score`。	见下文
`document_liveness`	object \| null	是	按欺诈类型（`portrait_replace`、`printed_copy`、`screen_replay`）给出的证件活体分数，无论是否触发警告都会返回。每项包括：`score`（0-100，越高越可能为真实证件；取较低的值，即决策所使用的值）、`front`、`back`、`decline_threshold`、`review_threshold`、`bucket`（`approve`、`review`、`decline` 或 `null`）。阈值和分档在评估时保存；当历史评估证据不可用时，三者均为 `null`，但已存储的分数仍可见。检查未运行时为 `null`。参见证件活体分数。仅限 V3。	`{ "portrait_replace": { "score": 96.46, "bucket": "approve" } }`
`node_id`	string \| null	是	工作流节点标识符（V3）。	`"first_id_verification"`
`warnings`	array	否	参见警告对象。	`[]`
`region`	string	是	签发国家/地区的地区或州（如果证件标明了地区）。	`"CA"`
`extracted_data`	object	是	向持证人展示以供核对的证件提取数据快照，与确认后的值并列保存，便于您对比。未要求持证人核对时为 `null`。
`barcodes`	array of objects	否	从证件条码读取的数据，每个条码一项，包含 `type`、`position`、`data`、`data_raw` 和 `side`。没有条码时为 `[]`。	`[]`

{
  "status": "Approved",
  "document_type": "Passport",
  "document_subtype": "PASSPORT_GENERIC",
  "document_number": "AB1234567",
  "personal_number": "99999999R",
  "portrait_image": "https://<media-host>/.../portrait.jpg?signature=...",
  "front_image": "https://<media-host>/.../front.jpg?signature=...",
  "front_video": null,
  "back_image": "https://<media-host>/.../back.jpg?signature=...",
  "back_video": null,
  "full_front_image": "https://<media-host>/.../full_front.jpg?signature=...",
  "full_back_image": null,
  "front_image_camera_front": null,
  "back_image_camera_front": null,
  "front_image_camera_front_face_match_score": null,
  "back_image_camera_front_face_match_score": null,
  "front_image_quality_score": {
    "focus_score": 91.0,
    "brightness_score": 88.0,
    "brightness_issue": "ok",
    "is_document_fully_visible": true,
    "resolution_score": 95.0,
    "overall_score": 88.5
  },
  "back_image_quality_score": null,
  "date_of_birth": "1990-05-12",
  "age": 35,
  "expiration_date": "2032-05-11",
  "date_of_issue": "2022-05-11",
  "issuing_state": "ESP",
  "issuing_state_name": "Spain",
  "first_name": "María",
  "last_name": "García López",
  "full_name": "María García López",
  "gender": "F",
  "address": "Calle Mayor 1, 28001 Madrid",
  "formatted_address": "Calle Mayor 1, 28001 Madrid, Spain",
  "parsed_address": { "street_1": "Calle Mayor 1", "street_2": null, "city": "Madrid", "region": "Madrid", "postal_code": "28001", "country": "ES", "address_type": "Calle" },
  "place_of_birth": "Madrid",
  "marital_status": null,
  "nationality": "ESP",
  "extra_fields": {},
  "mrz": {
    "document_number": "AB1234567",
    "surname": "GARCIA",
    "given_names": "MARIA",
    "birth_date": "900512",
    "expiry_date": "320511"
  },
  "extra_files": [],
  "matches": [],
  "node_id": "first_id_verification",
  "verification_method": "document",
  "assurance": "documentary",
  "wallet_provider": null,
  "fallback_from": null,
  "id_lookup": null,
  "wallet_verification": null,
  "document_liveness": {
    "portrait_replace": {
      "score": 96.46,
      "front": 96.46,
      "back": 98.2,
      "decline_threshold": 35,
      "review_threshold": 70,
      "bucket": "approve"
    },
    "printed_copy": {
      "score": 91.2,
      "front": 91.2,
      "back": 93.7,
      "decline_threshold": 35,
      "review_threshold": 77,
      "bucket": "approve"
    },
    "screen_replay": {
      "score": 99.9,
      "front": 99.9,
      "back": 99.5,
      "decline_threshold": 30,
      "review_threshold": 70,
      "bucket": "approve"
    }
  },
  "warnings": []
}

同一对象适用于非证件方式。只有特定于方式的键会发生变化：原本由证件读取填充的内容，改由登记记录或钱包属性填充，不适用的键为 null。

{
  "status": "Approved",
  "issuing_state": "ZAF",
  "first_name": "Thabo",
  "last_name": "Mokoena",
  "full_name": "Thabo Mokoena",
  "date_of_birth": "1991-06-15",
  "personal_number": "9106155043088",
  "node_id": "first_id_verification",
  "verification_method": "id_lookup",
  "assurance": "data_match",
  "wallet_provider": null,
  "fallback_from": null,
  "id_lookup": {
    "source": "Department of Home Affairs",
    "checked_at": "2026-09-04T09:12:44Z",
    "attempts": 1,
    "max_attempts": 2,
    "outcome": "match",
    "comparison": [
      { "field": "identification_number", "label": "ID number", "provided": "9106155043088", "record": "9106155043088", "result": "match" },
      { "field": "full_name", "label": "Full name", "provided": "Thabo Mokoena", "record": "Thabo Mokoena", "result": "match" },
      { "field": "date_of_birth", "label": "Date of birth", "provided": "1991-06-15", "record": "1991-06-15", "result": "match" }
    ],
    "registry_portrait": "https://<media-host>/.../registry_portrait.jpg?signature=...",
    "face_match_score": 96.4
  },
  "wallet_verification": null,
  "warnings": []
}

{
  "status": "Approved",
  "issuing_state": "DNK",
  "first_name": "Freja",
  "last_name": "Nielsen",
  "full_name": "Freja Nielsen",
  "date_of_birth": "1988-03-02",
  "node_id": "first_id_verification",
  "verification_method": "wallet",
  "assurance": "cryptographic",
  "wallet_provider": "mitid",
  "fallback_from": null,
  "id_lookup": null,
  "wallet_verification": {
    "provider": "mitid",
    "provider_name": "MitID",
    "issuing_authority": "Danish Agency for Digital Government",
    "issuing_country": "DNK",
    "credential_type": "person_identification",
    "level_of_assurance": "substantial",
    "verified_at": "2026-09-04T09:12:44Z",
    "signature_valid": true,
    "attributes": {
      "full_name": "Freja Nielsen",
      "date_of_birth": "1988-03-02",
      "cpr_alias": "b0f1c2d3-e4f5-4678-9abc-def012345678"
    },
    "portrait": null,
    "face_match_score": null
  },
  "warnings": []
}

NFC 验证

每次对证件进行芯片读取时都会返回：ICAO 9303 电子护照或电子身份证芯片，或通过 JPKI 读取的日本 My Number 卡（chip_protocol: "jpki"）。在 GET /v3/session/{sessionId}/decision/ 中以 nfc_verifications[] 形式返回（每条父级 KYC 记录对应一条）。来源：kyc/serializers/epassport.py:121-139（NFCV3Serializer，继承自 kyc/serializers/epassport.py:83-118 中的 NFCV2Serializer）。

字段	类型	可为空	说明	示例
`status`	string	否	参见状态枚举。	`"Approved"`
`portrait_image`	string (URL)	是	指向芯片提取人脸图像的预签名 URL。	`"https://<media-host>/.../nfc_portrait.jpg?..."`
`signature_image`	string (URL)	是	指向芯片提取签名图像的预签名 URL（如果签名存储在芯片中）。	`null`
`chip_data`	object	是	从芯片数据组解析出的个人数据，已展平（`kyc/utils/epassport.py:165-212`）：`dgs`（已读取的数据组）、`surname`、`name`、`country`、`nationality`、`birth_date`（`YYYY-MM-DD`）、`expiry_date`（`YYYY-MM-DD`）、`sex`（`M`/`F`）、`document_type`（MRZ 证件代码）、`document_number`、`optional_data`、MRZ 校验位（`birth_date_hash`、`expiry_date_hash`、`document_number_hash`、`optional_data_hash`、`final_hash`）、`mrz_string`、`mrz_type`（`TD1`/`TD2`/`TD3`）；当芯片包含 DG11 时，另有 `place_of_birth` 和 `address`（非拉丁文姓名时还有 `full_name` / `full_name_non_latin`），否则这些键不存在。跳过 NFC 步骤时为 `null`。	`{ "document_number": "AB1234567", "name": "MARIA" }`
`authenticity`	object	是	`{ sod_integrity, dg_integrity }`；JPKI 读取时为 `null`。`sod_integrity` 验证文档安全对象（SOD）的签名能否链接到有效的签发国 CSCA，且 DSC 既未被吊销也未过期；`dg_integrity` 验证每个数据组的哈希值与 SOD 相符。两者均为 `true` 表示芯片为真品且未被篡改。	`{ "sod_integrity": true, "dg_integrity": true }`
`certificate_summary`	对象	是	证件签名者证书的摘要（`kyc/utils/epassport.py:338-348`）：`issuer`、`subject`、`serial_number`（整数）、`not_valid_before`、`not_valid_after`（`YYYY-MM-DD HH:MM:SS`），另有一个 `validation` 对象 `{ csca_verified, dsc_revoked, dsc_expired, csca_expired }`（`kyc/views/epassport.py:86`）。	`{ "issuer": "Common Name: CSCA SPAIN, Country: ES", "not_valid_after": "2031-02-18 10:21:11" }`
`node_id`	字符串 \| null	是	工作流节点标识符（V3）。	`"first_nfc"`
`is_nfc_skipped`	布尔值	否	当此 NFC 步骤被明确跳过而非读取时为 `true`；`skip_reason` 说明原因。	`false`
`skip_reason`	字符串	是	跳过该步骤的原因，仅在 `is_nfc_skipped` 为 `true` 时设置。取值为以下之一：`USER_SKIPPED`、`DOCUMENT_WITHOUT_CHIP`、`CHIP_CERTIFICATE_UNAVAILABLE`、`DEVICE_WITHOUT_NFC`、`INTEGRATION_WITHOUT_NFC_ACCESS`、`MRZ_KEY_UNAVAILABLE`、`JPKI_UNAVAILABLE`；参见跳过原因。决策 payload 还包含会话级别的 `nfc_skip_reason`，其分类与之相同，涵盖在创建任何报告之前已被绕过的 NFC 步骤。	`null`
`chip_protocol`	字符串	否	芯片的读取方式：`icao`（ICAO 9303 电子护照或电子身份证芯片）或 `jpki`（日本 My Number 卡）。对于 `jpki`，`portrait_image`、`signature_image`、`chip_data`、`authenticity` 和 `certificate_summary` 均为 `null`。跳过的步骤同样会设置此字段。	`"icao"`
`jpki`	对象	是	一次 My Number 卡读取所证明的内容：`certificate_types`、`chain_valid`、`signature_valid`、`revocation_status`（`good`、`revoked` 或 `unchecked`）、`ca_generation`、`certificate_expires_at`、`certificates[]`、`attributes`（签名证书中的姓名、出生日期、性别和地址）、`attributes_match_ocr` 和 `mismatched_attributes`。绝不包含证书、其序列号或签名。对于 ICAO 芯片、跳过的步骤，以及在未读取任何卡片的情况下结束的步骤，该字段为 `null`。参见 JPKI 字段。	`null`
`warnings`	数组	否	参见警告对象。	`[]`

{
  "status": "Approved",
  "portrait_image": "https://<media-host>/.../nfc_portrait.jpg?signature=...",
  "signature_image": null,
  "chip_data": {
    "dgs": ["DG1", "DG2", "DG11"],
    "surname": "GARCIA LOPEZ",
    "name": "MARIA",
    "country": "ESP",
    "nationality": "ESP",
    "birth_date": "1990-05-12",
    "expiry_date": "2032-05-11",
    "sex": "F",
    "document_type": "P",
    "document_number": "AB1234567",
    "optional_data": "",
    "birth_date_hash": "4",
    "expiry_date_hash": "7",
    "document_number_hash": "3",
    "optional_data_hash": "",
    "final_hash": "8",
    "mrz_string": "P<ESPGARCIA<LOPEZ<<MARIA<<<<<<<<<<<<<<<<<<<<AB1234567ESP9005124F3205117<<<<<<<<<<<<<<08",
    "mrz_type": "TD3",
    "place_of_birth": "MADRID",
    "address": "CALLE MAYOR 1, MADRID"
  },
  "authenticity": { "sod_integrity": true, "dg_integrity": true },
  "certificate_summary": {
    "issuer": "Common Name: CSCA SPAIN, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
    "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
    "serial_number": 118120836164494130086420187336801405660,
    "not_valid_before": "2020-11-18 10:21:11",
    "not_valid_after": "2031-02-18 10:21:11",
    "validation": {
      "csca_verified": true,
      "dsc_revoked": false,
      "dsc_expired": false,
      "csca_expired": false
    }
  },
  "node_id": "first_nfc",
  "is_nfc_skipped": false,
  "skip_reason": null,
  "chip_protocol": "icao",
  "jpki": null,
  "warnings": []
}

活体检测

按活体会话返回。以 liveness_checks[] 的形式出现在 GET /v3/session/{sessionId}/decision/ 中。来源：face/serializers/face.py:301-320（LivenessV3Serializer，继承自 face/serializers/face.py:216-298 中的 LivenessV2Serializer）。

字段	类型	可为空	说明	示例
`status`	字符串	否	参见状态枚举。	`"Approved"`
`method`	字符串（枚举）	是	`ACTIVE_3D`、`FLASHING` 或 `PASSIVE`（`LivenessMethodChoices`，`common/config/choices.py:514-517`）。当允许桌面会话且用户使用桌面设备时，运行被动活体检测。	`"PASSIVE"`
`score`	浮点数（0-100）	是	活体置信度，保留两位小数。	`92.41`
`reference_image`	字符串（URL）	是	指向用户参考人脸裁剪图的预签名 URL。	`"https://<media-host>/.../reference.jpg?..."`
`video_url`	字符串（URL）	是	当采集过程保存了录像时，指向活体录像的预签名 URL，主动和被动活体均适用。若会话未保留录像，则为 `null`。	`"https://<media-host>/.../liveness.webm?..."`
`age_estimation`	浮点数	是	参考图像中最大人脸的估算年龄（单位：岁）。	`34.2`
`matches`	对象数组	否	跨会话人脸匹配结果。每一项：`{ session_id, session_number, similarity_percentage, vendor_data, vendor_user_id, biometric_template_id, verification_date, user_details: { full_name, document_type, document_number }, match_image_url, status, is_blocklisted, is_allowlisted, api_service, source }`。`source` 取值为 `session`、`imported`、`list_entry` 或 `retained_template`。保留模板匹配项具有 `vendor_user_id`、`vendor_data` 和 `biometric_template_id`；其会话、图像、身份详情、状态和 API 服务字段均为 `null`。	`[]`
`face_quality`	浮点数（0-100）	是	被动活体的人脸质量分数（已归一化为百分比）。	`87.50`
`face_luminance`	浮点数（0-100）	是	被动活体的人脸亮度分数（由 0-255 归一化为百分比）。	`54.12`
`node_id`	字符串 \| null	是	工作流节点标识符（V3）。	`"first_liveness"`
`warnings`	数组	否	参见警告对象。	`[]`

{
  "status": "Approved",
  "method": "PASSIVE",
  "score": 92.41,
  "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
  "video_url": null,
  "age_estimation": 34.2,
  "matches": [],
  "face_quality": 87.50,
  "face_luminance": 54.12,
  "node_id": "first_liveness",
  "warnings": []
}

当 PASSIVE 会话的采集保存了录像时，会返回此字段；若会话未保留录像，则返回 null。上面的示例是一个未保留录像的会话。

人脸比对

每次人脸比对（通常是用户的活体人脸与证件照片的比对）返回一次。以 face_matches[] 的形式出现在 GET /v3/session/{sessionId}/decision/ 中。来源：face/serializers/face.py:367-389（FaceMatchV3Serializer，继承自 face/serializers/face.py:323-364 中的 FaceMatchV2Serializer）。

字段	类型	可为空	说明	示例
`status`	字符串	否	参见状态枚举。	`"Approved"`
`score`	浮点数（0-100）	是	相似度，保留两位小数。当供应商仅返回 `unmatched_faces[].Confidence` 时，将其转换为 `100 - confidence`。	`97.83`
`source_image_session_id`	字符串（UUID）	是	提供源（参考）图像的已存储照片所属的会话，适用于基于照片的流程（生物识别认证，或在创建会话时提供的照片）。当参考图像是同一会话中的证件照片时为 `null`。	`null`
`source_image`	字符串（URL）	是	指向源（参考）图像的预签名 URL，通常是证件照片；在生物识别认证流程中则为已存储的照片。	`"https://<media-host>/.../source.jpg?..."`
`target_image`	字符串（URL）	是	指向活体检测期间采集的目标（活体人脸）图像的预签名 URL。	`"https://<media-host>/.../target.jpg?..."`
`node_id`	字符串 \| null	是	工作流节点标识符（V3）。	`"first_face_match"`
`warnings`	数组	否	参见警告对象。	`[]`
`face_coverage`	对象	是	采集图像中 `eyes`、`mouth` 和 `face` 是否被遮挡。每个区域包含 `covered`、`calibrated` 和 `visibility_score`；`calibrated: false` 表示仅为阴影证据，不会触发任何警告。仅由 `GET /v3/session/{sessionId}/decision/` 返回，从不出现在 Webhook payload 中。	`{ "eyes": { "covered": false, "calibrated": true, "visibility_score": 0.98 } }`

{
  "status": "Approved",
  "score": 97.83,
  "source_image_session_id": null,
  "source_image": "https://<media-host>/.../source.jpg?signature=...",
  "target_image": "https://<media-host>/.../target.jpg?signature=...",
  "node_id": "first_face_match",
  "warnings": []
}

人脸搜索

由独立的人脸搜索 API（POST /v3/face-search/）返回。人脸搜索不会以数组形式出现在 /v3/session/{sessionId}/decision/ 中。当 save_api_request=true 时保存的会话，会在 features[] 中以 FACE_SEARCH 条目出现，并在 liveness_checks[] 中包含一个保存了 matches 的条目。来源：apis/serializers/face_search.py:8-79（FaceSearchResponseSerializer 包装 FaceSearchDetailsSerializer）；匹配字典构建于 face/utils/utils.py:869-884。顶层响应：

字段	类型	可为空	说明	示例
`request_id`	字符串（UUID）	否	当 `save_api_request=true` 时为已保存的会话 ID（可用于 `GET /v3/session/{sessionId}/decision/`）；否则为临时关联 UUID。	`"4a1c2c4e-8b1b-4d6a-91b5-ee9a1f3a2c7f"`
`face_search`	对象	否	搜索详情 payload，见下方字段。	无
`vendor_data`	字符串	是	请求中回显的 `vendor_data`。	`null`
`metadata`	对象	是	请求中回显的 `metadata`。	`null`
`created_at`	字符串（ISO 8601）	否	服务端请求时间戳。	`"2026-06-12T01:04:42.763237+00:00"`

face_search 对象：

字段	类型	可为空	说明	示例
`status`	字符串	否	仅当触发 `FACE_IN_BLOCKLIST` 或 `POSSIBLE_FACE_IN_BLOCKLIST` 警告时为 `Declined`；否则为 `Approved`。重复匹配本身永远不会导致拒绝（`apis/views/face_search.py:242-248`）。	`"Approved"`
`total_matches`	整数	否	`matches[]` 中返回的匹配数（0–5）。	`1`
`matches`	人脸搜索匹配对象数组	否	最多返回 5 条高于相似度下限的匹配，按相似度降序排列（黑名单条目优先，且 `search_type=blocklisted_or_approved`）。	`[…]`
`user_image`	对象	否	提交图像的检测结果：`{ entities: [{ bbox, confidence }], best_angle }`，每检测到一张人脸对应一个实体。	`{ "entities": [{ "bbox": [40, 40, 120, 120], "confidence": 0.73 }], "best_angle": 0 }`
`warnings`	对象数组	否	此独立 API 返回精简的警告结构，不包含 `node_id`。序列化器契约声明的结构为 `{ risk, additional_data, log_type, short_description, long_description }`（`apis/serializers/face_search.py:49-54`）；运行时 payload 还包含 `feature`，其值始终为 `"LIVENESS"`（`apis/views/face_search.py:332-341`）。	`[]`

人脸搜索匹配对象

字段	类型	可为空	说明	示例
`session_id`	字符串（UUID）	是	匹配的验证会话。当 `source` 为 `imported`、`list_entry` 或 `retained_template` 时为 `null`。	`"a3f2a6f1-…"`
`session_number`	整数	是	便于控制台查看的匹配会话编号；非会话匹配为 `null`。	`1024`
`similarity_percentage`	浮点数（0–100）	否	提交人脸与匹配人脸之间的相似度。	`96.42`
`source`	字符串（枚举）	否	匹配人脸的录入来源：`session`（验证会话或已保存的独立调用）、`imported`（直接上传到用户资料的人脸）、`list_entry`（添加到列表中的人脸）、`retained_template`（来源会话被删除后保留的、不含图像的生物特征模板）。	`"session"`
`vendor_data`	字符串	是	匹配会话的 `vendor_data`；对于 `imported` 和 `retained_template` 匹配，则为关联用户的 vendor_data。	`"user-12345"`
`vendor_user_id`	字符串（UUID）	是	关联的用户。对于 `list_entry` 匹配以及没有用户的会话，为 `null`。	`"2f7c1a9e-…"`
`biometric_template_id`	字符串（UUID）	是	匹配到的已保留模板。仅对 `retained_template` 匹配设置；可与 `GET`/`DELETE /v3/biometric-templates/{id}/` 配合使用。	`null`
`verification_date`	字符串（ISO 8601）	是	匹配人脸的采集时间，或 `retained_template` 的保留时间；对于 `list_entry` 匹配为 `null`。	`"2024-11-04T09:14:02Z"`
`user_details`	对象	是	`{ full_name, document_type, document_number }`，取自匹配会话的证件验证；对于 `imported` 匹配仅设置 `full_name`；若不存在任何身份数据则为 `null`；对于 `retained_template` 匹配始终为 `null`。	`{ "full_name": "María García López", "document_type": "Passport", "document_number": "AB1234567" }`
`match_image_url`	字符串（URL）	是	匹配用户的参考人脸。当 `save_api_request=true` 时为预签名 URL，否则为原始存储路径。对于 `retained_template` 匹配始终为 `null`，因为其不保存图像。	`"https://<media-host>/.../matched.jpg?..."`
`status`	字符串	是	匹配会话的验证状态（见状态枚举）；非会话匹配为 `null`。	`"Approved"`
`is_blocklisted`	布尔值	否	匹配人脸是否在你的人脸黑名单中。对于 `retained_template` 匹配始终为 `false`；被列入黑名单的人脸会单独报告为 `list_entry` 匹配。	`false`
`is_allowlisted`	布尔值	否	匹配人脸是否在你的任一白名单中。	`false`
`api_service`	字符串（枚举）	是	匹配会话的独立 API 类型（大写形式，例如 `PASSIVE_LIVENESS`、`FACE_MATCH`）；工作流会话和非会话匹配为 `null`。	`null`

{
  "request_id": "4a1c2c4e-8b1b-4d6a-91b5-ee9a1f3a2c7f",
  "face_search": {
    "status": "Approved",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "a3f2a6f1-1c1c-4eec-8b69-1c1c2f3a2c7f",
        "session_number": 1024,
        "similarity_percentage": 96.42,
        "source": "session",
        "vendor_data": "user-12345",
        "verification_date": "2024-11-04T09:14:02Z",
        "user_details": {
          "full_name": "María García López",
          "document_type": "Passport",
          "document_number": "AB1234567"
        },
        "match_image_url": "https://<media-host>/.../matched.jpg?signature=...",
        "status": "Approved",
        "is_blocklisted": false,
        "is_allowlisted": false,
        "api_service": null
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [40, 40, 120, 120],
          "confidence": 0.732973
        }
      ],
      "best_angle": 0
    },
    "warnings": []
  },
  "vendor_data": null,
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}

AML 筛查

按每个被筛查的实体返回。对于 KYC 和 KYB 会话，均会以 aml_screenings[] 的形式出现在 GET /v3/session/{sessionId}/decision/ 中。来源：aml/serializers/aml.py:63-85（AMLV3Serializer，继承自 aml/serializers/aml.py:28-60 中的 AMLV2Serializer）。

字段	类型	可为空	说明	示例
`status`	字符串	否	参见状态枚举。	`"Approved"`
`total_hits`	整数	否	筛查命中次数（始终存在，默认为 `0`）。	`2`
`entity_type`	字符串（枚举）	是	`person` 或 `company`（`EntityTypeChoices`，`common/config/choices.py:675-677`）。	`"person"`
`hits`	对象数组	否	每次命中对应一个条目。主要字段：`id`、`caption`、`match`（布尔值）、`target`（布尔值 \| null，表示该实体是否为名单的直接目标）、`match_score`（0–100 的浮点数，身份置信度）、`risk_score`（0–100 的浮点数，实体风险）、`score`（已弃用，0–1 的浮点数）、`datasets[]`（例如 `PEP`、`PEP Level 1`-`4`、`Sanctions`、`Adverse Media`、`Warnings and Regulatory Enforcement`、`Fitness and Probity`）、`properties`（姓名、别名、出生日期等）、`features`、`url`、`first_seen`、`last_seen`、`rca_name`、`risk_view`、`score_breakdown`、`pep_matches`、`sanction_matches`、`warning_matches`、`adverse_media_matches`、`adverse_media_details`、`linked_entities`、`additional_information`，以及 `review_status`（`Unreviewed`、`Confirmed Match`、`False Positive`、`Inconclusive`，可通过更新 AML 命中状态的 endpoint 进行编辑，`AMLHitStatusChoices`）。	`[…]`
`score`	float (0-100)	是	整体筛查分数：未标记为 `False Positive` 的命中项中最高的 `risk_score`（`aml/services/aml.py:832-842`）；当所有命中项都是误报时为 `0`。计算前为 `null`。	`42.7`
`screened_data`	object	是	发送给筛查的数据快照，包括 `full_name`、`nationality`、`date_of_birth`、`document_number`。	`{ "full_name": "María García López", "date_of_birth": "1990-05-12" }`
`is_ongoing_monitoring_enabled`	boolean	否	实体是否订阅了持续监控的重新筛查。	`false`
`next_ongoing_monitoring_bill_date`	string (YYYY-MM-DD)	是	启用持续监控时，按 `last_aml_bill_date + 365 days` 计算。这是计费日期，而不是筛查日期。	`null`
`last_ongoing_screening_at`	string (ISO 8601)	是	持续监控最近一次完成该记录重新筛查的时间，无论结果是否变化。从未重新筛查时为 `null`；绝不回填。	`"2026-09-12T04:03:11Z"`
`last_ongoing_screening_datasets_updated_at`	string (ISO 8601)	是	服务商为该次筛查报告的最新 AML 数据集更新时间。服务商未报告数据集日期时为 `null`；绝不估算。	`null`
`node_id`	string \| null	是	工作流节点标识符（V3）。	`"first_aml"`
`warnings`	array	否	参见警告对象。	`[]`

{
  "status": "In Review",
  "total_hits": 1,
  "entity_type": "person",
  "hits": [
    {
      "id": "Q7XW3-aml-hit-1",
      "caption": "Maria Garcia Lopez",
      "match": true,
      "target": true,
      "match_score": 86.4,
      "risk_score": 42.7,
      "datasets": ["PEP Level 2"],
      "properties": {
        "name": ["María García López", "M. García"],
        "alias": ["Maria Garcia"],
        "birthDate": ["1990-05-12"]
      },
      "url": "https://example.org/registry/entities/Q7XW3",
      "first_seen": "2023-11-02T00:00:00Z",
      "last_seen": "2026-05-01T00:00:00Z",
      "review_status": "Unreviewed"
    }
  ],
  "score": 42.7,
  "screened_data": {
    "full_name": "María García López",
    "date_of_birth": "1990-05-12",
    "nationality": "ES",
    "document_number": "AB1234567"
  },
  "is_ongoing_monitoring_enabled": false,
  "next_ongoing_monitoring_bill_date": null,
  "last_ongoing_screening_at": null,
  "last_ongoing_screening_datasets_updated_at": null,
  "node_id": "first_aml",
  "warnings": []
}

IP 分析

按每个采集的网络位置返回。在 KYC 和 KYB 会话的 GET /v3/session/{sessionId}/decision/ 中，以 ip_analyses[] 形式出现。来源：kyc/serializers/location.py:196-243（IPAnalysisSerializerV3）。

字段	类型	可为空	描述	示例
`status`	string	否	参见状态枚举。	`"Approved"`
`node_id`	string \| null	是	工作流节点标识符（V3）。	`"first_ip_analysis"`
`device_brand`	string	是	根据 User-Agent 推断的设备品牌。	`"Apple"`
`device_model`	string	是	设备型号。	`"iPhone"`
`browser_family`	string	是	浏览器系列。	`"Mobile Safari"`
`os_family`	string	是	操作系统系列。	`"iOS"`
`platform`	string	是	高层平台（`mobile`、`desktop`、`tablet`）。	`"mobile"`
`device_fingerprint`	string	是	稳定的单设备指纹哈希。	`"f2a3…"`
`ip_country`	string	是	根据 IP 地址解析出的国家名称。	`"Spain"`
`ip_country_code`	string (ISO 3166-1 alpha-2)	是	根据 IP 地址解析出的国家代码。	`"ES"`
`ip_state`	string	是	根据 IP 地址解析出的地区或省州。	`"Comunidad de Madrid"`
`ip_city`	string	是	根据 IP 地址解析出的城市。	`"Madrid"`
`latitude`	float	是	基于 IP 地址推导的纬度。	`40.4168`
`longitude`	float	是	基于 IP 地址推导的经度。	`-3.7038`
`ip_address`	string	是	采集到的 IP 地址。	`"203.0.113.42"`
`isp`	string	是	ISP 名称。	`"Telefonica de Espana"`
`organization`	string	是	组织名称（通常与 ISP 相同）。	`"Telefonica de Espana"`
`is_vpn_or_tor`	boolean	是	当 IP 地址属于 VPN、代理或 Tor 出口节点时为 `true`。	`false`
`is_data_center`	boolean	是	当 IP 地址属于已知的托管或数据中心 ASN 时为 `true`。	`false`
`time_zone`	string	是	IANA 时区名称。	`"Europe/Madrid"`
`time_zone_offset`	string	是	UTC 偏移量。	`"+02:00"`
`ip`	object	否	`{ location, distance_from_id_document, distance_from_poa_document }`。`location = { latitude, longitude }`。距离单位为千米，任一侧缺失时为 `null`。	`{ "location": { "latitude": 40.4168, "longitude": -3.7038 }, "distance_from_id_document": 3.4, "distance_from_poa_document": 1.1 }`
`id_document`	object	否	`{ location, distance_from_ip, distance_from_poa_document }`。证件位置根据 `issuing_state` 和解析后的地址得出。	`{ "location": { "latitude": 40.4165, "longitude": -3.7026 }, "distance_from_ip": 3.4, "distance_from_poa_document": 4.0 }`
`poa_document`	object	否	`{ location, distance_from_ip, distance_from_id_document }`。地址证明中的地址已完成地理编码。	`{ "location": { "latitude": 40.4170, "longitude": -3.7040 }, "distance_from_ip": 1.1, "distance_from_id_document": 4.0 }`
`matches`	对象数组	否	跨会话的 IP 和设备匹配项。每项包含：`{ session_id, session_number, vendor_data, verification_date, match_type, match_source, matched_value, status, is_blocklisted, api_service, source, device_info, location_info, confidence, match_mode }`。`match_type` 为 `ip_address` 或 `device_fingerprint`；`match_source` 为 `ip_address`、`persistent_id`、`legacy_fp` 或 `recovered_high`（恢复的匹配项还包含 `recovery_similarity`、`tls_ja4_corroborated`、`recovery_gate_reason`）。IP 和设备匹配各最多 5 条。	`[]`
`warnings`	array	否	参见警告对象。	`[]`
`browser_version`, `os_version`	string	是	根据 User-Agent 获取的浏览器和操作系统版本。	`"17.4"`
`user_agent`, `accept_language`	string	是	浏览器发送的 User-Agent 字符串和 `Accept-Language` 请求头。	`"en-US,en;q=0.9"`
`session_identifier`, `session_age_ms`	string, integer	是	该步骤所在的浏览会话及其存续时长（毫秒）。	`48210`
`coords_accuracy`	float	是	设备上报坐标的精度半径（米）。	`35.0`
`raw_device_data`	object	是	为该步骤采集的原始设备信号。	`{}`

{
  "status": "Approved",
  "node_id": "first_ip_analysis",
  "device_brand": "Apple",
  "device_model": "iPhone",
  "browser_family": "Mobile Safari",
  "os_family": "iOS",
  "platform": "mobile",
  "device_fingerprint": "f2a3c1de8b994a3f9e4cdf3a02b1a7c9",
  "ip_country": "Spain",
  "ip_country_code": "ES",
  "ip_state": "Comunidad de Madrid",
  "ip_city": "Madrid",
  "latitude": 40.4168,
  "longitude": -3.7038,
  "ip_address": "203.0.113.42",
  "isp": "Telefonica de Espana",
  "organization": "Telefonica de Espana",
  "is_vpn_or_tor": false,
  "is_data_center": false,
  "time_zone": "Europe/Madrid",
  "time_zone_offset": "+02:00",
  "ip": {
    "location": { "latitude": 40.4168, "longitude": -3.7038 },
    "distance_from_id_document": 3.4,
    "distance_from_poa_document": 1.1
  },
  "id_document": {
    "location": { "latitude": 40.4165, "longitude": -3.7026 },
    "distance_from_ip": 3.4,
    "distance_from_poa_document": 4.0
  },
  "poa_document": {
    "location": { "latitude": 40.4170, "longitude": -3.7040 },
    "distance_from_ip": 1.1,
    "distance_from_id_document": 4.0
  },
  "matches": [],
  "warnings": []
}

位置验证

按每个位置验证步骤返回。在 GET /v3/session/{sessionId}/decision/ 中，以 geolocation_checks[] 形式出现：每个步骤一项，即其被接受的那次尝试。geolocation_attempts[] 列出每个步骤的每次尝试，最早的在前。对于不包含该步骤的工作流，两者均为 null。来源：GeolocationDecisionSerializer。

字段	类型	可为空	描述	示例
`node_id`	string	是	产生该结果的工作流节点。	`"geolocation_1"`
`status`	字符串	否	参见状态枚举。	`"Declined"`
`outcome`	字符串	是	本次尝试的结果：`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`。	`"outside_geofence"`
`permission`	字符串	是	系统授予的权限：`granted_precise`、`granted_approximate`、`denied`、`restricted`、`unavailable`、`timeout`、`dismissed` 或 `not_requested`。	`"granted_precise"`
`latitude`, `longitude`	浮点数	是	WGS84 位置。无位置时为 `null`。	`48.8566`
`accuracy_m`	浮点数	是	不确定性半径（米）。	`35.0`
`accuracy_confidence`	字符串	是	`p95`、`p68` 或 `unspecified`。	`"p95"`
`measured_at`, `age_seconds`	日期时间、整数	是	设备获取定位的时间，以及 Didit 收到该定位所经过的秒数。	`2`
`source`, `platform`, `sdk_version`	字符串	是	定位的来源、生成该定位的客户端及其 SDK 版本。	`"browser"`
`is_mock`, `produced_by_accessory`	布尔值	是	平台报告的欺骗攻击证据。`null` 表示平台未报告该项。	`null`
`integrity`	字符串	否	`attested`、`not_attested`、`failed`、`unsupported`（网页端）或 `not_determined`。	`"unsupported"`
`country_code`, `region_code`, `city`	字符串	是	该定位解析到的地点。	`"FR"`
`geofence`, `inside_geofence`, `geofence_basis`, `inside_areas`, `blocked_areas`	对象、布尔值、字符串、数组	是	国家和区域的判定结果。	`{ "enabled": true, "result": "outside" }`
`position_source`, `anonymizers`	字符串、对象	是	该步骤获取位置的来源，以及 VPN、代理、Tor、欺骗攻击和模拟器信号。	`"device_and_ip"`
`ip_distance_km`, `ip_distance_uncertainty_km`, `ip_consistent`, `document_distance_km`, `travel_excused`, `consecutive_mismatches`	数字、布尔值、整数	是	与 IP 位置及档案中存储地址的比较结果。	`12.4`
`attempts`	整数	否	本步骤内的尝试序号。	`3`
`consent`	对象	是	用户所接受告知声明的 `accepted_at`、`version` 和 `locale`。
`warnings`	警告对象的数组	否	本步骤的 `LOCATION_*` 警告。`geolocation_attempts[]` 中不包含此字段，该数组额外包含 `received_at` 和 `created_at`。	`[]`

所有字段和示例均见位置验证报告。

地址证明

每份提交的地址证明文件返回一条记录。以 poa_verifications[] 的形式出现在 GET /v3/session/{sessionId}/decision/ 中。来源：poa/serializers/poa.py:212-227（POAV3Serializer，扩展自 poa/serializers/poa.py:173-209 中的 POAV2Serializer）。

字段	类型	可为空	描述	示例
`status`	字符串	否	参见状态枚举。	`"Approved"`
`issuing_state`	字符串（ISO 3166-1 alpha-3）	是	证件签发方的国家代码。	`"ESP"`
`document_type`	字符串	否	来自 `PoaDocumentTypeChoices`（`common/config/choices.py:868-873`）的高级别类型：`UTILITY_BILL`、`BANK_STATEMENT`、`GOVERNMENT_ISSUED_DOCUMENT`、`OTHER_POA_DOCUMENT`。无法识别时回退为 `UNKNOWN`，绝不为 `null`。	`"UTILITY_BILL"`
`document_subtype`	字符串	否	来自 `PoaDocumentSubtypeChoices` 的子类型代码（例如 `ELECTRICITY_BILL`、`WATER_BILL`、`ACCOUNT_STATEMENT`）。无法识别时回退为 `UNKNOWN`，绝不为 `null`。	`"ELECTRICITY_BILL"`
`issuer`	字符串	是	签发机构的名称。	`"Iberdrola"`
`issue_date`	字符串（YYYY-MM-DD）	是	证件签发日期。	`"2026-04-15"`
`expiration_date`	字符串（YYYY-MM-DD）	是	证件上印刷的到期日期（如有）。	`null`
`poa_address`	字符串	是	OCR 提取的原始地址。	`"Calle Mayor 1, 28001 Madrid"`
`poa_formatted_address`	字符串	是	地理编码后的格式化地址。	`"Calle Mayor 1, 28001 Madrid, Spain"`
`poa_parsed_address`	对象	是	结构化地址（`street_1`、`street_2`、`city`、`region`、`postal_code`、`country`（alpha-2）、`address_type`、`document_location`、…）。	`{ "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001" }`
`document_file`	字符串（URL）	是	已上传证件的预签名 URL。	`"https://<media-host>/.../poa.pdf?..."`
`document_language`	字符串	是	检测到的证件语言（ISO 639-1）。	`"es"`
`document_metadata`	对象	是	过滤后的元数据：`file_size`、`content_type`、`creation_date`、`modified_date`、`creator`、`producer`、`software`、`encryption`、`is_signed`、`is_tampered`、`signature_info`、`exif_original_date`、`exif_digitized_date`、`processed_by_known_editor`、`has_different_creation_mod_date`、`overlay_manipulation`。	`{ "file_size": 184221, "content_type": "application/pdf", "is_tampered": false }`
`extra_fields`	对象	否	银行账户字段（`bank_account_number`、`bank_iban`、`bank_sort_code`、`bank_routing_number`、`bank_swift_bic`、`bank_branch_name`、`bank_branch_address`）、`document_phone_number`、`additional_names`，以及记录中保存的任何自定义键。	`{ "bank_iban": null, "additional_names": [] }`
`name_on_document`	字符串	是	证件上显示的姓名。	`"María García López"`
`expected_details_address`	字符串	是	客户注册时输入的地址（原文照录）。	`"Calle Mayor 1, Madrid"`
`expected_details_formatted_address`	字符串	是	地理编码后的预期地址。	`"Calle Mayor 1, 28001 Madrid, Spain"`
`expected_details_parsed_address`	对象	是	结构化的预期地址。	`{ "city": "Madrid", "postal_code": "28001" }`
`name_match_score_expected_details`	浮点数（0-100）	是	`name_on_document` 与创建会话时提供的姓名之间的模糊匹配分数。	`94.0`
`name_match_score_id_verification`	浮点数（0-100）	是	`name_on_document` 与已验证身份证件中 `full_name` 之间的模糊匹配分数。	`100.0`
`extra_files`	字符串数组（URL）	否	指向其他已上传文件的预签名 URL。	`[]`
`detected_codes`	对象数组	否	在文档所有已处理页面中检测到的 QR 码和条形码：`type`、`page_number`（从 1 开始计数）、`position`（多边形）、`x`/`y`/`width`/`height`（边界框）、`page_width`/`page_height`、`raw_payload`（base64）、`parsed_payload`（解码后的值，当代码已定位但无法解码时为 `null`）。未检测到任何代码时为空数组。	`[{ "type": "QR_CODE", "page_number": 1, "parsed_payload": "https://issuer.example/inv/9981" }]`
`node_id`	字符串 \| null	是	工作流节点标识符（V3）。	`"first_poa"`
`warnings`	数组	否	参见警告对象。	`[]`

{
  "status": "Approved",
  "issuing_state": "ESP",
  "document_type": "UTILITY_BILL",
  "document_subtype": "ELECTRICITY_BILL",
  "issuer": "Iberdrola",
  "issue_date": "2026-04-15",
  "expiration_date": null,
  "poa_address": "Calle Mayor 1, 28001 Madrid",
  "poa_formatted_address": "Calle Mayor 1, 28001 Madrid, Spain",
  "poa_parsed_address": { "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001", "country": "ES" },
  "document_file": "https://<media-host>/.../poa.pdf?signature=...",
  "document_language": "es",
  "document_metadata": {
    "file_size": 184221,
    "content_type": "application/pdf",
    "creation_date": "2026-04-15T08:11:32Z",
    "modified_date": "2026-04-15T08:11:32Z",
    "creator": "Iberdrola Billing",
    "producer": "Adobe PDF Library 15.0",
    "software": null,
    "encryption": null,
    "is_signed": true,
    "is_tampered": false,
    "signature_info": { "signer_name": "Iberdrola Clientes", "date": "2026-04-15T08:11:32Z" },
    "exif_original_date": null,
    "exif_digitized_date": null,
    "processed_by_known_editor": false,
    "has_different_creation_mod_date": false,
    "overlay_manipulation": null
  },
  "extra_fields": {
    "bank_account_number": null,
    "bank_iban": null,
    "bank_sort_code": null,
    "bank_routing_number": null,
    "bank_swift_bic": null,
    "bank_branch_name": null,
    "bank_branch_address": null,
    "document_phone_number": null,
    "additional_names": []
  },
  "name_on_document": "María García López",
  "expected_details_address": "Calle Mayor 1, Madrid",
  "expected_details_formatted_address": "Calle Mayor 1, 28001 Madrid, Spain",
  "expected_details_parsed_address": { "city": "Madrid", "postal_code": "28001", "country": "ES" },
  "name_match_score_expected_details": 94.0,
  "name_match_score_id_verification": 100.0,
  "extra_files": [],
  "detected_codes": [
    {
      "type": "QR_CODE",
      "page_number": 1,
      "position": [[820, 1120], [1002, 1120], [1002, 1302], [820, 1302]],
      "x": 820,
      "y": 1120,
      "width": 182,
      "height": 182,
      "page_width": 1190,
      "page_height": 1684,
      "raw_payload": "aHR0cHM6Ly9pYmVyZHJvbGEuZXMvZmFjdHVyYS85OTgx",
      "parsed_payload": "https://iberdrola.es/factura/9981"
    },
    {
      "type": "CODE_128",
      "page_number": 1,
      "position": [[112, 1480], [560, 1480], [560, 1540], [112, 1540]],
      "x": 112,
      "y": 1480,
      "width": 448,
      "height": 60,
      "page_width": 1190,
      "page_height": 1684,
      "raw_payload": "MDA5OTgxMDAwNDI=",
      "parsed_payload": "0099810042"
    }
  ],
  "node_id": "first_poa",
  "warnings": []
}

电话验证

每次电话验证尝试返回一条记录。在 KYC 和 KYB 会话的 GET /v3/session/{sessionId}/decision/ 中以 phone_verifications[] 形式出现。来源：phone/serializers/phone.py:251-266（PhoneV3Serializer，继承自位于 phone/serializers/phone.py:103-248 的 PhoneV2Serializer）。

字段	类型	可为空	描述	示例
`status`	字符串	否	参见状态枚举。	`"Approved"`
`phone_number_prefix`	字符串	否	E.164 国家区号（包含 `+`）。	`"+34"`
`phone_number`	字符串	否	不含区号的用户号码。	`"612345678"`
`full_number`	字符串	否	完整的 E.164 号码（`phone_number_prefix + phone_number`）。	`"+34612345678"`
`country_code`	字符串（ISO 3166-1 alpha-2）	是	号码所属国家/地区。	`"ES"`
`country_name`	字符串	是	本地化的国家/地区名称。	`"Spain"`
`carrier`	对象	否	`{ name, type }`，其中 `type` 为 `LineTypeChoices` 的值（`common/config/choices.py:648-667`）：`mobile`、`fixed_line`、`voip`、`isp`、`vpn`、`toll_free`、`premium_rate`、`satellite`、`pager`、`payphone`、`voice_mail`、`unknown`，以及其他线路类别。	`{ "name": "Movistar", "type": "mobile" }`
`is_disposable`	布尔值	否	运营商将该号码标记为临时或一次性号码时为 `true`。	`false`
`is_virtual`	布尔值	否	当 `carrier.type` 为 `voip`、`isp`、`vpn` 之一时为 `true`。	`false`
`verification_method`	字符串	否	用于投递一次性验证码的渠道（`whatsapp`、`sms`、…）。取自最后一次发送尝试的 `actual_channel`（若不存在则回退到请求的 `channel`，再回退到 `sms`）。	`"whatsapp"`
`verification_attempts`	整数	否	一次性验证码发送尝试的总次数（首次发送加上重新发送）。	`1`
`verified_at`	字符串（ISO 8601）	是	一次性验证码成功输入的时间戳。	`"2026-05-17T10:14:02Z"`
`lifecycle`	对象数组	否	按时间顺序排列的事件：发送尝试、投递回调、验证码检查，以及最终状态事件。每个事件为 `{ type, timestamp, details, fee }`。事件类型来自 `PhoneEventChoices`。	`[…]`
`matches`	对象数组	否	跨会话的电话号码匹配记录。每一项为：`{ session_id, session_number, vendor_data, verification_date, phone_number, status, is_blocklisted, api_service, source }`。`source` 为 `session` 或 `list_entry`。	`[]`
`node_id`	字符串 \| null	是	工作流节点标识符（V3）。	`"first_phone"`
`warnings`	数组	否	参见警告对象。	`[]`
`phone_intelligence`	对象	是	电话情报信号。仅当情报附加功能对该号码运行时才会出现。
`phone_social`	对象	是	该号码的社交足迹。仅当社交足迹附加功能运行时才会出现。

{
  "status": "Approved",
  "phone_number_prefix": "+34",
  "phone_number": "612345678",
  "full_number": "+34612345678",
  "country_code": "ES",
  "country_name": "Spain",
  "carrier": { "name": "Movistar", "type": "mobile" },
  "is_disposable": false,
  "is_virtual": false,
  "verification_method": "whatsapp",
  "verification_attempts": 1,
  "verified_at": "2026-05-17T10:14:02Z",
  "lifecycle": [
    {
      "type": "PHONE_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2026-05-17T10:13:51Z",
      "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" },
      "fee": 0.02
    },
    {
      "type": "PHONE_DELIVERY_DELIVERED",
      "timestamp": "2026-05-17T10:13:52Z",
      "details": { "channel": "whatsapp", "status": "delivered" },
      "fee": 0
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2026-05-17T10:14:02Z",
      "details": { "code_tried": "482917", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "PHONE_VERIFICATION_APPROVED",
      "timestamp": "2026-05-17T10:14:02Z",
      "details": null,
      "fee": 0
    }
  ],
  "matches": [],
  "node_id": "first_phone",
  "warnings": []
}

邮箱验证

每次邮箱验证尝试返回一条记录。在 KYC 和 KYB 会话的 GET /v3/session/{sessionId}/decision/ 中以 email_verifications[] 形式出现。来源：email_verification/serializers/email.py:149-164（EmailV3Serializer，继承自位于 email_verification/serializers/email.py:38-146 的 EmailV2Serializer）。

字段	类型	可为空	描述	示例
`status`	字符串	否	参见状态枚举。	`"Approved"`
`email`	字符串	否	用户提交的邮箱地址。	`"maria.garcia@example.com"`
`is_breached`	布尔值	否	当该邮箱出现在已知数据泄露事件中时为 `true`。	`false`
`breaches`	对象数组	否	当 `is_breached` 为 `true` 时，每次泄露的详细信息：`{ name, domain, logo_path, breach_date, description, is_verified, data_classes, breach_emails_count }`。	`[]`
`is_disposable`	布尔值	否	当该邮箱属于一次性邮箱服务商时为 `true`。	`false`
`is_undeliverable`	布尔值	否	当 SMTP 投递探测显示该收件箱不接收邮件时为 `true`。	`false`
`verification_attempts`	整数	否	一次性验证码检查尝试的总次数。	`1`
`verified_at`	字符串（ISO 8601）	是	一次性验证码成功输入的时间戳。	`"2026-05-17T10:15:22Z"`
`lifecycle`	对象数组	否	按时间顺序排列的事件：发送尝试、验证码检查，以及最终状态事件。每个事件为 `{ type, timestamp, details, fee }`。事件类型来自 `EmailEventChoices`。	`[…]`
`matches`	对象数组	否	跨会话的邮箱匹配记录。每一项为：`{ session_id, session_number, vendor_data, verification_date, email, status, is_blocklisted, api_service, source }`。`source` 为 `session` 或 `list_entry`。	`[]`
`node_id`	字符串 \| null	是	工作流节点标识符（V3）。	`"first_email"`
`warnings`	数组	否	参见警告对象。	`[]`
`email_intelligence`	对象	是	邮箱情报信号。仅当情报附加功能对该地址运行时才会出现。
`email_social`	对象	是	该地址的社交足迹。仅当社交足迹附加功能运行时才会出现。

{
  "status": "Approved",
  "email": "maria.garcia@example.com",
  "is_breached": false,
  "breaches": [],
  "is_disposable": false,
  "is_undeliverable": false,
  "verification_attempts": 1,
  "verified_at": "2026-05-17T10:15:22Z",
  "lifecycle": [
    {
      "type": "EMAIL_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2026-05-17T10:15:11Z",
      "details": { "status": "Success", "reason": null },
      "fee": 0.02
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2026-05-17T10:15:22Z",
      "details": { "code_tried": "739204", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "EMAIL_VERIFICATION_APPROVED",
      "timestamp": "2026-05-17T10:15:22Z",
      "details": null,
      "fee": 0
    }
  ],
  "matches": [],
  "node_id": "first_email",
  "warnings": []
}

数据库核验

每次针对用户提交数据运行的数据库查询都会返回一条记录。在 GET /v3/session/{sessionId}/decision/ 中以 database_validations[] 形式出现。来源：database_validation/serializers/database_validation.py:21-142（DatabaseValidationV3Serializer，继承自 DatabaseValidationV2Serializer）。

字段	类型	可为空	说明	示例
`issuing_state`	字符串（ISO 3166-1 alpha-3）	是	被查询注册库所属的国家或地区。	`"ESP"`
`validation_type`	字符串（枚举）	否	结果的佐证方式：`one_by_one`（单一服务的结果）、`two_by_two`（两个或更多不同服务独立完整匹配了证件号码）或 `not_enabled`（验证器被跳过，或没有任何服务商响应。明确的 `no_match` 仍会返回 `one_by_one`）。绝不为 `null`。来源：`DatabaseValidationChoices`（`common/config/choices.py:1097-1100`）。	`"one_by_one"`
`screened_data`	对象	否	提交给注册库的数据。文件字段（`selfie`、`cnh_qr_code_image`、`document_image`）在读取时生成预签名链接。	`{ "document_number": "99999999R", "date_of_birth": "1990-05-12" }`
`validations`	对象数组	否	每个产生匹配的目录服务对应一条记录。每条记录可包含 `service_id`、`service_name`、`validation`（服务商判定对象）、`outcome_code`、`outcome_detail` 和 `source_data`（清洗后的公民档案：`full_name`、`gender`、`date_of_birth`、`photo`（预签名 URL）、`signature`（预签名 URL）……）。	`[…]`
`errors`	对象数组	是	查询失败时各服务的错误信息。为空时该键会被完全省略。每条记录是上游服务的错误对象，外加产生该错误的 `service_id`。	`[]`
`match_type`	字符串（枚举）	是	各被查询服务的汇总匹配结论：`full_match`、`partial_match` 或 `no_match`（`DatabaseValidationMatchTypeChoices`，`common/config/choices.py:1103-1106`）。评估前为 `null`。	`"full_match"`
`status`	字符串	否	参见状态枚举。	`"Approved"`
`node_id`	字符串 \| null	是	工作流节点标识符（V3）。	`"first_db_validation"`
`warnings`	数组	否	参见警告对象。	`[]`

{
  "issuing_state": "ESP",
  "validation_type": "one_by_one",
  "screened_data": {
    "document_number": "99999999R",
    "date_of_birth": "1990-05-12",
    "first_name": "María",
    "last_name": "García López"
  },
  "validations": [
    {
      "service_id": "esp_dni",
      "service_name": "Spain - DNI/NIE verification",
      "validation": { "is_valid": true, "match_score": 100 },
      "outcome_code": "MATCH",
      "outcome_detail": "All identifiers match the registry record.",
      "source_data": {
        "full_name": "María García López",
        "gender": "F",
        "date_of_birth": "1990-05-12",
        "photo": "https://<media-host>/.../registry_photo.jpg?signature=...",
        "signature": null
      }
    }
  ],
  "match_type": "full_match",
  "status": "Approved",
  "node_id": "first_db_validation",
  "warnings": []
}

问卷回复

每次提交问卷时返回。在 KYC 和 KYB 会话的 GET /v3/session/{sessionId}/decision/ 中以 questionnaire_responses[] 形式出现。来源：questionnaires/serializers/questionnaire.py:591-597（QuestionnaireResponseV3Serializer，继承自 questionnaires/serializers/questionnaire.py:520-588 中的 QuestionnaireResponseSerializer）。

字段	类型	可为空	说明	示例
`questionnaire_id`	字符串（UUID）	否	所答问卷版本的标识符。	`"6a0f1c2c-…"`
`title`	字符串	否	问卷名称，与控制台中设置的一致。	`"Customer risk profile"`
`description`	字符串	是	问卷描述。	`"Short risk-profile questions."`
`languages`	字符串数组	否	问卷发布所用的语言代码。	`["en", "es"]`
`default_language`	字符串	否	回退语言代码。	`"en"`
`is_active`	布尔值	否	该问卷版本是否为当前生效的版本。	`true`
`is_simple_questionnaire`	布尔值	否	问卷没有分支（为平铺列表）时为 `true`。	`true`
`questionnaire_group_id`	字符串（UUID）	否	同一问卷各版本共享的标识符。	`"a7c2c2c2-…"`
`version`	整数	否	当前生效模板的版本号。	`3`
`status`	字符串	否	其中之一：`Approved`、`In Review`、`Not Finished`（问卷级拒绝映射为 `In Review`）。	`"Approved"`
`published_at`	字符串（ISO 8601）	是	模板的发布时间。	`"2026-01-12T11:00:00Z"`
`sections`	对象数组	否	经过图遍历和可见性过滤后的有序章节。每个章节为 `{ title, description, items[] }`（title 和 description 来自开头的 `SECTION_HEADER`，已预先翻译）。每个条目是一个表单元素（`uuid`、`value`（节点 ID）、`element_type`、`is_required`、`title`、`description`、`placeholder`、`choices`、`max_files`、`required_if`、`repeatable_config`，以及 `answer` 字段：未作答时为 `null`，在 `HEADING`、`PARAGRAPH`、`SEPARATOR` 布局条目上省略）。文件答案包含 `{ files: [<presigned URL>, …] }`。	`[…]`
`node_id`	字符串 \| null	是	工作流节点标识符（V3）。	`"first_questionnaire"`

{
  "questionnaire_id": "6a0f1c2c-3b7d-4d2c-9eb6-fdc6c7c92ef9",
  "title": "Customer risk profile",
  "description": "Short risk-profile questions.",
  "languages": ["en", "es"],
  "default_language": "en",
  "is_active": true,
  "is_simple_questionnaire": true,
  "questionnaire_group_id": "a7c2c2c2-1111-4d2c-9eb6-fdc6c7c92ef9",
  "version": 3,
  "status": "Approved",
  "published_at": "2026-01-12T11:00:00Z",
  "sections": [
    {
      "title": "Source of funds",
      "description": null,
      "items": [
        {
          "uuid": "4f1d5e2c-aaaa-4d2c-9eb6-fdc6c7c92ef9",
          "value": "q_source_of_funds",
          "element_type": "SINGLE_CHOICE",
          "is_required": true,
          "title": "What is your main source of funds?",
          "description": null,
          "placeholder": null,
          "choices": [
            { "label": "Salary", "value": "salary" },
            { "label": "Business income", "value": "business" },
            { "label": "Investments", "value": "investments" }
          ],
          "max_files": 1,
          "required_if": null,
          "repeatable_config": null,
          "answer": { "value": "salary" }
        }
      ]
    }
  ],
  "node_id": "first_questionnaire"
}

电子签名

为电子签名步骤中的每位签署人返回。仅当工作流包含该步骤时，才会在 KYC 和 KYB 会话的 GET /v3/session/{sessionId}/decision/ 中以 signatures[] 形式出现。与其他报告对象不同，它的 status 表示签署阶段，结果则在 verdict 中；其 warnings[] 条目为 { code, node_id }，而不是警告对象。

字段	类型	可为空	说明	示例
`id`	字符串（UUID）	否	签署人的签名标识符。在证据和验证路由中作为 `signature_id` 使用。	`"0e6c2a8e-…"`
`node_id`	字符串	否	工作流节点标识符。	`"feature_signature"`
`status`	字符串	否	签署阶段：`intro`、`review`、`code`、`signing`、`signed` 或 `declined`。只有 `signed` 表示文件已签署。	`"signed"`
`verdict`	字符串	否	`Not Finished`、`Approved`、`In Review` 或 `Declined`。	`"Approved"`
`level`	字符串	否	`simple`（默认）、`aes` 或 `qes`（合格签名，为附加功能）。	`"aes"`
`format`	字符串	否	简单签名为 `pdf`；高级签名（AES）和合格签名（QES）为 `pades`。	`"pades"`
`profile`	字符串	是	高级签名（AES）或合格签名（QES）完成签署后为 `PAdES-B-LT`，否则为 null。	`"PAdES-B-LT"`
`signer`	对象	否	`{ name, capacity, company, role, roles, identity_session_id }`。`capacity` 为 `self`（KYC）或 `company`（KYB）。	`{ "name": "Jane Doe", "capacity": "self", … }`
`identity_used`	对象	否	`{ session_id, kyc_id, verified, expected_name }`：签名所依赖的已验证身份。简单签名且无已验证身份时为空。	`{ "verified": true, … }`
`certificate`	对象	是	`{ issuer, issued_to, serial, valid_from, valid_until }`。签署前为 `null`，简单签名始终为 `null`。	`{ "serial": "5A3F9C21", … }`
`confirmation`	对象	否	`{ channel, destination, confirmed_at, attempts }`。`destination` 已脱敏；`attempts` 统计输入过的验证码次数，包括正确的那次。简单签名没有验证码，因此 `channel` 和 `destination` 为 `null`。	`{ "channel": "email", … }`
`timestamp`	对象	是	`{ time, qualified, valid }`。对于 AES，`qualified` 始终为 `false`，因为时间戳由 Didit 签发；对于 QES，时间戳由合格信任服务提供方签发。签署前为 `null`，简单签名始终为 `null`。	`{ "qualified": false, … }`
`documents`	对象数组	否	`{ id, uuid, title, language, source_revision, translation_id, file_name, pages, size_bytes, sha256_original, sha256_signed, status, opened_at, read_at, read_to_end, consented_at, consent, signed_file, mode, source_format, conversion, fields }`。`status` 为 `signed`、`declined`、`not_signed` 或 `not_reached`。`mode` 为 `fields` 或 `read_and_agree`。`source_format` 为 `pdf` 或 `docx`；`conversion` 描述原始 Word 文件，PDF 则为 `null`。	`[…]`
`documents[].language`	字符串	是	尝试开始时所选版本的语言，未设置时为 `null`。若存在完全匹配的译文则使用译文，否则使用原文。签署后，此字段为实际签署所用的语言。	`"en"`
`documents[].source_revision`	字符串（UUID）	否	尝试开始时复制的源修订版本，包括选择了译文的情况。与签署人的文档 `id` 不同。	`"22222222-2222-4222-8222-222222222222"`
`documents[].translation_id`	字符串（UUID）	是	所选译文的 ID，选择原文时为 `null`。尝试开始后，文档副本及其语言选择保持不变。	`null`
`documents[].fields`	对象数组	否	文档上每个字段对应的 `{ key, type, role, label, page, x, y, width, height, required, value, display_value, value_source, filled_at, image_url, value_unavailable_reason }`。`value` 为字符串；复选框为布尔值；已应用的签名或首字母缩写为 `true`。没有字段的文档此项为空。	`[…]`
`adopted_signature`	对象	是	`{ method, font, adopted_at }`：签署人采用的签名和首字母缩写。`method` 为 `typed` 或 `drawn`；`font` 是打字签名的手写风格。采用前为 `null`。	`{ "method": "drawn", … }`
`electronic_signature_consent_at`	字符串（ISO 8601）	是	签署人同意以电子方式签署文档的时间。任一文档包含字段时设置。	`"2026-11-03T10:41:40Z"`
`evidence_file`	字符串	是	证据 PDF 的路径，签署后可用。	`"/v3/session/…/evidence/?signature_id=…"`
`warnings`	对象数组	否	`{ code, node_id }`，其中 `code` 为以下之一：`SIGNATURE_DECLINED`、`SIGNATURE_OTP_FAILED`、`SIGNATURE_NAME_MISMATCH`、`SIGNATURE_IDENTITY_NOT_VERIFIED`、`SIGNATURE_DOCUMENT_CHANGED`。	`[]`
`validation`	对象	是	`{ valid, checked_at, documents[] }`：对已签署文档最近一次的密码学校验。签署前为 `null`。无法确认签署结果时为 `{ valid: null, reason: "signature_provider_outcome_unknown", checked_at }`。	`{ "valid": true, … }`
`declined_at`	字符串（ISO 8601）	是	签署人拒签的时间。	`null`
`declined_action`	字符串	否	该步骤的 `signature_declined_action`。	`"REVIEW"`
`signed_at`	字符串（ISO 8601）	是	文档签署的时间。	`"2026-11-03T10:42:24Z"`
`expires_at`	字符串（ISO 8601）	否	签署链接失效的时间。	`"2026-11-10T10:30:00Z"`
`email_sent_at`	字符串（ISO 8601）	是	向签署人发送已签署副本邮件的时间。	`"2026-11-03T10:42:30Z"`
`email_unavailable_reason`	字符串	是	请求发送副本但未发送邮件的原因。	`null`
`ip_address`	字符串	是	签署人申请验证码时的 IP 地址。	`"203.0.113.10"`
`place`	字符串	是	未收集，始终为 `null`。	`null`
`place_unavailable_reason`	字符串	是	`not_collected`。	`"not_collected"`

电子签名报告提供了完整示例，并列出了所有嵌套字段。

年龄估算

由独立的年龄估算 API（POST /v3/age-estimation/）返回。响应在 age_estimation 包装对象下包含 Liveness check 结构的一部分字段，即 status、method、score、age_estimation、warnings，并额外包含仅独立接口才有的 user_image 人脸检测块；它不包含 reference_image、video_url、matches、face_quality 或 face_luminance。在工作流会话中没有单独的数组，估算年龄显示在 GET /v3/session/{sessionId}/decision/ 的 liveness_checks[].age_estimation 下。来源：apis/serializers/age_estimation.py:50-55（AgeEstimationResponseSerializer），包装对象在 apis/views/age_estimation.py:138-174 中组装。

字段	类型	可为空	说明	示例
`request_id`	字符串（UUID）	否	当 `save_api_request=true`（默认值）时为已保存的会话 ID；否则为临时关联 UUID。	`"3b1f1e2c-…"`
`age_estimation`	对象	否	结果包装对象：`status`（`Approved` / `Declined`）、`method`（始终为 `PASSIVE`）、`score`（活体检测分数，0-100，可为空）、`age_estimation`（最大人脸的预测年龄，单位为年，可为空）、`user_image`（`entities[]`，包含每张人脸的 `age`、`bbox` `[x_min, y_min, x_max, y_max]`、`confidence`、`gender`，另有 `best_angle`）、`warnings[]`。	`{ … }`
`vendor_data`	字符串	是	请求中回传的 `vendor_data`。	`null`
`metadata`	对象	是	请求中回传的 `metadata`。	`null`
`created_at`	字符串（ISO 8601）	否	服务端请求时间戳。	`"2026-05-17T10:22:13.512941+00:00"`

{
  "request_id": "3b1f1e2c-7777-4d2c-9eb6-fdc6c7c92ef9",
  "age_estimation": {
    "status": "Approved",
    "method": "PASSIVE",
    "score": 94.10,
    "age_estimation": 28.7,
    "user_image": {
      "entities": [
        { "age": 28.7, "bbox": [40, 40, 100, 100], "confidence": 0.72, "gender": "male" }
      ],
      "best_angle": 0
    },
    "warnings": []
  },
  "vendor_data": null,
  "metadata": null,
  "created_at": "2026-05-17T10:22:13.512941+00:00"
}

生物识别认证

生物识别认证运行的是与标准 KYC 相同的活体检测 + 人脸比对流程，但配置为将采集的人脸与现有用户的参考图像进行比较，而不是与刚通过 OCR 识别出的证件人像进行比较。没有专用的序列化器：GET /v3/session/{sessionId}/decision/ 会在 liveness_checks[] 和 face_matches[] 下返回标准的活体检测和人脸比对对象。会话的工作流配置为 workflow_type = "biometric_authentication"（WorkflowTypeChoices，common/config/choices.py:636）。

字段	类型	可为空	描述	示例
`liveness_checks`	数组，元素为活体检测	否	认证尝试的活体检测结果。	`[ { "status": "Approved", … } ]`
`face_matches`	数组，元素为人脸比对	否	与已登记参考人脸的比对结果。`source_image_session_id` 设为会话自身的 `session_id`：参考人脸（即提供的 `portrait_image`，或在省略 `portrait_image` 时通过 `vendor_data` 复用的已存储人脸）记录在认证会话本身之下（`face/views/face.py:656-659`）。	`[ { "status": "Approved", "source_image_session_id": "…", … } ]`
`status`	字符串	否	会话顶层状态（参见状态枚举）。	`"Approved"`

{
  "session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
  "status": "Approved",
  "liveness_checks": [
    {
      "status": "Approved",
      "method": "PASSIVE",
      "score": 95.10,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": null,
      "age_estimation": null,
      "matches": [],
      "face_quality": 91.20,
      "face_luminance": 53.10,
      "node_id": "biometric_auth_liveness",
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "status": "Approved",
      "score": 98.42,
      "source_image_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
      "source_image": "https://<media-host>/.../source.jpg?signature=...",
      "target_image": "https://<media-host>/.../target.jpg?signature=...",
      "node_id": "biometric_auth_face_match",
      "warnings": []
    }
  ]
}

KYB 登记信息

针对每家经公司登记机构确认的公司返回。在企业会话的 GET /v3/session/{sessionId}/decision/ 中以 registry_checks[] 出现。来源：kyb/serializers/kyb.py:939-964（RegistryCheckV3Serializer）。

字段	类型	可为空	描述	示例
`status`	字符串	否	参见状态枚举。	`"Approved"`
`node_id`	字符串 \| null	是	工作流节点标识符（V3）。	`"first_registry"`
`data_resolved`	布尔值	否	登记机构数据获取完成时为 `true`（或 `is_from_registry` 为 `false`，表示数据为手动录入）。	`true`
`company`	对象	否	完整的公司 payload，参见下方的公司对象。	`{ … }`
`ownership_structure`	对象	是	登记机构证实的股权结构：包括 `shareholders[]` 和 `beneficial_owners[]`，每位所有者都带有其登记身份、持股比例和标准 `shareholding`。	`{ "shareholders": [...], "beneficial_owners": [] }`
`warnings`	数组	否	参见警告对象。	`[]`

公司对象

来源：kyb/serializers/kyb.py:220-321（KYBCompanyResponseSerializer）。

字段	类型	可为空	描述
`uuid`	字符串（UUID）	否	内部公司标识符。
`node_id`	字符串 \| null	是	工作流节点标识符。
`status`	字符串	否	功能状态（`FeatureStatusChoices`）。
`registry_status`	字符串	是	登记机构中的公司状态（`active`、`dissolved` 等）。
`data_resolved`	布尔值	否	与父对象中的定义相同。
`company_name`	字符串	是	注册的公司名称。
`registration_number`	字符串	是	登记机构标识符。
`country_code`	字符串（ISO 3166-1 alpha-2）	是	注册国家或地区。
`region`	字符串	是	适用时为 ISO 3166-2 行政区划（例如 `US-CA`）。
`company_type`	字符串	是	法律形式（`LLC`、`SL` 等）。
`incorporation_date`	字符串（YYYY-MM-DD）	是	成立日期。
`registered_address`	字符串	是	法定注册地址。
`tax_number`	字符串	是	税号或 VAT 标识符。
`risk_level`	字符串	是	服务提供方提供的风险评级。
`verification_status`	字符串	是	内部验证状态枚举。
`is_from_registry`	布尔值	否	数据来自登记机构时为 `true`（与手动录入相对）。
`fetch_status`	字符串	是	`pending`、`resolved`、`failed`。
`alternative_names`	字符串	是	以逗号分隔的其他商号。
`nature_of_business`	字符串	是	自由文本形式的经营活动描述。
`registered_capital`	字符串	是	以便于阅读的字符串表示的注册资本。
`registered_capital_amount`	字符串（十进制）	是	解析后的注册资本金额。
`registered_capital_currency`	字符串（ISO 4217）	是	货币代码。
`website`	字符串（URL）	是	公司网站。
`email`	字符串	是	公开的联系邮箱。
`phone`	字符串	是	公开的联系电话。
`legal_entity_identifier`	字符串	是	可用时提供的 LEI。
`location_of_registration`	字符串	是	登记办事处或地区。
`vat_number`	字符串	是	为该公司提交的 VAT 号码。
`vat_validation_status`	字符串	否	对 VAT 号码进行验证的结果；若无 VAT 号码，则为对 `tax_number` 的验证结果：`valid`、`invalid`、`format_valid`、`invalid_format`、`could_not_validate` 或 `not_applicable`。参见 VAT 与税号验证。
`vat_validated_number`	字符串	是	所检查的号码，按来源方所记录的形式。
`vat_validation_source`	字符串	是	决定状态的来源：`eu_vies`、`pl_vat_white_list`、`no_brreg`、`ch_uid_register`、`br_receita_federal`、`co_rues`、`cr_hacienda`、`ec_sri`、`py_dnit` 或 `format_rules`。
`vat_validated_name`	字符串	是	在来源方登记的名称（来源方不披露时为空）。
`vat_validated_address`	字符串	是	在来源方登记的地址（未披露时为空）。
`vat_checked_at`	字符串（ISO 8601）	是	检查的时间戳；未进行检查时为 `null`。
`financial_summary`	对象	是	登记机构提供时，最新财务要点的快照。
`officers`	对象数组	否	可安全用于 B2C 场景的负责人列表：`{ uuid, name, designation, role, nationality, is_active, kyc_status, kyc_session_url }`。
`beneficial_owners`	对象数组	否	可安全用于 B2C 场景的实际受益人列表（UBO）：`{ uuid, name, first_name, last_name, entity_type, roles, ownership_min_shares, ownership_max_shares, is_active, kyc_status, kyc_session_url, effective_ownership_percent }`。
`addresses`	对象数组	是	登记机构提供的各地址明细。
`industries`	对象数组	是	SIC/NAICS 风格的行业分类。
`accounts`	对象数组	是	已提交账目的元数据。
`registry_data`	对象	是	Didit 标准化后的登记机构详细信息（所有权结果、控制台更正，以及没有独立字段的登记事实）。不是稳定的契约。
`user_provided_data`	对象	是	用户编辑字段的快照。
`confirmed_by_user_at`	字符串（ISO 8601）	是	用户确认提取数据的时间戳。
`last_console_edit_at`	string (ISO 8601)	是	最近一次控制台编辑的时间戳。
`is_editable`	boolean	否	当登记来源数据仍可由终端用户编辑时为 `true`。

{
  "status": "Approved",
  "node_id": "first_registry",
  "data_resolved": true,
  "company": {
    "uuid": "b1f1e2c2-9999-4d2c-9eb6-fdc6c7c92ef9",
    "node_id": "first_registry",
    "status": "Approved",
    "registry_status": "active",
    "data_resolved": true,
    "company_name": "Sante Clinics SL",
    "registration_number": "B12345678",
    "country_code": "ES",
    "region": null,
    "company_type": "SL",
    "incorporation_date": "2018-03-22",
    "registered_address": "Calle Mayor 1, 28001 Madrid, Spain",
    "tax_number": "B12345678",
    "risk_level": "low",
    "verification_status": "verified",
    "is_from_registry": true,
    "fetch_status": "resolved",
    "alternative_names": "Sante Clinics",
    "nature_of_business": "Medical clinic operations",
    "registered_capital": "EUR 50,000",
    "registered_capital_amount": "50000.00",
    "registered_capital_currency": "EUR",
    "website": "https://santeclinics.com",
    "email": "info@santeclinics.com",
    "phone": "+34911223344",
    "legal_entity_identifier": null,
    "location_of_registration": "Registro Mercantil de Madrid",
    "vat_number": "ESB12345678",
    "vat_validation_status": "valid",
    "vat_validated_name": "SANTE CLINICS SL",
    "vat_validated_address": "CALLE MAYOR 1, 28001 MADRID",
    "vat_checked_at": "2026-05-17T10:11:05Z",
    "financial_summary": null,
    "officers": [
      {
        "uuid": "c1f1e2c2-aaaa-4d2c-9eb6-fdc6c7c92ef9",
        "name": "María García López",
        "designation": "Administrador único",
        "role": "Director",
        "nationality": "ESP",
        "is_active": true,
        "kyc_status": "Approved",
        "kyc_session_url": "https://verify.didit.me/s/…"
      }
    ],
    "beneficial_owners": [
      {
        "uuid": "d1f1e2c2-bbbb-4d2c-9eb6-fdc6c7c92ef9",
        "name": "María García López",
        "first_name": "María",
        "last_name": "García López",
        "entity_type": "person",
        "roles": ["UBO"],
        "ownership_min_shares": "75.00",
        "ownership_max_shares": "75.00",
        "is_active": true,
        "kyc_status": "Approved",
        "kyc_session_url": "https://verify.didit.me/s/…",
        "effective_ownership_percent": 75.0
      }
    ],
    "addresses": [],
    "industries": [],
    "accounts": [],
    "registry_data": {},
    "user_provided_data": {},
    "confirmed_by_user_at": "2026-05-17T10:11:02Z",
    "last_console_edit_at": null,
    "is_editable": false
  },
  "ownership_structure": null,
  "warnings": []
}

KYB 证件

按收集 KYB 佐证证件的节点返回。在企业会话的 GET /v3/session/{sessionId}/decision/ 响应中以 document_verifications[] 形式出现，每个 node_id 对应一条记录，其中 items[] 列出每份已上传的证件。来源：kyb/serializers/kyb.py:1053-1068（DocumentVerificationV3Serializer），每个项目遵循 kyb/serializers/kyb.py:811-851（KYBDocumentResponseSerializer）。

字段	类型	可为空	描述	示例
`status`	string	否	该节点所有证件的汇总状态：仅当流程中的每份证件都已通过时为 `Approved`；任一证件被拒绝则为 `Declined`；其他情况为 `In Review`；等待中时为 `Not Finished`。参见状态枚举。	`"Approved"`
`node_id`	string \| null	是	工作流节点标识符（V3）。	`"first_kyb_documents"`
`items`	array of KYB 证件项目对象	否	每份已上传或被要求提供的证件对应一条记录。	`[…]`
`groups`	object	否	按证件组统计的数量：`{ <group_name>: { total, approved, pending, declined, in_review, other, missing } }`。	`{ "incorporation_certificate": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 } }`
`required_groups`	array of strings	否	工作流配置要求的证件组。	`["incorporation_certificate", "shareholder_register"]`
`warnings`	array	否	参见警告对象。	`[]`

KYB 证件项目对象

字段	类型	可为空	描述
`uuid`	string (UUID)	否	内部证件标识符。
`document_type`	string	是	高层级证件组（`incorporation_certificate`、`shareholder_register` 等）。
`document_subtype`	string	是	服务提供方特定的子类型。
`document_group`	string	是	`document_type` 的镜像（为清晰起见保留的别名）。
`file_url`	string (URL)	是	指向已清理文件的预签名 URL。
`original_filename`	string	是	上传时的文件名。
`file_size`	integer	是	文件大小，单位为字节。
`status`	string	否	单份证件的状态（`FeatureStatusChoices`）。
`created_at`	string (ISO 8601)	否	上传时间戳。
`cross_check_result`	object	是	与登记信息及其他证件交叉核验的结论。
`document_metadata`	object	是	与 POA 的 `document_metadata` 相同的过滤后元数据结构。
`description`	string	是	由审核员或系统提供的描述。
`is_requested`	boolean	否	工作流预期提供此证件时为 `true`。
`ocr_data`	object	是	可用时，OCR 提取的字段。
`is_console_upload`	boolean	否	由控制台审核员上传的证件为 `true`，且不计入汇总结论。
`is_confirmed`	boolean	否	审核员已明确确认该证件时为 `true`。

{
  "status": "Approved",
  "node_id": "first_kyb_documents",
  "items": [
    {
      "uuid": "e1f1e2c2-cccc-4d2c-9eb6-fdc6c7c92ef9",
      "document_type": "incorporation_certificate",
      "document_subtype": "registro_mercantil_extract",
      "document_group": "incorporation_certificate",
      "file_url": "https://<media-host>/.../incorporation.pdf?signature=...",
      "original_filename": "incorporation_certificate.pdf",
      "file_size": 256412,
      "status": "Approved",
      "created_at": "2026-05-17T10:08:00Z",
      "cross_check_result": { "matches_registry_name": true, "matches_registration_number": true },
      "document_metadata": {
        "file_size": 256412,
        "content_type": "application/pdf",
        "is_signed": true,
        "is_tampered": false
      },
      "description": null,
      "is_requested": true,
      "ocr_data": { "company_name": "Sante Clinics SL", "registration_number": "B12345678" },
      "is_console_upload": false,
      "is_confirmed": true
    }
  ],
  "groups": {
    "incorporation_certificate": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 }
  },
  "required_groups": ["incorporation_certificate", "shareholder_register"],
  "warnings": []
}

KYB 关键人员

按 KYB 工作流中的每个关键人员节点返回。在企业会话的 GET /v3/session/{sessionId}/decision/ 响应中以 key_people_checks[] 形式出现。来源：kyb/serializers/kyb.py:967-1050（KeyPeopleCheckV3Serializer）。

字段	类型	可为空	描述	示例
`status`	string	否	参见状态枚举。	`"Approved"`
`node_id`	string \| null	是	工作流节点标识符（V3）。	`"first_key_people"`
`registry`	object	否	从登记信息中提取的 `{ officers[], beneficial_owners[] }`。高管遵循 `KYBPersonResponseSerializer`（`kyb/serializers/kyb.py:533-645`）；实际受益人遵循 `KYBBeneficialOwnerResponseSerializer`（`kyb/serializers/kyb.py:648-788`），并额外包含 `date_of_birth`、`country_of_birth`、`email`、`company_name`、`registration_number`、`entity_type`、`roles`、`ownership_min_shares`、`ownership_max_shares`、`child_beneficial_owners`、`effective_ownership_percent`。两者均包含按相关方补充的 AML 与 KYC 信息（`aml_status`、`kyc_status`、`kyc_session_url`、`kyc_session_id`、`verification_workflow_type`、`verification_workflow_id`、`verification_workflow_label`、`verification_workflow_features`、`didit_internal_id`、`kyc_document_type`、`kyc_nationality`、`kyc_liveness_passed`、`kyc_verified_at`、`kyc_aml_categories`、`kyc_notification_sent_at`）。	`{ "officers": [...], "beneficial_owners": [...] }`
`submitted`	object	否	`{ parties[] }`，即企业通过关键人员流程确认或提交的条目（`source=USER` 的 `BusinessParty` 记录）。每个相关方遵循 `BusinessPartySubmissionResponseSerializer`（`kyb/serializers/party.py:146-194`）：`uuid`、`entity_type`、`source`、`name`、`first_name`、`last_name`、`company_name`、`registration_number`、`email`、`nationality`、`phone_number`、`date_of_birth`、`position`、`custom_fields`、`is_active`、`is_skipped`、`requires_verification`、`roles[]`（`{ role, ownership_percent, voting_percent }`）、`kyc_session_id`、`kyc_session_status`、`kyc_session_url`、`kyc_session_deleted`、`kyb_sub_session_id`、`kyb_sub_session_status`、`kyb_sub_session_url`、`kyb_sub_session_deleted`、`verification_workflow_type`、`verification_workflow_id`、`verification_workflow_label`、`verification_workflow_features`、`didit_internal_id`。`kyc_session_deleted` 与 `kyb_sub_session_deleted` 表示子会话已被删除：其状态保持在删除前的值，对应的 `*_session_url` 返回 `null`，因为链接已无法访问，该相关方也不再阻塞父会话（检查结果会转为 `In Review`）。如需清除该标记，请使用 `PATCH /v3/session/{id}/kyb/parties/{party_uuid}/`。	`{ "parties": [...] }`
`ubo_kyc_summary`	object	是	有效 UBO 中已关联 KYC 的数量统计：`{ total, approved, flagged, pending }`。若没有已关联 KYC 的有效 UBO，则为 `null`。	`{ "total": 2, "approved": 2, "flagged": 0, "pending": 0 }`
`warnings`	数组	否	参见警告对象。	`[]`

{
  "status": "Approved",
  "node_id": "first_key_people",
  "registry": {
    "officers": [
      {
        "uuid": "c1f1e2c2-aaaa-4d2c-9eb6-fdc6c7c92ef9",
        "name": "María García López",
        "designation": "Administrador único",
        "role": "Director",
        "nationality": "ESP",
        "appointment_date": "2018-03-22",
        "termination_date": null,
        "is_active": true,
        "address": "Calle Mayor 1, 28001 Madrid",
        "aml_status": "Approved",
        "kyc_status": "Approved",
        "kyc_session_url": "https://verify.didit.me/s/…",
        "kyc_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
        "verification_workflow_type": "kyc",
        "verification_workflow_id": "11111111-1111-1111-1111-111111111111",
        "verification_workflow_label": "KYB officer KYC",
        "verification_workflow_features": [
          { "feature": "ID_VERIFICATION", "status": "Approved" },
          { "feature": "LIVENESS", "status": "Approved" },
          { "feature": "FACE_MATCH", "status": "Approved" }
        ],
        "didit_internal_id": "user-12345",
        "kyc_document_type": "Passport",
        "kyc_nationality": "ESP",
        "kyc_liveness_passed": true,
        "kyc_verified_at": "2026-05-17T10:10:11Z",
        "kyc_aml_categories": [],
        "kyc_notification_sent_at": "2026-05-15T08:00:00Z"
      }
    ],
    "beneficial_owners": []
  },
  "submitted": {
    "parties": [
      {
        "uuid": "d1f1e2c2-bbbb-4d2c-9eb6-fdc6c7c92ef9",
        "entity_type": "person",
        "source": "USER",
        "name": "María García López",
        "first_name": "María",
        "last_name": "García López",
        "company_name": null,
        "registration_number": null,
        "email": "maria.garcia@example.com",
        "nationality": "ESP",
        "phone_number": null,
        "date_of_birth": "1990-05-12",
        "position": "Administrador único",
        "custom_fields": {},
        "is_active": true,
        "is_skipped": false,
        "requires_verification": true,
        "roles": [
          { "role": "UBO", "ownership_percent": 75.0, "voting_percent": null }
        ],
        "kyc_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
        "kyc_session_status": "Approved",
        "kyc_session_url": "https://verify.didit.me/s/…",
        "kyb_sub_session_id": null,
        "kyb_sub_session_status": null,
        "kyb_sub_session_url": null,
        "verification_workflow_type": "kyc",
        "verification_workflow_id": "11111111-1111-1111-1111-111111111111",
        "verification_workflow_label": "KYB officer KYC",
        "verification_workflow_features": [
          { "feature": "ID_VERIFICATION", "status": "Approved" },
          { "feature": "LIVENESS", "status": "Approved" }
        ],
        "didit_internal_id": "user-12345"
      }
    ]
  },
  "ubo_kyc_summary": { "total": 1, "approved": 1, "flagged": 0, "pending": 0 },
  "warnings": []
}

决策层级字段

这些字段位于 GET /v3/session/{sessionId}/decision/ 响应及 Webhook 的 decision 内部，与功能数组并列。

字段	类型	可为空	说明
`status_override`	object	是	审核员手动设置 `status` 后的 `{ overridden_at, automatic_status }`；当状态为自动判定时为 `null`。
`decision_trace`	object	否	状态的达成过程：`status`、`decided_by`（`manual`、`automatic` 或 `investigator`）、`decided_at`、`automatic_status`、`terminal_node_id`、`actor`、`warning_counts` 以及 `status_warnings`。
`linked_records`	object	是	`same_face`、`earlier_verifications` 和 `networks` 摘要；无内容展示时为 `null`。
`biometric_retention`	object	否	`{ jurisdictions, deletes_at }`。`deletes_at` 为该会话的实时生物特征数据被删除的日期，尚未适用具体日期时为 `null`。
`database_validation_not_performed_reason`	object	是	解释为何已配置的数据库核验未产生结果的 `{ code, message }`。
`assignee`、`waiting_since`、`sla_due_at`	object、datetime	是	处理该会话的 Console 审核员及其审核计时器；除非会话处于 `In Review` 状态，否则该计时器为 `null`。
`shared_from_session`、`shared_from_session_number`	UUID、integer	是	导入会话的源会话。
`sandbox_scenario`	string	是	创建沙盒会话时所使用的场景。
`fraud_check`	object	是	Fraud Check API 结果；对其余所有会话均为 `null`。
`full_session_video`、`full_session_video_recorded_at`	URL、datetime	是	录像及其录制时间。仅在您的组织启用了完整会话视频录制时返回。

有关如何读取这些字段，请参阅获取会话。

生物识别同意

每个用户验证决策和会话 Webhook 都包含一个单一的 biometric_consent 对象（非数组）：说明该会话是否需要明确的生物识别同意、原因以及该答复的证据。当会话从未被评估时（例如不含人脸采集的工作流），该字段为 null。来源：BiometricConsentDecisionSerializer（sessions/serializers/biometric_consent.py）。何时出现此步骤以及各种情况的具体含义，请参阅生物识别同意。没有记录值的字段为 null，绝不会是空字符串。

字段	类型	说明
`required`	boolean	该会话是否必须收集明确的生物识别同意。绝不会变回 `false`。
`trigger`	string (enum) \| null	为什么需要同意，或它是如何被满足的：`declared_state`、`ip_state`、`ip_unknown`、`document_issuer`、`forced`（应用的模式为 Always）、`customer_collected`（您在创建会话时发送了 `biometric_consent`）。在不需要时为 `null`。
`status`	string (enum)	`not_required`、`pending`（需要，但尚未给出）、`given`、`declined`（已记录拒绝；目前没有 Didit 界面提供拒绝选项）。
`given_at`	string (ISO 8601) \| null	给出同意的时间。对于 `customer_collected`，为您发送的 `given_at`。
`declined_at`	string (ISO 8601) \| null	记录拒绝的时间。
`text_version`	string \| null	用户做出答复或您发送的同意文本的版本 ID。
`text_hash`	string \| null	所显示确切文本（按其显示的语言）的 SHA-256（十六进制）。
`locale`	string \| null	显示文本所用的语言。
`policy_url`	string \| null	该步骤链接的生物识别数据政策。
`step`	string \| null	用户做出答复时会话所在的工作流步骤（例如 `LIVENESS`）。
`node_id`	string \| null	用户做出答复时会话所在的工作流图谱节点。
`ip_address`	string \| null	做出答复的地址。
`ip_country_code`	string \| null	答复 IP 的 ISO 3166-1 alpha-2 国家/地区代码。
`ip_state`	string \| null	答复 IP 的 ISO 3166-2 细分代码（例如 `US-IL`）。
`ip_city`	string \| null	答复 IP 的城市。
`user_agent`	string \| null	答复请求的用户代理。
`detected_ip_address`	string \| null	上次评估该要求时检测到的用户地址。当用户在另一台设备上做出答复时，可能与 `ip_address` 不同。
`detected_country_code`	string \| null	检测到的 IP 的 ISO 3166-1 alpha-2 国家/地区代码。
`detected_state`	string \| null	检测到的 IP 的 ISO 3166-2 细分代码。
`detected_city`	string \| null	检测到的 IP 的城市。
`declared_state`	string \| null	您申报的 ISO 3166-2 细分代码：`user_state`，或 `expected_details` 中美国地址的州。
`document_state`	string \| null	签发该身份证件的 ISO 3166-2 细分代码，在证件采集时读取。
`jurisdictions`	array of string	其生物识别法律涵盖该用户的美国州（USPS 代码，例如 `IL`）。当证据表明该用户在美国但未知具体州时为 `US`。若均不适用则为空。
`retention_months`	integer \| null	`jurisdictions` 中最短的生物特征保留期限（以月为单位）。若均不适用则为 `null`。
`reason`	string (enum) \| null	`BIOMETRIC_CONSENT_UNSUPPORTED_SDK`：需要同意，但低于 4.10.0 版本的原生 SDK（或未上报其版本的 SDK）在未执行该步骤的情况下采集了人脸；`status` 保持为 `pending`，如果用户稍后在托管流程中同意，则变为 `given`。`BIOMETRIC_CONSENT_DECLINED`：记录了拒绝（会替代 SDK 原因）。在其他情况下为 `null`，且在会话不需要同意时始终为 `null`。
`decline_reason`	string \| null	当记录的拒绝导致会话终止时为 `BIOMETRIC_CONSENT_DECLINED`，否则为 `null`。
`face_data_deleted_at`	string (ISO 8601) \| null	拒绝导致删除会话的人脸图像、视频和人脸模板的时间。除非记录了拒绝，否则为 `null`。

在伊利诺伊州由低于 4.10.0 版本的原生 SDK 提供服务、并在未执行该步骤的情况下采集了自拍照的会话：

{
  "required": true,
  "trigger": "ip_state",
  "status": "pending",
  "given_at": null,
  "declined_at": null,
  "text_version": null,
  "text_hash": null,
  "locale": null,
  "policy_url": null,
  "step": null,
  "node_id": null,
  "ip_address": null,
  "ip_country_code": null,
  "ip_state": null,
  "ip_city": null,
  "user_agent": null,
  "detected_ip_address": "203.0.113.42",
  "detected_country_code": "US",
  "detected_state": "US-IL",
  "detected_city": "Chicago",
  "declared_state": null,
  "document_state": null,
  "jurisdictions": ["IL"],
  "retention_months": 36,
  "reason": "BIOMETRIC_CONSENT_UNSUPPORTED_SDK",
  "decline_reason": null,
  "face_data_deleted_at": null
}

使用出口位于美国境外的 VPN、并在托管流程中表示同意的用户：

{
  "required": true,
  "trigger": "declared_state",
  "status": "given",
  "given_at": "2026-10-13T18:31:07.412000Z",
  "declined_at": null,
  "text_version": "bio-consent-2026-10-12",
  "text_hash": "9b2f0c5e4d8a7f61c3e2b4a5d6f7081923a4b5c6d7e8f90a1b2c3d4e5f6a7b8c",
  "locale": "en",
  "policy_url": "https://didit.me/legal/biometric-data-policy",
  "step": "LIVENESS",
  "node_id": "feature_liveness_1",
  "ip_address": "198.51.100.23",
  "ip_country_code": "ES",
  "ip_state": "ES-M",
  "ip_city": "Madrid",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1",
  "detected_ip_address": "198.51.100.23",
  "detected_country_code": "ES",
  "detected_state": "ES-M",
  "detected_city": "Madrid",
  "declared_state": null,
  "document_state": null,
  "jurisdictions": ["IL"],
  "retention_months": 36,
  "reason": null,
  "decline_reason": null,
  "face_data_deleted_at": null
}

状态枚举参考

两个相关的值空间共用 status 字段名。本页中的每个功能报告对象均使用功能级枚举；父会话的顶层 status 则使用更广泛的会话枚举。

功能级状态

供每个报告对象的 status 字段使用。来源：common/config/choices.py:343-348（FeatureStatusChoices）。

值	含义
`Not Finished`	该功能已配置，但用户尚未完成。
`Approved`	该功能通过了所有检查。
`Declined`	该功能未通过至少一项硬性检查（参见带有 `log_type: "error"` 的 `warnings[]`）。
`In Review`	该功能触发了软性未通过信号，正在等待人工审核（参见带有 `log_type: "warning"` 的 `warnings[]`）。
`Resub Requested`	审核员已要求用户重新提交该功能。

当其对应步骤超时时，电话验证、邮箱验证和身份证件验证还可能呈现 Expired（PhoneStatusChoices 见 common/config/choices.py:377-382，EmailStatusChoices 见 common/config/choices.py:434-439）。

会话级状态

供父会话的顶层 status 使用。来源：common/config/choices.py:106-117（StatusChoices）。

值	含义
`Not Started`	会话已创建，但用户尚未开始。
`In Progress`	用户已开始流程；结果尚未最终确定。
`Approved`	会话通过了所有检查。
`Declined`	会话未通过至少一项硬性检查。
`In Review`	会话正在等待人工审核。
`Expired`	会话在完成前已过期。
`Abandoned`	用户在未完成流程的情况下离开。
`Kyc Expired`	KYC 的有效期已过（用于重新验证流程）。
`Resubmitted`	用户在先前被拒绝后重新提交；该会话已被较新的会话取代。
`Awaiting User`	系统正在等待用户端操作（例如输入 OTP）。

会话的终止状态值为 Approved、Declined、In Review、Expired、Kyc Expired 和 Abandoned。即使单个功能仍处于 In Review 状态，会话也可以得出其总体决策。