> ## 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.

# Questionnaires

> Build custom KYC questionnaires with a drag-and-drop builder. Multi-language, conditional logic, manual review routing. Pay-per-call $0.10.

export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
  const [copied, setCopied] = React.useState(false);
  const handleCopy = e => {
    e.stopPropagation();
    if (!prompt) return;
    navigator.clipboard.writeText(prompt.trim()).then(() => {
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    });
  };
  const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
  return <div className="didit-agent-card">
      {}
      <div className="didit-agent-titlebar">
        <div className="didit-agent-dots" aria-hidden="true">
          <span className="didit-agent-dot didit-agent-dot-red"></span>
          <span className="didit-agent-dot didit-agent-dot-yellow"></span>
          <span className="didit-agent-dot didit-agent-dot-green"></span>
        </div>
        <span className="didit-agent-filename">{title}</span>
        <button type="button" className={`didit-agent-copy ${copied ? "didit-agent-copy-copied" : ""}`} onClick={handleCopy} title="Copy prompt to clipboard" aria-label={copied ? "Copied!" : "Copy prompt to clipboard"}>
          {copied ? <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <path d="M3 8.5l3.5 3.5L13 4" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
              </svg>
              <span>Copied</span>
            </> : <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <rect x="5" y="5" width="9" height="9" rx="1.5" stroke="currentColor" strokeWidth="1.5" />
                <path d="M11 5V3.5A1.5 1.5 0 0 0 9.5 2h-6A1.5 1.5 0 0 0 2 3.5v6A1.5 1.5 0 0 0 3.5 11H5" stroke="currentColor" strokeWidth="1.5" />
              </svg>
              <span>Copy</span>
            </>}
        </button>
      </div>

      {}
      <pre className="didit-agent-body"><code>{prompt.trim()}</code></pre>

      {}
      <div className="didit-agent-footer">
        <span className="didit-agent-footer-label">Paste into</span>
        <div className="didit-agent-chips">
          {agents.map(name => <span key={name} className="didit-agent-chip">{name}</span>)}
        </div>
      </div>
    </div>;
};

export const VideoEmbed = ({src, title = "Video", type = "iframe"}) => <div className={type === "iframe" ? "didit-video-embed" : "didit-video-embed didit-video-native"}>
    {type === "iframe" ? <iframe src={src} title={title} style={{
  width: "100%",
  height: "100%",
  border: 0,
  borderRadius: "12px"
}} allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen /> : <video controls autoPlay muted loop playsInline src={src} title={title} style={{
  width: "100%",
  height: "auto",
  display: "block",
  borderRadius: "12px"
}} />}
  </div>;

Didit's Questionnaires let you design structured, dynamic forms to collect additional information from users during verification. Use our visual builder to drag and drop elements, organize content into sections, localize text for multiple languages, and route results for manual review when needed.

<AgentPromptAccordion
  title="Questionnaires Integration Prompt"
  prompt={`# 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`}
/>

<VideoEmbed src="https://www.youtube.com/embed/h0i9Q0-izcw?start=2681&rel=0&playsinline=1" title="Custom Questionnaires (KYB & Purpose of Relationship)" />

***

## Two Ways to Build Questionnaires

Didit offers **two distinct approaches** to creating questionnaires, allowing you to choose the right level of complexity for your needs:

<Frame>
  <img src="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" alt="Didit KYC questionnaire simple and advanced builder modes side by side" width="1280" height="842" data-path="images/questionnaires-simple-and-complex.jpg" />
</Frame>

### 1. Simple Mode: Quick Form Builder

The **Simple Mode** is perfect for creating straightforward forms quickly. Use our intuitive drag-and-drop interface to add elements, set required fields, and publish in minutes.

<Frame>
  <img src="https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-simple.jpg?fit=max&auto=format&n=z6T2GHM4Zh-iSj-K&q=85&s=8e777d8fc72ca16e8e2deb65a0a66e92" alt="Didit questionnaire simple mode drag-and-drop form builder interface" width="1280" height="669" data-path="images/questionnaires-simple.jpg" />
</Frame>

**Best for:**

* Quick data collection forms
* Simple surveys and attestations
* Teams new to form building
* Single-language questionnaires

**How it works:**

1. Open the Questionnaire Builder
2. Drag elements from the palette onto your form
3. Configure each element (label, required, placeholder)
4. Preview and publish

***

### 2. Advanced Mode: Visual Graph Builder

The **Advanced Mode** unlocks powerful features for complex data collection scenarios using a **visual node-based editor**. Build sophisticated questionnaires with conditional logic, branching paths, and full control over flow.

<Frame>
  <img src="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" alt="Didit advanced questionnaire visual node-based graph editor with branching logic" width="1280" height="667" data-path="images/questionnaires-node-based.jpg" />
</Frame>

**Best for:**

* Multi-language questionnaires
* Complex forms with conditional branching
* Compliance-driven data collection with different paths
* Forms requiring manual review workflows

