数据模型 (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"
}

报告对象

其余部分涵盖每个功能的报告对象。H3 标题文本保持稳定，以便其他文档进行深度链接。

身份证件验证

针对用户提交的每份 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`	string	否	参见状态枚举。	`"Approved"`
`document_type`	string	是	人类可读的证件类别（`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`	string	是	来自 Didit 证件注册库的证件子类型代码，并根据工作流证件设置接受的类型进行过滤。特定地区的证件包含地区信息。完整代码列表：证件子类型。	`"QUEENSLAND_DRIVER_LICENSE_GENERIC"`
`document_number`	string	是	OCR 提取的证件号码。	`"AB1234567"`
`personal_number`	string	是	OCR 提取的个人/国民身份证件号。	`"99999999R"`
`portrait_image`	string (URL)	是	人脸裁剪图的预签名 URL。	`"https://<media-host>/.../portrait.jpg?..."`
`front_image`	string (URL)	是	清理后的证件正面预签名 URL。	`"https://<media-host>/.../front.jpg?..."`
`front_video`	string (URL)	是	正面拍摄视频的预签名 URL（可用时提供）。	`"https://<media-host>/.../front.mp4?..."`
`back_image`	string (URL)	是	清理后的证件背面预签名 URL。	`"https://<media-host>/.../back.jpg?..."`
`back_video`	string (URL)	是	背面拍摄视频的预签名 URL。	`null`
`full_front_image`	string (URL)	是	未裁剪（完整画面）的正面拍摄图像。	`"https://<media-host>/.../full_front.jpg?..."`
`full_back_image`	string (URL)	是	未裁剪（完整画面）的背面拍摄图像。	`null`
`front_image_camera_front`	string (URL)	是	拍摄证件正面时同时由前置摄像头拍摄的图像。	`null`
`back_image_camera_front`	string (URL)	是	拍摄证件背面时同时由前置摄像头拍摄的图像。	`null`
`front_image_camera_front_face_match_score`	float (0-100)	是	证件人像与前置摄像头拍摄图像之间的相似度。	`null`
`back_image_camera_front_face_match_score`	float (0-100)	是	与上述相同，但对应背面拍摄。	`null`
`document_selfie_face_matches`	array	是	与证件拍摄期间拍摄的自拍照相匹配的历史会话或人脸黑名单条目。条目格式与 `liveness_checks[].matches` 相同。未运行搜索时为 `null`，无匹配项时为 `[]`。	`null`
`front_image_quality_score`	object	是	正面图像质量指标：分值 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`	object	是	格式与 `front_image_quality_score` 相同。	`null`
`date_of_birth`	string (YYYY-MM-DD)	是	OCR 提取的出生日期。	`"1990-05-12"`
`age`	integer	是	提取时计算出的周岁年龄。	`35`
`expiration_date`	string (YYYY-MM-DD)	是	证件到期日期。	`"2032-05-11"`
`date_of_issue`	string (YYYY-MM-DD)	是	证件签发日期。	`"2022-05-11"`
`issuing_state`	string (ISO 3166-1 alpha-3)	是	签发国家/地区代码。	`"ESP"`
`issuing_state_name`	string	是	本地化的签发国家/地区名称。	`"Spain"`
`first_name`	string	是	OCR 提取的名字。	`"María"`
`last_name`	string	是	OCR 提取的姓氏。	`"García López"`
`full_name`	string	是	规范化全名（由服务商提供）。	`"María García López"`
`gender`	string	是	`M`、`F` 或服务商提供的其他值。	`"F"`
`address`	string	是	OCR 提取的原始地址行。	`"Calle Mayor 1, 28001 Madrid"`
`formatted_address`	string	是	地理编码/格式化地址（可解析时）。	`"Calle Mayor 1, 28001 Madrid, Spain"`
`parsed_address`	object	是	结构化、经地理编码的地址：`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`	string	是	OCR 提取的出生地点。	`"Madrid"`
`marital_status`	string	是	可提取时提供。	`null`
`nationality`	string (ISO 3166-1 alpha-3)	是	OCR 提取的国籍。	`"ESP"`
`extra_fields`	object	是	标准架构未涵盖的特定证件类型字段（例如驾照准驾车型）。	`{ "DL Class": "B" }`
`mrz`	object	是	存在时解析的 MRZ 字段（`document_number`、`birth_date`、`expiry_date`、`surname`、`given_names`……）。	`{ "document_number": "AB1234567", "surname": "GARCIA", "given_names": "MARIA" }`
`extra_files`	array of strings (URL)	否	任何额外上传文件的预签名 URL。	`[]`
`matches`	array of objects	否	跨会话证件匹配项。每个条目包含：`{ 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`	对象数组	否	从证件条形码中读取的数据，每个条形码对应一项，包含 `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 电子护照或 eID 芯片，或通过 JPKI 读取的日本个人编号卡（My Number Card，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	是	从芯片数据组（Data Groups）解析并扁平化后的个人数据（`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`	object	是	证件签名证书摘要（`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`	string \| null	是	工作流节点标识符（V3）。	`"first_nfc"`
`is_nfc_skipped`	boolean	否	当此 NFC 步骤被明确跳过而非读取时为 `true`；`skip_reason` 说明了跳过原因。	`false`
`skip_reason`	string	是	跳过该步骤的原因，仅在 `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`	string	否	芯片的读取方式：`icao`（ICAO 9303 电子护照或 eID 芯片）或 `jpki`（日本个人编号卡 My Number Card）。对于 `jpki`，`portrait_image`、`signature_image`、`chip_data`、`authenticity` 和 `certificate_summary` 为 `null`。在跳过的步骤中也会设置。	`"icao"`
`jpki`	object	是	个人编号卡读取所证明的内容：`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`	array	否	参见警告对象。	`[]`

{
  "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": []
}

活体检测

每个活体检测会话返回一次。在 GET /v3/session/{sessionId}/decision/ 中体现为 liveness_checks[]。源码：face/serializers/face.py:301-320（LivenessV3Serializer，继承位于 face/serializers/face.py:216-298 的 LivenessV2Serializer）。

字段	类型	可为空	描述	示例
`status`	string	否	参见状态枚举。	`"Approved"`
`method`	string (enum)	是	`ACTIVE_3D`、`FLASHING` 或 `PASSIVE`（`LivenessMethodChoices`，`common/config/choices.py:514-517`）。当允许桌面端会话且用户使用桌面设备时，运行被动模式。	`"PASSIVE"`
`score`	float (0-100)	是	活体置信度，保留 2 位小数。	`92.41`
`reference_image`	string (URL)	是	用户参考人脸裁剪图像的预签名 URL。	`"https://<media-host>/.../reference.jpg?..."`
`video_url`	string (URL)	是	活体检测视频的预签名 URL（仅限主动模式）。	`"https://<media-host>/.../liveness.webm?..."`
`age_estimation`	float	是	参考图像中最大人脸的估算年龄（周岁）。	`34.2`
`matches`	array of objects	否	跨会话人脸匹配结果。每项包含：`{ 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`	float (0-100)	是	被动活体人脸质量评分（归一化为百分比）。	`87.50`
`face_luminance`	float (0-100)	是	被动活体人脸亮度评分（从 0-255 归一化为百分比）。	`54.12`
`node_id`	string \| null	是	工作流节点标识符（V3）。	`"first_liveness"`
`warnings`	array	否	参见警告对象。	`[]`

{
  "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": []
}

人脸比对

每次人脸比对返回一次（通常为用户的活体人脸与证件人像比对）。在 GET /v3/session/{sessionId}/decision/ 中体现为 face_matches[]。源码：face/serializers/face.py:367-389（FaceMatchV3Serializer，继承位于 face/serializers/face.py:323-364 的 FaceMatchV2Serializer）。

字段	类型	可为空	描述	示例
`status`	string	否	参见状态枚举。	`"Approved"`
`score`	float (0-100)	是	相似度，保留 2 位小数。当服务商仅返回 `unmatched_faces[].Confidence` 时，转换为 `100 - confidence`。	`97.83`
`source_image_session_id`	string (UUID)	是	其存储的人像提供源（参考）图像的会话，在基于人像的流程（生物识别认证，或在创建会话时提供的人像）中设置。当参考图像来自同一会话的证件人像时为 `null`。	`null`
`source_image`	string (URL)	是	源（参考）图像的预签名 URL，通常是证件人像，或生物识别认证流程中的存储人像。	`"https://<media-host>/.../source.jpg?..."`
`target_image`	string (URL)	是	活体检测期间捕获的目标（活体人脸）图像的预签名 URL。	`"https://<media-host>/.../target.jpg?..."`
`node_id`	string \| null	是	工作流节点标识符（V3）。	`"first_face_match"`
`warnings`	array	否	参见警告对象。	`[]`
`face_coverage`	object	是	捕获的图像中 `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 条目，以及一个携带已存储 matches 的 liveness_checks[] 项。源码：apis/serializers/face_search.py:8-79（包装 FaceSearchDetailsSerializer 的 FaceSearchResponseSerializer）；匹配字典构建于 face/utils/utils.py:869-884。顶层响应：

字段	类型	可为 null	描述	示例
`request_id`	string (UUID)	否	当 `save_api_request=true` 时的持久化会话 ID（可用于 `GET /v3/session/{sessionId}/decision/`）；否则为一个临时的关联 UUID。	`"4a1c2c4e-8b1b-4d6a-91b5-ee9a1f3a2c7f"`
`face_search`	object	否	搜索详情 payload — 参见下方字段。	—
`vendor_data`	string	是	来自请求中回传的 `vendor_data`。	`null`
`metadata`	object	是	来自请求中回传的 `metadata`。	`null`
`created_at`	string (ISO 8601)	否	服务端请求时间戳。	`"2026-06-12T01:04:42.763237+00:00"`

face_search 对象：

字段	类型	可为 null	描述	示例
`status`	string	否	仅当触发 `FACE_IN_BLOCKLIST` 或 `POSSIBLE_FACE_IN_BLOCKLIST` 警告时为 `Declined`；否则为 `Approved` — 仅凭重复匹配绝不会拒绝（`apis/views/face_search.py:242-248`）。	`"Approved"`
`total_matches`	integer	否	`matches[]` 中返回的匹配数量（0–5）。	`1`
`matches`	array of 人脸搜索匹配对象	否	高于相似度下限的最多 5 个匹配项，按相似度降序排列（当 `search_type=blocklisted_or_approved` 时黑名单条目排在最前）。	`[…]`
`user_image`	object	否	提交图片的检测结果：`{ entities: [{ bbox, confidence }], best_angle }` — 每个检测到的人脸对应一个实体。	`{ "entities": [{ "bbox": [40, 40, 120, 120], "confidence": 0.73 }], "best_angle": 0 }`
`warnings`	array of objects	否	该独立 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`）。	`[]`

人脸搜索匹配对象

字段	类型	可为 null	描述	示例
`session_id`	string (UUID)	是	匹配的验证会话。当 `source` 为 `imported`、`list_entry` 或 `retained_template` 时为 `null`。	`"a3f2a6f1-…"`
`session_number`	integer	是	控制台中易读的匹配会话编号；对于非会话匹配为 `null`。	`1024`
`similarity_percentage`	float (0-100)	否	提交的人脸与匹配人脸之间的相似度。	`96.42`
`source`	string (enum)	否	匹配人脸的录入来源：`session`（验证会话或已保存的独立调用）、`imported`（直接上传到用户资料的人脸）、`list_entry`（附加到名单的人脸）、`retained_template`（在源会话被删除后保留的无图像生物特征模板）。	`"session"`
`vendor_data`	string	是	匹配会话的 `vendor_data`，对于 `imported` 和 `retained_template` 匹配则为关联用户的该数据。	`"user-12345"`
`vendor_user_id`	string (UUID)	是	关联的用户。对于 `list_entry` 匹配以及没有关联用户的会话为 `null`。	`"2f7c1a9e-…"`
`biometric_template_id`	string (UUID)	是	匹配的保留模板。仅对 `retained_template` 匹配设置；可用于 `GET`/`DELETE /v3/biometric-templates/{id}/`。	`null`
`verification_date`	string (ISO 8601)	是	捕获匹配人脸的时间，或保留 `retained_template` 的时间；对于 `list_entry` 匹配为 `null`。	`"2024-11-04T09:14:02Z"`
`user_details`	object	是	匹配会话的证件验证提取出的 `{ 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`	string (URL)	是	匹配用户的参考人脸 — 当 `save_api_request=true` 时为预签名 URL，否则为原始存储路径。对于不包含图像的 `retained_template` 匹配始终为 `null`。	`"https://<media-host>/.../matched.jpg?..."`
`status`	string	是	匹配会话的验证状态（参见状态枚举）；对于非会话匹配为 `null`。	`"Approved"`
`is_blocklisted`	boolean	否	匹配的人脸是否位于您的人脸黑名单中。对于 `retained_template` 匹配始终为 `false`；被列入黑名单的人脸会单独报告为 `list_entry` 匹配。	`false`
`is_allowlisted`	boolean	否	匹配的人脸是否位于您的某个白名单中。	`false`
`api_service`	string (enum)	是	匹配会话的大写独立 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 会话的 GET /v3/session/{sessionId}/decision/ 中均显示为 aml_screenings[]。源码：aml/serializers/aml.py:63-85（AMLV3Serializer，继承位于 aml/serializers/aml.py:28-60 的 AMLV2Serializer）。

字段	类型	可为 null	描述	示例
`status`	string	否	参见状态枚举。	`"Approved"`
`total_hits`	integer	否	筛查命中数量（始终存在，默认值为 `0`）。	`2`
`entity_type`	string (enum)	是	`person` 或 `company`（`EntityTypeChoices`，`common/config/choices.py:675-677`）。	`"person"`
`hits`	array of objects	否	每个命中项对应一个条目。关键字段：`id`、`caption`、`match`（布尔值）、`target`（布尔值 \| null — 实体是否为该名单条目的直接目标）、`match_score`（float 0-100 身份置信度）、`risk_score`（float 0-100 实体风险）、`score`（已废弃的 0-1 float）、`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 会话中均作为 ip_analyses[] 出现在 GET /v3/session/{sessionId}/decision/ 中。来源：kyc/serializers/location.py:196-243（IPAnalysisSerializerV3）。

字段	类型	可为空	描述	示例
`status`	string	否	参见状态枚举。	`"Approved"`
`node_id`	string \| null	是	工作流节点标识符（V3）。	`"first_ip_analysis"`
`device_brand`	string	是	从用户代理解析出的设备品牌。	`"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 }`。地址证明（POA）中的地址（已进行地理编码）。	`{ "location": { "latitude": 40.4170, "longitude": -3.7040 }, "distance_from_ip": 1.1, "distance_from_id_document": 4.0 }`
`matches`	array of objects	否	跨会话 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`）。上限为 5 个 IP + 5 个设备匹配。	`[]`
`warnings`	array	否	参见警告对象。	`[]`
`browser_version`, `os_version`	string	是	来自用户代理的浏览器和操作系统版本。	`"17.4"`
`user_agent`, `accept_language`	string	是	浏览器发送的用户代理字符串和 `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`	string	否	参见状态枚举。	`"Declined"`
`outcome`	string	是	本次尝试的结果：`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`	string	是	系统授予的权限：`granted_precise`、`granted_approximate`、`denied`、`restricted`、`unavailable`、`timeout`、`dismissed` 或 `not_requested`。	`"granted_precise"`
`latitude`, `longitude`	float	是	WGS84 坐标。无定位时为 `null`。	`48.8566`
`accuracy_m`	float	是	不确定性半径（以米为单位）。	`35.0`
`accuracy_confidence`	string	是	`p95`、`p68` 或 `unspecified`。	`"p95"`
`measured_at`, `age_seconds`	datetime, integer	是	设备获取定位的时间，以及到 Didit 接收时经过的秒数。	`2`
`source`, `platform`, `sdk_version`	string	是	定位来源、生成定位的客户端及其 SDK 版本。	`"browser"`
`is_mock`, `produced_by_accessory`	boolean	是	平台报告的欺骗攻击证据。`null` 表示未报告。	`null`
`integrity`	string	否	`attested`、`not_attested`、`failed`、`unsupported`（Web）或 `not_determined`。	`"unsupported"`
`country_code`, `region_code`, `city`	string	是	定位解析出的地点。	`"FR"`
`geofence`, `inside_geofence`, `geofence_basis`, `inside_areas`, `blocked_areas`	object, boolean, string, arrays	是	国家/地区及区域结果。	`{ "enabled": true, "result": "outside" }`
`position_source`, `anonymizers`	string, object	是	该步骤获取位置的来源，以及 VPN、代理、Tor、欺骗攻击和模拟器信号。	`"device_and_ip"`
`ip_distance_km`, `ip_distance_uncertainty_km`, `ip_consistent`, `document_distance_km`, `travel_excused`, `consecutive_mismatches`	number, boolean, integer	是	与 IP 位置和存档地址的比对结果。	`12.4`
`attempts`	integer	否	该步骤内此次尝试的编号。	`3`
`consent`	object	是	用户接受的通知的 `accepted_at`、`version` 和 `locale`。
`warnings`	警告对象数组	否	该步骤的 `LOCATION_*` 警告。在添加了 `received_at` 和 `created_at` 的 `geolocation_attempts[]` 中不存在。	`[]`

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

地址证明

按提交的每个地址证件返回。在 GET /v3/session/{sessionId}/decision/ 中显示为 poa_verifications[]。来源：poa/serializers/poa.py:212-227（POAV3Serializer，继承位于 poa/serializers/poa.py:173-209 的 POAV2Serializer）。

字段	类型	可为空	描述	示例
`status`	string	否	参见状态枚举。	`"Approved"`
`issuing_state`	string (ISO 3166-1 alpha-3)	是	证件签发机构的国家/地区代码。	`"ESP"`
`document_type`	string	否	来自 `PoaDocumentTypeChoices`（`common/config/choices.py:868-873`）的高级别类型：`UTILITY_BILL`、`BANK_STATEMENT`、`GOVERNMENT_ISSUED_DOCUMENT`、`OTHER_POA_DOCUMENT`。默认回退至 `UNKNOWN`，永不为 `null`。	`"UTILITY_BILL"`
`document_subtype`	string	否	来自 `PoaDocumentSubtypeChoices` 的子类型代码（例如 `ELECTRICITY_BILL`、`WATER_BILL`、`ACCOUNT_STATEMENT`）。默认回退至 `UNKNOWN`，永不为 `null`。	`"ELECTRICITY_BILL"`
`issuer`	string	是	签发机构名称。	`"Iberdrola"`
`issue_date`	string (YYYY-MM-DD)	是	证件签发日期。	`"2026-04-15"`
`expiration_date`	string (YYYY-MM-DD)	是	证件上印刷的到期日期（如存在）。	`null`
`poa_address`	string	是	OCR 提取的原始地址。	`"Calle Mayor 1, 28001 Madrid"`
`poa_formatted_address`	string	是	地理编码/格式化后的地址。	`"Calle Mayor 1, 28001 Madrid, Spain"`
`poa_parsed_address`	object	是	结构化地址（`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`	string (URL)	是	上传证件的预签名 URL。	`"https://<media-host>/.../poa.pdf?..."`
`document_language`	string	是	检测到的证件语言（ISO 639-1）。	`"es"`
`document_metadata`	object	是	过滤后的元数据：`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`	object	否	银行账户字段（`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`	string	是	地址证明上显示的姓名。	`"María García López"`
`expected_details_address`	string	是	客户在注册时填写的原样地址。	`"Calle Mayor 1, Madrid"`
`expected_details_formatted_address`	string	是	地理编码后的预期地址。	`"Calle Mayor 1, 28001 Madrid, Spain"`
`expected_details_parsed_address`	object	是	结构化的预期地址。	`{ "city": "Madrid", "postal_code": "28001" }`
`name_match_score_expected_details`	float (0-100)	是	`name_on_document` 与创建会话时提供的姓名之间的模糊匹配度。	`94.0`
`name_match_score_id_verification`	float (0-100)	是	`name_on_document` 与验证通过的身份证件 `full_name` 之间的模糊匹配度。	`100.0`
`extra_files`	array of strings (URL)	否	其他已上传文件的预签名 URL。	`[]`
`detected_codes`	array of objects	否	在证件每个已处理页面上检测到的二维码和条形码：`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`	string \| null	是	工作流节点标识符（V3）。	`"first_poa"`
`warnings`	array	否	参见警告对象。	`[]`

{
  "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`	string	否	参见状态枚举。	`"Approved"`
`phone_number_prefix`	string	否	E.164 国家/地区前缀（带 `+`）。	`"+34"`
`phone_number`	string	否	不带前缀的用户号码。	`"612345678"`
`full_number`	string	否	完整的 E.164 号码（`phone_number_prefix + phone_number`）。	`"+34612345678"`
`country_code`	string (ISO 3166-1 alpha-2)	是	号码所属国家/地区。	`"ES"`
`country_name`	string	是	本地化的国家/地区名称。	`"Spain"`
`carrier`	object	否	`{ 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`	boolean	否	当运营商将该号码标记为临时/一次性号码时为 `true`。	`false`
`is_virtual`	boolean	否	当 `carrier.type` 为 `voip`、`isp`、`vpn` 之一时为 `true`。	`false`
`verification_method`	string	否	用于投递 OTP 的渠道（`whatsapp`、`sms`……）。读取自最后一次发送尝试的 `actual_channel`（回退至请求的 `channel`，然后回退至 `sms`）。	`"whatsapp"`
`verification_attempts`	integer	否	OTP 发送尝试总次数（初次发送加上重发）。	`1`
`verified_at`	string (ISO 8601)	是	成功输入 OTP 的时间戳。	`"2026-05-17T10:14:02Z"`
`lifecycle`	array of objects	否	按时间顺序排列的事件：发送尝试、投递回调、代码校验以及最终状态事件。每个事件为 `{ type, timestamp, details, fee }`。事件类型来自 `PhoneEventChoices`。	`[…]`
`matches`	array of objects	否	跨会话电话号码匹配项。每个条目包含：`{ session_id, session_number, vendor_data, verification_date, phone_number, status, is_blocklisted, api_service, source }`。`source` 为 `session` 或 `list_entry`。	`[]`
`node_id`	string \| null	是	工作流节点标识符（V3）。	`"first_phone"`
`warnings`	array	否	参见警告对象。	`[]`
`phone_intelligence`	object	是	电话情报信号。仅在为该号码运行了情报附加组件时存在。
`phone_social`	object	是	该号码的社交足迹。仅在运行了社交足迹附加组件时存在。

{
  "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`	string	否	参见状态枚举。	`"Approved"`
`email`	string	否	提交的邮箱地址。	`"maria.garcia@example.com"`
`is_breached`	boolean	否	当该邮箱出现在已知数据泄露事件中时为 `true`。	`false`
`breaches`	array of objects	否	当 `is_breached` 为 `true` 时的单次泄露详情：`{ name, domain, logo_path, breach_date, description, is_verified, data_classes, breach_emails_count }`。	`[]`
`is_disposable`	boolean	否	当该邮箱属于一次性邮箱提供商时为 `true`。	`false`
`is_undeliverable`	boolean	否	当 SMTP 投递探测显示该收件箱不接收邮件时为 `true`。	`false`
`verification_attempts`	integer	否	OTP 校验尝试总次数。	`1`
`verified_at`	string (ISO 8601)	是	成功输入 OTP 的时间戳。	`"2026-05-17T10:15:22Z"`
`lifecycle`	array of objects	否	按时间顺序排列的事件：发送尝试、代码校验以及最终状态事件。每个事件为 `{ type, timestamp, details, fee }`。事件类型来自 `EmailEventChoices`。	`[…]`
`matches`	array of objects	否	跨会话邮箱匹配项。每个条目包含：`{ session_id, session_number, vendor_data, verification_date, email, status, is_blocklisted, api_service, source }`。`source` 为 `session` 或 `list_entry`。	`[]`
`node_id`	string \| null	是	工作流节点标识符（V3）。	`"first_email"`
`warnings`	array	否	参见警告对象。	`[]`
`email_intelligence`	object	是	邮箱情报信号。仅在为该地址运行了情报附加组件时存在。
`email_social`	object	是	该地址的社交足迹。仅在运行了社交足迹附加组件时存在。

{
  "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`	string (ISO 3166-1 alpha-3)	是	查询的登记机构所属国家/地区。	`"ESP"`
`validation_type`	string (enum)	否	结果的证实方式：`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`	object	否	提交给登记机构的数据。文件字段（`selfie`、`cnh_qr_code_image`、`document_image`）在读取时生成预签名 URL。	`{ "document_number": "99999999R", "date_of_birth": "1990-05-12" }`
`validations`	array of objects	否	产生匹配的每个目录服务对应一项条目。每个条目可包含 `service_id`、`service_name`、`validation`（提供商判定对象）、`outcome_code`、`outcome_detail` 和 `source_data`（清洗后的公民档案：`full_name`、`gender`、`date_of_birth`、`photo`（预签名 URL）、`signature`（预签名 URL）等）。	`[…]`
`errors`	array of objects	是	查询失败时的各服务错误；为空时该键会被完全省略。每个条目是上游服务的错误对象加上生成该错误对象的 `service_id`。	`[]`
`match_type`	string (enum)	是	所查询服务之间的综合匹配判定：`full_match`、`partial_match` 或 `no_match`（`DatabaseValidationMatchTypeChoices`，`common/config/choices.py:1103-1106`）。评估前为 `null`。	`"full_match"`
`status`	string	否	参见状态枚举。	`"Approved"`
`node_id`	string \| null	是	工作流节点标识符 (V3)。	`"first_db_validation"`
`warnings`	array	否	参见警告对象。	`[]`

{
  "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`	string (UUID)	否	所作答的问卷版本标识符。	`"6a0f1c2c-…"`
`title`	string	否	在控制台中设置的问卷名称。	`"Customer risk profile"`
`description`	string	是	问卷描述。	`"Short risk-profile questions."`
`languages`	array of strings	否	问卷发布的语言代码。	`["en", "es"]`
`default_language`	string	否	回退语言代码。	`"en"`
`is_active`	boolean	否	此问卷版本是否处于活跃状态。	`true`
`is_simple_questionnaire`	boolean	否	当问卷没有分支逻辑（扁平列表）时为 `true`。	`true`
`questionnaire_group_id`	string (UUID)	否	同一问卷的不同版本之间共享的标识符。	`"a7c2c2c2-…"`
`version`	integer	否	活跃模板的版本号。	`3`
`status`	string	否	`Approved`、`In Review`、`Not Finished` 之一（问卷级别的拒绝会映射到 `In Review`）。	`"Approved"`
`published_at`	string (ISO 8601)	是	模板的发布时间。	`"2026-01-12T11:00:00Z"`
`sections`	array of objects	否	应用图谱遍历和可见性过滤后的有序章节。每个章节为 `{ title, description, items[] }`（标题/描述来自起始的 `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`	string \| 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`	string (UUID)	否	签署人的签名。在证据和验证路由中用作 `signature_id`。	`"0e6c2a8e-…"`
`node_id`	string	否	工作流节点标识符。	`"feature_signature"`
`status`	string	否	签署阶段：`intro`、`review`、`code`、`signing`、`signed` 或 `declined`。仅 `signed` 表示文件已签署。	`"signed"`
`verdict`	string	否	`Not Finished`、`Approved`、`In Review` 或 `Declined`。	`"Approved"`
`level`	string	否	`simple`（默认）或 `aes`。`qes` 为附加组件，目前暂不可用。	`"aes"`
`format`	string	否	Simple 签名对应 `pdf`，高级签名 (AES) 对应 `pades`。	`"pades"`
`profile`	string	是	高级 (AES) 签名签署完成后为 `PAdES-B-LT`，否则为 null。	`"PAdES-B-LT"`
`signer`	object	否	`{ name, capacity, company, role, roles, identity_session_id }`。`capacity` 可以是 `self` (KYC) 或 `company` (KYB)。	`{ "name": "Jane Doe", "capacity": "self", … }`
`identity_used`	object	否	`{ session_id, kyc_id, verified, expected_name }`：签名所依赖的已核验身份。对于无已核验身份的 Simple 签名，该项为空。	`{ "verified": true, … }`
`certificate`	object	是	`{ issuer, issued_to, serial, valid_from, valid_until }`。签署完成前为 `null`，且 Simple 签名始终为 `null`。	`{ "serial": "5A3F9C21", … }`
`confirmation`	object	No	`{ channel, destination, confirmed_at, attempts }`。`destination` 已脱敏；`attempts` 统计输入的验证码次数，包含正确的一次。简易签名无需验证码，因此 `channel` 和 `destination` 为 `null`。	`{ "channel": "email", … }`
`timestamp`	object	Yes	`{ time, qualified, valid }`。对于 AES，`qualified` 始终为 `false`。签名完成前为 `null`，简易签名始终为 `null`。	`{ "qualified": false, … }`
`documents`	array of objects	No	`{ id, uuid, title, 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[].fields`	array of objects	No	证件上每个字段的 `{ 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`	object	Yes	`{ method, font, adopted_at }`：签署人采用的签名和姓名首字母。`method` 为 `typed` 或 `drawn`；`font` 为键入签名的手写样式。采用前为 `null`。	`{ "method": "drawn", … }`
`electronic_signature_consent_at`	string (ISO 8601)	Yes	签署人同意以电子方式签署证件的时间。当任一证件包含字段时设置。	`"2026-11-03T10:41:40Z"`
`evidence_file`	string	Yes	签署完成后证据 PDF 的路径。	`"/v3/session/…/evidence/?signature_id=…"`
`warnings`	array of objects	No	`{ code, node_id }`，其中 `code` 为 `SIGNATURE_DECLINED`、`SIGNATURE_OTP_FAILED`、`SIGNATURE_NAME_MISMATCH`、`SIGNATURE_IDENTITY_NOT_VERIFIED`、`SIGNATURE_DOCUMENT_CHANGED` 之一。	`[]`
`validation`	object	Yes	`{ valid, checked_at, documents[] }`：对已签署证件的最新密码学检查。签名完成前为 `null`。当无法确认签名结果时为 `{ valid: null, reason: "signature_provider_outcome_unknown", checked_at }`。	`{ "valid": true, … }`
`declined_at`	string (ISO 8601)	Yes	签署人拒绝的时间。	`null`
`declined_action`	string	No	该步骤的 `signature_declined_action`。	`"REVIEW"`
`signed_at`	string (ISO 8601)	Yes	证件签署完成的时间。	`"2026-11-03T10:42:24Z"`
`expires_at`	string (ISO 8601)	No	签名链接失效的时间。	`"2026-11-10T10:30:00Z"`
`email_sent_at`	string (ISO 8601)	Yes	通过邮件向签署人发送已签署副本的时间。	`"2026-11-03T10:42:30Z"`
`email_unavailable_reason`	string	Yes	当请求了邮件副本但未发送的原因。	`null`
`ip_address`	string	Yes	签署人索取验证码时的地址。	`"203.0.113.10"`
`place`	string	Yes	未采集：始终为 `null`。	`null`
`place_unavailable_reason`	string	Yes	`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。

字段	类型	可为 null	描述	示例
`request_id`	string (UUID)	No	当 `save_api_request=true`（默认值）时为持久化的会话 ID；否则为临时的关联 UUID。	`"3b1f1e2c-…"`
`age_estimation`	object	No	结果外层对象：`status`（`Approved` / `Declined`）、`method`（始终为 `PASSIVE`）、`score`（活体得分 0-100，可为 null）、`age_estimation`（最大人脸的预测年龄（岁），可为 null）、`user_image`（包含每个人脸 `age`、`bbox` `[x_min, y_min, x_max, y_max]`、`confidence`、`gender` 的 `entities[]`；外加 `best_angle`）、`warnings[]`。	`{ … }`
`vendor_data`	string	Yes	请求中回传的 `vendor_data`。	`null`
`metadata`	object	Yes	请求中回传的 `metadata`。	`null`
`created_at`	string (ISO 8601)	No	服务端请求时间戳。	`"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）。

字段	类型	可为 null	描述	示例
`liveness_checks`	array of 活体检测	No	认证尝试的活体检测结果。	`[ { "status": "Approved", … } ]`
`face_matches`	array of 人脸比对	No	与已登记参考图像的比对结果。`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`	string	否	顶层会话状态（参见状态枚举）。	`"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 公司登记

在 KYB 工作流中针对每个经公司登记确认的公司返回。在用于企业会话的 GET /v3/session/{sessionId}/decision/ 中显示为 registry_checks[]。来源：kyb/serializers/kyb.py:939-964（RegistryCheckV3Serializer）。

字段	类型	可为空	描述	示例
`status`	string	否	参见状态枚举。	`"Approved"`
`node_id`	string \| null	是	工作流节点标识符（V3）。	`"first_registry"`
`data_resolved`	boolean	否	当公司登记数据获取已完成（或 `is_from_registry` 为 `false`，表示数据为手动输入）时为 `true`。	`true`
`company`	object	否	完整公司 payload — 参见下文的公司对象。	`{ … }`
`ownership_structure`	object	是	公司登记证明的股权结构表：`shareholders[]` 和 `beneficial_owners[]`，每个所有者包含其登记身份、持股比例和规范的 `shareholding`。	`{ "shareholders": [...], "beneficial_owners": [] }`
`warnings`	array	否	参见警告对象。	`[]`

公司对象

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

字段	类型	可为空	描述
`uuid`	string (UUID)	否	内部公司标识符。
`node_id`	string \| null	是	工作流节点标识符。
`status`	string	否	功能状态（`FeatureStatusChoices`）。
`registry_status`	string	是	来自公司登记的公司状态（`active`、`dissolved` 等）。
`data_resolved`	boolean	否	与父对象上的定义相同。
`company_name`	string	是	注册公司名称。
`registration_number`	string	是	注册号。
`country_code`	string (ISO 3166-1 alpha-2)	是	注册成立国家/地区。
`region`	string	是	适用的 ISO 3166-2 行政区划（例如 `US-CA`）。
`company_type`	string	是	法律组织形式（`LLC`、`SL` 等）。
`incorporation_date`	string (YYYY-MM-DD)	是	注册成立日期。
`registered_address`	string	是	注册法定地址。
`tax_number`	string	是	税号 / 增值税标识符。
`risk_level`	string	是	提供商给出的风险评级。
`verification_status`	string	是	内部验证状态枚举。
`is_from_registry`	boolean	否	当来源于公司登记（相对于手动输入）时为 `true`。
`fetch_status`	string	是	`pending`、`resolved`、`failed`。
`alternative_names`	string	是	逗号分隔的其他商用名称。
`nature_of_business`	string	是	自由文本格式的商业活动描述。
`registered_capital`	string	是	人类可读字符串格式的注册资本。
`registered_capital_amount`	string (decimal)	是	解析后的注册资本金额。
`registered_capital_currency`	string (ISO 4217)	是	货币代码。
`website`	string (URL)	是	公司网站。
`email`	string	是	公开联系邮箱。
`phone`	string	是	公开联系电话。
`legal_entity_identifier`	string	是	法人机构识别码（LEI，如可用）。
`location_of_registration`	string	是	登记机关 / 地区。
`vat_number`	string	是	为公司提交的增值税号。
`vat_validation_status`	string	否	验证增值税号或 `tax_number`（当没有增值税号时）的结果：`valid`、`invalid`、`format_valid`、`invalid_format`、`could_not_validate` 或 `not_applicable`。参见增值税号与税号核验。
`vat_validated_number`	string	是	数据源所记录的经过核验的号码。
`vat_validation_source`	string	是	判定该状态的数据源：`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`	string	是	在数据源登记的名称（当数据源未披露时为空）。
`vat_validated_address`	string	是	在数据源登记的地址（未披露时为空）。
`vat_checked_at`	string (ISO 8601)	是	核验的时间戳；未运行核验时为 `null`。
`financial_summary`	object	是	公司登记提供的最新财务摘要快照（如提供）。
`officers`	array of objects	否	适用于 B2C 的管理人员列表：`{ uuid, name, designation, role, nationality, is_active, kyc_status, kyc_session_url }`。
`beneficial_owners`	array of objects	否	适用于 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`	array of objects	是	来自公司登记的各地址详情。
`industries`	array of objects	是	SIC/NAICS 风格的行业分类。
`accounts`	array of objects	是	已提交账目元数据。
`registry_data`	object	是	Didit 归一化的登记详情（股权结果、控制台修正、没有独立字段的登记事实）。非稳定契约。
`user_provided_data`	object	是	用户编辑字段的快照。
`confirmed_by_user_at`	string (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`。参见 Status 枚举。	`"Approved"`
`node_id`	string \| null	是	工作流节点标识符（V3）。	`"first_kyb_documents"`
`items`	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`	字符串数组	否	工作流配置所要求的证件分组。	`["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	否	参见 Status 枚举。	`"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	是	已关联 KYC 的活跃实际受益人汇总计数：`{ total, approved, flagged, pending }`。当没有活跃实际受益人关联 KYC 时为 `null`。	`{ "total": 2, "approved": 2, "flagged": 0, "pending": 0 }`
`warnings`	array	否	参见警告对象。	`[]`

{
  "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 状态，会话也可以得出其总体决策。

​概述

​常见字段

​警告对象

​报告对象

​身份证件验证

​NFC 验证

​活体检测

​人脸比对

​人脸搜索

​人脸搜索匹配对象

​AML 筛查

​IP 分析

​位置验证

​地址证明

​电话验证

​邮箱验证

​数据库核验

​问卷响应

​电子签名

​年龄估算

​生物识别认证

​KYB 公司登记

​公司对象

​KYB 证件

​KYB 证件项对象

​KYB 关键人员

​决策层级字段

​生物识别同意

​状态枚举参考

​功能级状态

​会话级状态

概述

常见字段

警告对象

报告对象

身份证件验证

NFC 验证

活体检测

人脸比对

人脸搜索

人脸搜索匹配对象

AML 筛查

IP 分析

位置验证

地址证明

电话验证

邮箱验证

数据库核验

问卷响应

电子签名

年龄估算

生物识别认证

KYB 公司登记

公司对象

KYB 证件

KYB 证件项对象

KYB 关键人员

决策层级字段

生物识别同意

状态枚举参考

功能级状态

会话级状态