> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# KYC 问卷 API：动态表单构建器

> Didit 问卷功能支持通过拖拽式构建器创建自定义 KYC 问卷，具备多语言、条件逻辑与人工审核流转功能，每次调用仅需 $0.10。

Didit 的问卷功能让您能够设计结构化的动态表单，以便在验证过程中从用户处收集额外信息。使用我们的可视化构建器拖放元素、将内容划分为不同板块、针对多种语言进行本地化，并在需要时将结果流转至人工审核。

问卷集成提示词
        将提示词复制到剪贴板



      
      

\<pre>

\````# Goal
Integrate Didit Questionnaires (custom KYC/KYB forms with conditional logic and manual-review routing) into your app.

\# Delivery mode
Questionnaires are **session-only**. The form is designed in the Business Console (drag-and-drop builder) and bound to a workflow via the QUESTIONNAIRE feature. There is no standalone questionnaire submission API — answers are collected through the hosted Didit flow.

\# Steps
1\. Build the questionnaire in the Business Console (Questionnaires tab). Define sections, fields, conditional visibility, multi-language labels, and **custom status rules** (e.g. "if source_of_funds = 'crypto' set status to In Review").
2\. Add the QUESTIONNAIRE feature to a workflow and select the questionnaire id (POST /v3/workflows/ or the Console).
3\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
4\. Open session.url for the user (or mount the Web/Mobile SDK) — the form renders inside the flow.
5\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

