问卷报告：回答 JSON Schema

问卷报告包含向用户展示的结构化表单、他们在条件分支中实际经过的路径，以及每个可见项目的答案。报告按节点返回，因此多实例工作流（例如每位 UBO 一份问卷）对每次出现都会包含一个条目。

概览

每个问卷响应都描述了：

用户看到的问卷版本（标题、描述、语言、版本元数据、分节）。
用户在表单图谱中实际走过的路径所对应的可见项目（被条件逻辑隐藏的项目会从响应中剔除）。
每个可见交互项目的答案，其数据结构与自身的 element_type 相匹配。
整个响应所对应的单一状态。

布局元素会被重塑而非作为答案回答：每个 SECTION_HEADER 会成为一个分节边界（其标题和描述会成为该分节的 title/description），而 HEADING、PARAGRAPH 和 SEPARATOR 则保留在 items[] 中且不包含 answer 键，从而使报告保持用户看到的相同视觉结构。

出现位置

只要运行了问卷功能，无论是 KYC 还是 KYB 会话，问卷报告都会以复数数组 questionnaire_responses[] 的形式出现在 GET /v3/session/{sessionId}/decision/ 中。在至少有一个问卷实例启动之前，该字段的值为 null。每个条目都带有一个 node_id，以便多实例工作流可以明确区分是由哪个图谱步骤生成的。

GET /v3/session/{sessionId}/decision/
  ──▶ { "questionnaire_responses": [ { node_id, questionnaire_id, title, status, sections, … }, … ] }

项目结构

有关规范模式，请参阅数据模型参考中的问卷响应。

interface QuestionnaireResponse {
  questionnaire_id: string;          // UUID of the questionnaire version that was answered
  title: string;                     // Questionnaire name, as set in the Console
  description: string | null;
  languages: string[];               // Supported language codes
  default_language: string;          // Default language code
  is_active: boolean;
  is_simple_questionnaire: boolean;  // true = flat list, false = branching graph
  questionnaire_group_id: string;    // UUID shared by all versions of the same questionnaire
  version: number;                   // Version number within the group
  published_at: string | null;       // ISO 8601 — when this version was published
  status: "Approved" | "In Review" | "Not Finished";
  sections: Array<{
    title: string | null;            // From the SECTION_HEADER that opens the section
    description: string | null;
    items: QuestionnaireItem[];
  }>;
  node_id: string | null;            // Workflow graph node that ran this questionnaire
}

interface QuestionnaireItem {
  uuid: string;                      // Form element UUID
  value: string;                     // Stable node id of the element within the questionnaire graph
  element_type:
    | "SHORT_TEXT" | "LONG_TEXT"
    | "DROPDOWN" | "SINGLE_CHOICE" | "MULTIPLE_CHOICE"
    | "NUMBER" | "EMAIL" | "PHONE" | "ADDRESS" | "COUNTRY"
    | "DATE_PICKER" | "TIME"
    | "CONSENT"
    | "FILE_UPLOAD" | "IMAGE"
    | "REPEATABLE_GROUP"
    | "HEADING" | "PARAGRAPH" | "SEPARATOR";   // layout-only — no answer key
  is_required: boolean;
  title: string | null;              // Localized
  description: string | null;        // Localized help text, or null when none is set
  placeholder: string | null;        // Localized
  choices: Array<{                   // DROPDOWN / SINGLE_CHOICE / MULTIPLE_CHOICE
    label: string;                   // Localized
    value: string;                   // Stable across languages
    requires_text_input?: boolean;   // Selecting this option triggers a free-text follow-up
  }> | null;
  max_files: number | null;          // FILE_UPLOAD / IMAGE upload cap (1–5)
  required_if: {                     // Conditional requirement rule, or null
    rules: Array<{ field: string; operator: string; value?: unknown }>;
    logic: "and" | "or";
  } | null;
  repeatable_config: {               // REPEATABLE_GROUP only, or null
    min_items?: number;
    max_items?: number;
    item_label?: string;             // Localized
    fields: Array<object>;           // Sub-field definitions (value, element_type, title, …)
  } | null;
  answer?: Answer | null;            // Omitted on HEADING / PARAGRAPH / SEPARATOR; null when unanswered
}

SECTION_HEADER 元素绝不会出现在 items[] 中：它们用于开启一个新分节并提供该分节的 title 和 description。

元素类型