**Key capabilities:**

* **Visual node editor**: Drag, drop, and connect nodes on an infinite canvas
* **Smart connections**: Drag from a node handle to empty space to instantly create and connect a new node
* **Conditional branching**: Route users to different questions based on previous answers
* **Multi-language support**: Translate all user-facing content
* **Keyboard shortcuts**: Undo (Ctrl/Cmd+Z), Redo (Ctrl/Cmd+Shift+Z), Delete (Delete/Backspace)
* **Zoom and pan**: Navigate complex forms with scroll-to-zoom and drag-to-pan

#### Graph Builder Node Types

| Node Type           | Color  | Description                           | When to Use                                       |
| ------------------- | ------ | ------------------------------------- | ------------------------------------------------- |
| **Question Nodes**  | Blue   | Input elements that collect user data | Text inputs, dropdowns, file uploads, dates, etc. |
| **Text Nodes**      | Green  | Read-only content displayed to users  | Instructions, explanations, legal text            |
| **Branching Nodes** | Orange | Conditional routing based on answers  | "If country is US, show tax form"                 |
| **Section Nodes**   | Gray   | Visual grouping of related elements   | Organize questions into logical sections          |

> **Connection Rules:** Section and Text nodes can connect to Questions and other Text nodes, but not directly to Branching nodes. Branching nodes can connect to any node type.

***

## Questionnaire Templates

Templates help you get started quickly with pre-configured forms for common use cases. You can use them as-is or customize them to fit your needs.

<Frame>
  <img src="https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-template.jpg?fit=max&auto=format&n=z6T2GHM4Zh-iSj-K&q=85&s=97a45bd55692379ffc057e11f4530a54" alt="Didit questionnaire pre-built templates for source of funds and KYC compliance" width="1280" height="872" data-path="images/questionnaires-template.jpg" />
</Frame>

### Pre-Built Templates

| Template                 | Description                                         | Typical Elements                          |
| ------------------------ | --------------------------------------------------- | ----------------------------------------- |
| **Source of Funds**      | Capture income sources and supporting documentation | Dropdown, Long Text, File Upload          |
| **Employment Details**   | Collect job title, employer, income range           | Short Text, Dropdown, Number              |
| **Purpose of Account**   | Understand intended account usage                   | Single Choice, Multiple Choice, Long Text |
| **Beneficial Ownership** | Identify UBOs and ownership structure               | Short Text, Number, File Upload           |
| **Tax Residency**        | Collect tax-related declarations                    | Country, Consent, File Upload             |
| **Risk Assessment**      | Gather risk-relevant information                    | Multiple Choice, Dropdown, Long Text      |

***

## How it works

Our questionnaire workflow is designed for flexibility and auditability:

### 1. Build in the Console (No Code)

* Drag and drop elements to create your questionnaire
* Organize content into multiple sections for clarity
* Mark elements as required or optional
* Configure placeholders and helper descriptions
* Add choices (with optional free-text follow-up) for dropdown and single-choice
* Configure file/image upload limits per element

### 2. Localize Content

* Provide translations for `title`, `description`, `placeholder`, and choices
* Define supported `languages` and a `default_language`
* The end-user sees content automatically in the best available language

### 3. Publish and Collect

* Activate the questionnaire and embed it in your verification flow
* End-users complete the sections and submit answers
* File uploads (documents, images) are stored and linked to the response

### 4. Review and Decide

* Responses are saved with a `status`: `Approved`, `In Review`, or `Not Finished`
* You can force all questionnaire responses to go `In Review`, so a person manually approves them
* Review answers and files in the console, then mark as `Approved`

> Note: Questionnaires do not produce risk warnings. Governance is achieved through required fields, validation, and review workflows.

***

## Key capabilities

| Capability                  | Simple Mode | Advanced Mode |
| --------------------------- | ----------- | ------------- |
| Drag-and-drop builder       | ✅           | ✅             |
| Required/optional fields    | ✅           | ✅             |
| Placeholders & descriptions | ✅           | ✅             |
| Multiple sections           | ✅           | ✅             |
| File upload limits          | ✅           | ✅             |
| Visual graph editor         | ❌           | ✅             |
| Conditional branching       | ❌           | ✅             |
| Multi-language translations | ❌           | ✅             |
| Choice logic (require text) | ❌           | ✅             |
| Force manual review         | ❌           | ✅             |
| Undo/Redo support           | ❌           | ✅             |
| Keyboard shortcuts          | ❌           | ✅             |

**Full feature list:**

* **Visual Builder**: Create and manage questionnaires with an intuitive drag-and-drop editor
* **Sections**: Group related questions; add headers and separators to guide users
* **Translations**: Localize all user-facing text; select default language; support multiple languages
* **Validation**: Mark fields required; enforce max files per upload element
* **Choice Logic**: For dropdown/single-choice, optionally require additional text per selected option
* **Uploads**: Collect documents and images with file count limits (e.g., up to 3 files)
* **Manual Review**: Optionally force all responses to `In Review` pending human approval
* **Activation Toggle**: Enable or disable the questionnaire per application
* **Workflow Integration**: Add questionnaires to KYC or run them standalone as a Questionnaire Verification workflow
* **APIs & Webhooks**: Read structured results via API and receive updates