curl (create session):
\```bash
curl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-1234",
"callback": "https://yourapp.com/post-kyc"
}'
\```

\# Decision surface
The result lands under `questionnaire_responses[]` on the decision payload (one entry per questionnaire node). Each entry includes:
\- `status` — final status for this questionnaire instance (driven by your custom status rules).
\- `answers` — array of { question_id, question_label, value } pairs (or nested sections).
\- `warnings` — any rule-triggered warnings.

\# Status enum (per questionnaire_responses[].status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"

\# Warnings (LogWarningChoices.QUESTIONNAIRE)
The dominant risk code is CUSTOM_STATUS_RULE_TRIGGERED — emitted whenever an answer matches a Console-configured rule that escalates the status. The warning's `additional_data` carries the rule id and matched answer so reviewers can see why the session was routed.

Full catalogue: questionnaire warnings are documented inside the report page — see /core-technology/questionnaires/report-questionnaire.

\# Failure modes to handle
\- questionnaire_responses[] empty — user abandoned the form. The session status will reflect "Abandoned"; treat per your retention policy.
\- status="In Review" with CUSTOM_STATUS_RULE_TRIGGERED — answers crossed your manual-review rule; surface the relevant answers in your reviewer UI.
\- status="Declined" — answers crossed a decline rule (e.g. user declared they are a sanctioned-country resident); do not approve.

\# See also
\- Canonical schema: /reference/data-models#questionnaire-response
\- Per-feature report: /core-technology/questionnaires/report-questionnaire
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

粘贴到

在关于解读验证结果的 Academy 课程中，11:54 章节介绍了 Document AI 和问卷。[Document AI 与问卷 — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=714\&rel=0\&playsinline=1)***## 构建问卷的两种方式Didit 提供**两种截然不同的方式**来创建问卷，让您可以根据需求选择合适的复杂度：![Didit KYC 问卷的简单和高级构建器模式并排显示](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-simple-and-complex.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=71d18d67b4684cca46c7809ba43cfcb6)### 1. 简单模式: 快速表单构建器**简单模式**非常适合快速创建直观的表单。使用我们直观的拖拽界面即可添加元素、设置必填字段，并在数分钟内完成发布。![Didit 问卷简单模式的拖放式表单构建器界面](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-simple.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=8e777d8fc72ca16e8e2deb65a0a66e92)**最适合：**- 快速数据收集表单
- 简单的调查问卷与证明
- 刚开始接触表单构建的团队
- 单一语言问卷**工作原理：**1) 打开问卷构建器
2) 从组件面板中将元素拖拽到表单上
3) 配置每个元素（标签、必填、占位符）
4) 预览并发布***### 2. 高级模式: 可视化图谱构建器**高级模式**通过**基于节点的可视化编辑器**，为复杂的数据收集场景解锁强大的功能。构建具有条件逻辑、分支路径以及完整流程控制的精密问卷。![Didit 高级问卷的基于节点的可视化图谱编辑器，包含分支逻辑](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-node-based.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=7ff0c1d79f500ed3f78dca4ff89b0698)**最适合：**- 多语言问卷
- 带有条件分支的复杂表单
- 具有不同路径且由合规驱动的数据收集
- 需要人工审核工作流的表单**核心能力：**- **可视化节点编辑器**：在无限画布上拖拽、放置并连接节点
- **智能连接**：从节点控制柄拖拽到空白区域，即可立即创建并连接新节点
- **条件分支**：根据先前的回答将用户引导至不同问题，然后[在共享步骤处重新汇合路径](#将分支路径重新汇合到共享步骤)
- **多语言支持**：翻译所有面向用户的内容
- **键盘快捷键**：撤销（Ctrl/Cmd+Z）、重做（Ctrl/Cmd+Shift+Z）、删除（Delete/Backspace）
- **缩放与平移**：通过滚动缩放和拖拽平移在复杂表单中自如浏览#### 图谱构建器节点类型| 节点类型 | 颜色 | 描述 | 何时使用 |
| - | - | - | - |
| **问题节点** | 蓝色 | 收集用户数据的输入元素 | 文本输入、下拉菜单、文件上传、日期等 |
| **文本节点** | 绿色 | 向用户显示的只读内容 | 说明、解释、法律文本 |
| **分支节点** | 橙色 | 基于回答的条件路由 | “如果国家为美国，则显示税务表单” |
| **分区节点** | 灰色 | 相关元素的可视化分组 | 将问题整理为逻辑分区 |> **连接规则：**分区节点和文本节点可以连接到问题节点和其他文本节点，但不能直接连接到分支节点。分支节点可以连接到任何节点类型。#### 条件运算符分支条件用于将先前的回答与特定值进行比对。
使用 `and` 或 `or` 可以组合多个条件。| 运算符 | 匹配条件：当回答 |
| - | - |
| `equals` | 等于该值 |
| `not_equals` | 不等于该值 |
| `contains` | 包含该值 |
| `greater_than` | 大于该值 |
| `greater_than_or_equals` | 大于或等于该值 |
| `less_than` | 小于该值 |
| `less_than_or_equals` | 小于或等于该值 |
| `in` | 属于值列表中的一项 |
| `not_in` | 不属于值列表中的任何一项 |
| `is_empty` | 留空未填 |
| `is_not_empty` | 已填写 |#### 将分支路径重新汇合到共享步骤分支不必始终保持单向分流。多条路径的末端可以连接到同一个下游节点，问卷将从该处继续，且共享问题只需回答一次。共享的问题集中在一处构建和维护，无需在每条路径的末尾重复设置。**实操示例：在选择“是”时显示额外问题，随后汇入共享后续流程**1) 添加一个包含“是”和“否”选项的**单选**问题的**问题节点**，随后添加一个包含 `Yes` 路径和 `No` 路径的**分支节点**。
2) 在 `Yes` 路径上，添加仅在回答为“是”时才适用的额外问题。
3) 在该路径的末尾，添加分支后每位答卷人都必须回答的第一个问题，即共享后续流程的起点。
4) 将 `No` 路径指向该问题：打开 `No` 路径末尾的 **+** 菜单并选择**连接到现有步骤**，或者从 `No` 路径的连接点拖拽并在共享问题的顶部边缘释放。画布仅连接到卡片顶部的小目标区域，因此在卡片中间释放不会产生任何效果。
5) 在第一个共享问题之后继续添加其余共享问题，然后发布。画布将会在导向共享后续流程的各条路径下方仅绘制一次该共享后续流程。路径可以通过这种方式加入已存在的节点，且多条路径可以指向同一个节点。汇合会设置该路径的后续连接位置，因此在路径以此结束时，**+** 菜单会提供**连接到现有步骤**选项。任何会闭合回路返回到先前节点的连接都会被拒绝。无论答卷人走哪条路径，共享问题都只需回答一次；答卷人未走路径上的问题将被跳过。决策 payload 遵循相同的规则：`questionnaire_responses[].sections[].items` 仅列出答卷人所走路径上的项目。请参阅[条件可见性](https://docs.didit.me/zh/core-technology/questionnaires/report-questionnaire.md#条件可见性)。***## 问卷模板模板可帮助您通过适用于常见使用场景的预配置表单快速入门。您可以直接使用它们，也可以根据自身需求进行自定义。![Didit 问卷预构建模板，适用于资金来源和 KYC 合规](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-template.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=97a45bd55692379ffc057e11f4530a54)### 预构建模板| 模板 | 说明 | 典型元素 |
| - | - | - |
| **资金来源** | 获取收入来源和支持性证明文件 | 下拉菜单、长文本、文件上传 |
| **就业详情** | 收集职位、雇主、收入范围 | 短文本、下拉菜单、数字 |
| **账户目的** | 了解预期的账户用途 | 单选、多选、长文本 |
| **实际受益所有权** | 识别 UBO 和股权结构 | 短文本、数字、文件上传 |
| **税务居住地** | 收集税务相关的声明 | 国家/地区、同意、文件上传 |
| **风险评估** | 收集风险相关信息 | 多选、下拉菜单、长文本 |***## 工作原理我们的问卷工作流专为灵活性和可审计性而设计：### 1. 在控制台中构建 (无需编写代码)- 拖放元素以创建您的问卷
- 将内容整理为多个分区以保持清晰
- 将元素标记为必填或可选
- 配置占位符和辅助描述
- 为下拉菜单和单选添加选项（可包含可选的自由文本补充内容）
- 为每个元素配置文件/图片上传限制### 2. 内容本地化- 仅需使用问卷的 `default_language` 编写一次内容
- 定义支持的 `languages`：当您发布时，所有标题、描述、占位符、选项标签和验证消息都会**自动翻译**为全部所选语言
- 在构建器中手动微调任何翻译；在源文本变更之前，手动编辑将始终保留
- 终端用户将自动以最佳可用语言查看内容### 3. 发布与收集- 激活问卷并将其嵌入您的验证流程中
- 终端用户完成各个分区并提交答案
- 上传的文件（证件、图片）将被存储并与回答关联### 4. 审核与决策* 回答保存时带有 `status`：`Approved`、`In Review` 或 `Not Finished`
* 您可以强制所有问卷回答进入 `In Review`，以便由审核人员手动批准
* 在控制台中查看答案和文件，然后标记为 `Approved`> 注意：问卷不会生成风险警告。治理是通过必填字段、验证和审核工作流来实现的。***## 核心功能| 功能 | 简易模式 | 高级模式 |
| - | - | - |
| 拖放式构建器 | ✅ | ✅ |
| 必填/可选字段 | ✅ | ✅ |
| 占位符与描述 | ✅ | ✅ |
| 多个分区 | ✅ | ✅ |
| 文件上传限制 | ✅ | ✅ |
| 可视化图谱编辑器 | ❌ | ✅ |
| 条件分支 | ❌ | ✅ |
| 多语言翻译 | ❌ | ✅ |
| 选项逻辑（要求补充文本） | ❌ | ✅ |
| 强制人工审核 | ❌ | ✅ |
| 撤销/重做支持 | ❌ | ✅ |
| 键盘快捷键 | ❌ | ✅ |**完整功能列表：**- **可视化构建器**：使用直观的拖放式编辑器创建和管理问卷
- **分区**：对相关问题进行分组；添加标题和分隔线以引导用户
- **自动翻译**：使用一种语言编写内容，在发布时，所有面向用户的文本都会自动翻译为所有其他选定语言，并支持手动微调
- **验证**：将字段标记为必填；对每个上传元素强制执行最大文件数限制
- **选项逻辑**：对于下拉菜单/单选，可选择对选定的每个选项要求补充文本
- **上传**：收集具有文件数量限制的证件和图片（例如最多 3 个文件）
- **人工审核**：可选择强制所有回答进入 `In Review`，等待人工批准
- **激活开关**：按应用启用或禁用问卷
- **工作流集成**：将问卷添加到 KYC 中，或作为问卷验证工作流单独运行
- **API 与 Webhook**：通过 API 读取结构化结果并接收更新***## 元素类型您可以在构建器中添加以下元素类型（可直接在控制台中选择）：### 输入元素| 元素 | 说明 | 配置选项 |
| - | - | - |
| **SHORT\_TEXT** | 单行自由文本 | 占位符、必选 |
| **LONG\_TEXT** | 多行自由文本 | 占位符、必选 |
| **NUMBER** | 数字输入 | 占位符、必选 |
| **EMAIL** | 带有验证的邮箱输入 | 占位符、必选 |
| **PHONE** | 电话号码输入 | 占位符、必选 |
| **ADDRESS** | 地址输入 | 占位符、必选 |
| **DATE\_PICKER** | 日期选择 | 占位符、必选 |
| **TIME** | 时间输入 | 占位符、必选 |### 选项元素| 元素 | 说明 | 配置选项 |
| - | - | - |
| **DROPDOWN** | 列表单选下拉框 | 选项、每个选项的 `requires_text_input` |
| **SINGLE\_CHOICE** | 单选框样式的单选 | 选项、每个选项的 `requires_text_input` |
| **MULTIPLE\_CHOICE** | 多选复选框列表 | 选项 |
| **COUNTRY** | 国家/地区选择器 | 必选 |
| **CONSENT** | 复选框或确认声明 | 必选、自定义标签 |### 上传元素| 元素 | 说明 | 配置选项 |
| - | - | - |
| **IMAGE** | 图片上传 | `max_files` (1-5)、必选 |
| **FILE\_UPLOAD** | 证件上传 | `max_files` (1-5)、必选 |### 布局元素| 元素 | 说明 | 备注 |
| - | - | - |
| **PARAGRAPH** | 只读解释性文本 | 不可回答 |
| **SECTION\_HEADER** | 可视化小节标题 | 不可回答，非必选 |
| **SEPARATOR** | 可视化分隔线 | 不可回答，非必选 |**行为说明：**- `SECTION_HEADER` 和 `SEPARATOR` 仅用于展示。它们会忽略必选/占位符/选项/文件数量限制等配置。
- 对于选项元素，请将选项定义为 `{ label, value, requires_text_input? }`。
- 对于上传元素，请设置 `max_files` (1–5) 以控制最多可上传的文件数量。***## 强制人工审核某些合规工作流要求对每个回答都进行人工审核。在控制台中，您可以将问卷设置为始终生成 `In Review` 结果。审核员随后批准或请求修改，之后回答状态变为 `Approved`。**何时使用人工审核：**- 高风险客户入驻
- 敏感数据收集（资金来源、UBO 声明）
- 监管对人工监督的要求
- 初步上线期间的质量保证***## 常见用例### 资金来源收集收入来源、金额，并上传证明材料（例如工资单、对账单）。结合使用下拉框、长文本和文件上传。**典型结构：**- 第 1 节：就业状态（下拉框）
- 第 2 节：收入来源（多选 + 长文本）
- 第 3 节：证明材料（文件上传）
- 第 4 节：声明（同意）***### 协会或会员关系记录所属机构、角色和会员身份证明；包含用于声明确认的同意元素。**典型结构：**- 组织名称（短文本）
- 角色/职位（下拉框）
- 会员期限（日期选择器）
- 会员身份证明（文件上传）
- 声明（同意）***### 业务关系目的与预期账户活动收集使用意向、预期交易量、开展活动的国家/地区以及预期交易对手。使用单选/多选、数字输入和段落来说明背景。**典型结构：**- 第 1 节：账户用途（多选）
- 第 2 节：预计月交易量（数字输入 + 用于币种的下拉框）
- 第 3 节：开展活动的国家/地区（国家/地区选择器 - 多选）
- 第 4 节：交易类型（多选）
- 第 5 节：补充信息（长文本）***## 简易模式与高级模式：何时使用| 场景 | 推荐模式 |
| - | - |
| 单语言基础表单 | 简易模式 |
| 需要多语言支持 | 高级模式 |
| 快速内部调研 | 简易模式 |
| 合规问卷 | 高级模式 |
| 一次性数据收集 | 简易模式 |
| 条件分支路径 | 高级模式 |
| 强制人工审核 | 高级模式 |
| 复杂的多小节表单 | 高级模式 |***## 开始使用1. **刚接触问卷？** 从**简易模式**开始熟悉构建器
2. **需要翻译或条件逻辑？** 切换到**高级模式**使用可视化图谱编辑器> 请参阅 [问卷报告](https://docs.didit.me/zh/core-technology/questionnaires/report-questionnaire.md) 页面了解结果的结构形式。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.