元素类型	答案结构	说明
`SHORT_TEXT`、`LONG_TEXT`	`{ value: string }`	自由文本。
`EMAIL`、`DATE_PICKER`、`TIME`	`{ value: string }`	类型化文本变体。
`NUMBER`	`{ value: number }`	JSON 数字，在服务端校验为数值。
`COUNTRY`	`{ value: string }`	ISO 3166-1 alpha-3 代码（例如 `"ESP"`），在服务端校验。
`PHONE`	`{ value: { countryCode, callingCode, number } }`	结构化电话对象。
`ADDRESS`	`{ value: { street, streetExtraInfo, city, state, postalCode, country } }`	结构化地址对象。
`DROPDOWN`、`SINGLE_CHOICE`	`{ value: string, text?: string }`	`value` 为选项值；当所选选项包含 `requires_text_input: true` 时，会填充 `text`。
`MULTIPLE_CHOICE`	`{ value: string[], text?: string }`	选项值数组。
`CONSENT`	`{ value: boolean }`	JSON 布尔值。
`FILE_UPLOAD`、`IMAGE`	`{ files: string[] }`	每个条目都是一个预签名 URL。
`REPEATABLE_GROUP`	`{ items: Array<{ [fieldValue]: Answer }> }`	每次重复对应一个对象，以各子字段的 `value` 为键，并包含各自的答案对象。
`HEADING`、`PARAGRAPH`、`SEPARATOR`	（无 `answer` 键）	纯布局元素，保留在 `items[]` 中以维持结构。

用户从未回答过的可见交互项目将以 "answer": null 返回。

条件可见性

当问卷定义了图谱（条件逻辑）时，仅会包含用户实际走过路径上的项目。被用户未选择的分支所隐藏的项目不会出现在 sections[].items 中，即使模板中存在该项目也是如此。没有任何可见项目的分节将被完全剔除。

状态值

响应级别的 status 为以下三个值之一。在系统内部，基础状态（Approved，或者当工作流强制进行人工审核时为 In Review）会按照全平台通用的优先级规则 Declined > In Review > Approved 与任何匹配的自定义状态规则合并；问卷级别的 Declined 结果随后会被映射为 In Review，以便审核员在人工审核期间做出最终处置。

状态	含义
`Not Finished`	用户尚未提交问卷。
`In Review`	已提交并等待人工审核（工作流强制进行人工审核，或状态规则对响应进行了升级）。
`Approved`	已提交并通过。

警告

问卷会发出单一警告代码，该代码在问卷节点上配置的自定义状态规则与答案匹配时生成：

标签	描述
`CUSTOM_STATUS_RULE_TRIGGERED`	工作流状态规则评估了问卷答案并更改（或确认）了功能状态。

该警告的 additional_data 包含 field、operator、rule_value、actual_value、target_status，以及在规则定义了分值时的 score。其 log_type 遵循规则的目标状态：Declined 为 error，In Review 为 warning，其他情况为 information。与其他功能不同，问卷条目不包含嵌入的 warnings[] 数组；触发规则的日志会记录在会话的 feature: "QUESTIONNAIRE" 下，并显示在 Console 审核界面中（另请参阅企业验证（KYB）警告列表；相同代码也适用于 KYC 会话）。

示例 — 资金来源问卷

{
  "questionnaire_responses": [
    {
      "questionnaire_id": "9f7485e0-b00b-4d56-9d3e-7859b68d1213",
      "title": "Source of Funds",
      "description": "Reply to this questionnaire to help us understand the source of funds.",
      "languages": ["en"],
      "default_language": "en",
      "is_active": true,
      "is_simple_questionnaire": true,
      "questionnaire_group_id": "2b6a9d40-13a8-4b1e-9a6c-3f1d2e4b5a60",
      "version": 1,
      "published_at": "2025-11-02T09:14:55.000000Z",
      "status": "Approved",
      "sections": [
        {
          "title": null,
          "description": null,
          "items": [
            {
              "uuid": "618636d9-7d5c-41ce-b8d0-1ab2a4be20db",
              "value": "question_1",
              "element_type": "DROPDOWN",
              "is_required": true,
              "title": "What is your primary source of funds?",
              "description": null,
              "placeholder": null,
              "choices": [
                { "label": "Salary", "value": "salary" },
                { "label": "Business Income", "value": "business_income" },
                { "label": "Savings", "value": "savings" },
                { "label": "Investments", "value": "investments" },
                { "label": "Inheritance/Gift", "value": "inheritance_gift" },
                { "label": "Other", "value": "other", "requires_text_input": true }
              ],
              "max_files": 1,
              "required_if": null,
              "repeatable_config": null,
              "answer": { "value": "salary" }
            },
            {
              "uuid": "2d16b527-72be-42e0-8e96-b164b818386c",
              "value": "question_2",
              "element_type": "LONG_TEXT",
              "is_required": true,
              "title": "Provide details of the primary source.",
              "description": null,
              "placeholder": null,
              "choices": null,
              "max_files": 1,
              "required_if": null,
              "repeatable_config": null,
              "answer": { "value": "Software engineer at Acme Ltd since 2018." }
            },
            {
              "uuid": "1bf8a2a3-14ee-48a8-bb3d-175481aae4aa",
              "value": "question_3",
              "element_type": "SINGLE_CHOICE",
              "is_required": true,
              "title": "Will any funds originate from third parties?",
              "description": null,
              "placeholder": null,
              "choices": [
                { "label": "Yes", "value": "yes", "requires_text_input": true },
                { "label": "No", "value": "no" }
              ],
              "max_files": 1,
              "required_if": null,
              "repeatable_config": null,
              "answer": { "value": "yes", "text": "One-off gift from parents, EUR 8,000." }
            },
            {
              "uuid": "a90a073d-e098-404c-bbce-5130d8b12a13",
              "value": "question_4",
              "element_type": "FILE_UPLOAD",
              "is_required": true,
              "title": "Upload a proof of funds document",
              "description": null,
              "placeholder": null,
              "choices": null,
              "max_files": 3,
              "required_if": null,
              "repeatable_config": null,
              "answer": {
                "files": [
                  "https://<media-host>/.../payslip-jul.pdf",
                  "https://<media-host>/.../payslip-aug.pdf"
                ]
              }
            }
          ]
        }
      ],
      "node_id": "feature_questionnaire"
    }
  ]
}