***

## Element types

You can add the following element types in the builder (selectable from the console):

### Input Elements

| Element          | Description                 | Configuration Options |
| ---------------- | --------------------------- | --------------------- |
| **SHORT\_TEXT**  | Single-line free text       | Placeholder, required |
| **LONG\_TEXT**   | Multi-line free text        | Placeholder, required |
| **NUMBER**       | Numeric input               | Placeholder, required |
| **EMAIL**        | Email input with validation | Placeholder, required |
| **PHONE**        | Phone number input          | Placeholder, required |
| **ADDRESS**      | Address input               | Placeholder, required |
| **DATE\_PICKER** | Date selection              | Placeholder, required |
| **TIME**         | Time input                  | Placeholder, required |

### Choice Elements

| Element              | Description                  | Configuration Options                     |
| -------------------- | ---------------------------- | ----------------------------------------- |
| **DROPDOWN**         | Single selection from a list | Choices, `requires_text_input` per choice |
| **SINGLE\_CHOICE**   | Radio-style single selection | Choices, `requires_text_input` per choice |
| **MULTIPLE\_CHOICE** | Multi-select checklist       | Choices                                   |
| **COUNTRY**          | Country selector             | Required                                  |
| **CONSENT**          | Checkbox or acknowledgement  | Required, custom label                    |

### Upload Elements

| Element          | Description     | Configuration Options       |
| ---------------- | --------------- | --------------------------- |
| **IMAGE**        | Image upload    | `max_files` (1-5), required |
| **FILE\_UPLOAD** | Document upload | `max_files` (1-5), required |

### Layout Elements

| Element             | Description                | Notes                        |
| ------------------- | -------------------------- | ---------------------------- |
| **PARAGRAPH**       | Read-only explanatory text | Not answerable               |
| **SECTION\_HEADER** | Visual section header      | Not answerable, not required |
| **SEPARATOR**       | Visual divider             | Not answerable, not required |

**Behavioral notes:**

* `SECTION_HEADER` and `SEPARATOR` are presentation-only. They ignore required/placeholder/choices/file limits.
* For choice elements, define choices as `{ label, value, requires_text_input? }`.
* For upload elements, set `max_files` (1–5) to control how many files can be attached.

***

## Forcing manual review

Some compliance workflows require human review of every response. From the console, you can set questionnaires to always result in `In Review`. A reviewer then approves or requests changes, after which the response becomes `Approved`.

**When to use manual review:**

* High-risk customer onboarding
* Sensitive data collection (Source of Funds, UBO declarations)
* Regulatory requirements for human oversight
* Quality assurance during initial rollout

***

## Example use cases

### Source of Funds

Capture income sources, amounts, and upload supporting documents (e.g., payslips, statements). Combine dropdowns, long text, and file uploads.

**Typical structure:**

* Section 1: Employment Status (Dropdown)
* Section 2: Income Sources (Multiple Choice + Long Text)
* Section 3: Supporting Documents (File Upload)
* Section 4: Declaration (Consent)

***

### Association or Membership

Record affiliations, roles, and proof of membership; include consent elements for declarations.

**Typical structure:**

* Organization Name (Short Text)
* Role/Position (Dropdown)
* Duration of Membership (Date Picker)
* Membership Proof (File Upload)
* Declaration (Consent)

***

### Purpose of Relationship & Expected Account Activity

Collect intent, expected transaction volumes, countries of activity, and anticipated counterparties. Use single/multiple choice, number inputs, and paragraphs for context.

**Typical structure:**

* Section 1: Account Purpose (Multiple Choice)
* Section 2: Expected Monthly Volume (Number + Dropdown for currency)
* Section 3: Countries of Activity (Country - multiple)
* Section 4: Transaction Types (Multiple Choice)
* Section 5: Additional Information (Long Text)

***

## Simple vs Advanced Mode: When to Use Each

| Scenario                      | Recommended Mode |
| ----------------------------- | ---------------- |
| Single-language, basic form   | Simple           |
| Multi-language support needed | Advanced         |
| Quick internal survey         | Simple           |
| Compliance questionnaire      | Advanced         |
| One-time data collection      | Simple           |
| Conditional branching paths   | Advanced         |
| Force manual review           | Advanced         |
| Complex multi-section forms   | Advanced         |

***

## Getting Started

1. **New to questionnaires?** Start with **Simple Mode** to learn the builder
2. **Need translations or conditional logic?** Switch to **Advanced Mode** for the visual graph editor

> See how results are structured in the [Questionnaires Report](/core-technology/questionnaires/report-questionnaire) page.