示例 — 未完成

{
  "questionnaire_responses": [
    {
      "questionnaire_id": "9f7485e0-b00b-4d56-9d3e-7859b68d1213",
      "title": "Source of Funds",
      "description": "Reply to this questionnaire to help us understand the source of funds.",
      "languages": ["en"],
      "default_language": "en",
      "is_active": true,
      "is_simple_questionnaire": true,
      "questionnaire_group_id": "2b6a9d40-13a8-4b1e-9a6c-3f1d2e4b5a60",
      "version": 1,
      "published_at": "2025-11-02T09:14:55.000000Z",
      "status": "Not Finished",
      "sections": [
        {
          "title": null,
          "description": null,
          "items": [
            {
              "uuid": "618636d9-7d5c-41ce-b8d0-1ab2a4be20db",
              "value": "question_1",
              "element_type": "DROPDOWN",
              "is_required": true,
              "title": "What is your primary source of funds?",
              "description": null,
              "placeholder": null,
              "choices": [
                { "label": "Salary", "value": "salary" },
                { "label": "Other", "value": "other", "requires_text_input": true }
              ],
              "max_files": 1,
              "required_if": null,
              "repeatable_config": null,
              "answer": null
            }
          ]
        }
      ],
      "node_id": "feature_questionnaire"
    }
  ]
}

当用户已到达问卷步骤但尚未提交答案时，返回的响应中 status: "Not Finished"，且每个可见项目上的 "answer": null。从未到达该步骤的会话则完全不会生成任何条目：不存在实例时，questionnaire_responses 保持为 null。

Notes

文件 URL 会过期。 answer.files 中的条目是预签名 URL（默认有效期为 4 小时）。当您需要全新的 URL 时，请重新调用决策 endpoint。
本地化。 当问卷支持英语时，项目的 title、description、placeholder，选项的 label 以及小节的 title/description 将以英语返回，否则以问卷的 default_language 返回。选项的 value 在所有语言中保持不变，因此您可以安全地将其用作业务逻辑的键。
项目的 description 是元素的帮助文本。 任何项目都可以包含该帮助文本（包括问题），未设置时为 null。SEPARATOR 绝不会包含此字段。

问卷概述

如何构建、版本控制问卷并将其附加到工作流。

数据模型 — 问卷响应

此对象的规范字段级架构。

检索会话

V3 决策 payload 的 endpoint 参考。

身份认证

验证

监控

平台

问卷报告：回答 JSON Schema

概览

出现位置

项目结构

元素类型

条件可见性

状态值

警告

示例 — 资金来源问卷

示例 — 未完成

Notes

相关内容

问卷概述

数据模型 — 问卷响应

检索会话

​概览

​出现位置

​项目结构

​元素类型

​条件可见性

​状态值

​警告

​示例 — 资金来源问卷

​示例 — 未完成

​Notes

​相关内容

问卷概述

数据模型 — 问卷响应

检索会话

概览

出现位置

项目结构

元素类型

条件可见性

状态值

警告

示例 — 资金来源问卷

示例 — 未完成

Notes

相关内容