Collect any data.
Inside any verification flow.

# Didit Custom Questionnaires — integrate in 5 minutes

You are integrating Didit's Custom Questionnaires module into <my_stack>.
Follow these steps exactly. Every URL, header, and enum value below is
canonical — do not paraphrase or "improve" them.

## 1. Provision an account
- Sign up: https://business.didit.me (no credit card required).
- Or provision programmatically: POST https://apx.didit.me/auth/v2/programmatic/register/
  (returns an API key bound to the workspace + application).

## 2. Build the questionnaire — Console OR API

### 2a. Visual builder in the Console (no code)
Questionnaires are authored visually — no schema upload, no SDK required.
1. Open https://business.didit.me, go to Questionnaires, click New.
2. Pick a mode:
   - Simple Mode — single-language drag-and-drop builder. Best for fast
     forms, internal surveys, single-locale flows.
   - Advanced Mode — visual node-based graph editor. Required for
     conditional branching, multi-language translations, choice-driven
     follow-up text, and forced manual review.
3. Drag elements onto the canvas (input, choice, upload, layout — full
   element catalog in section 5 below).
4. Optionally start from a pre-built template (Source of Funds,
   Employment Details, Purpose of Account, Beneficial Ownership, Tax
   Residency, Risk Assessment).
5. Localize titles, descriptions, placeholders, and choice labels for
   every supported language; set a default_language.
6. Publish — the questionnaire is now addressable by its questionnaire_id.

### 2b. Create the questionnaire programmatically (Management API)
Use this path when you want the form to live in code, ship via CI, or be
authored by an LLM. Endpoint:

  POST https://verification.didit.me/v3/questionnaires/
  Headers:  x-api-key: <your-api-key>
            Content-Type: application/json

Required body:
- title              — internal questionnaire name (string).
- languages          — array of locale codes; MUST include "en".
- default_language   — the default locale (string, e.g. "en").
- form_elements      — ordered array of questions (≥1 entry).

Each form element requires id, element_type (lowercase OR uppercase enum
— "short_text", "multiple_choice", "email", "file_upload", "date_picker",
etc.), and a translated label keyed by locale. For dropdown,
single_choice, and multiple_choice add options: [{ value, label }].

Hard constraints:
- This endpoint supports SIMPLE LINEAR questionnaires only. Do NOT send
  graph, branches, next, required_if, or conditional rules — use the
  Console (section 2a) for those.

Example body:
{
  "title": "Customer Onboarding",
  "languages": ["en"],
  "default_language": "en",
  "form_elements": [
    {
      "id": "occupation",
      "element_type": "short_text",
      "label": { "en": "What is your occupation?" },
      "is_required": true
    },
    {
      "id": "source_of_funds",
      "element_type": "multiple_choice",
      "label": { "en": "Source of funds" },
      "is_required": true,
      "options": [
        { "value": "employment", "label": { "en": "Employment" } },
        { "value": "business", "label": { "en": "Business" } },
        { "value": "investments", "label": { "en": "Investments" } }
      ]
    }
  ]
}

Response includes questionnaire_id — store it; you'll use it as
questionnaire_uuid when you wire the questionnaire into a workflow in
section 3 below. Full reference:
https://docs.didit.me/management-api/questionnaires/create

## 3. Two integration paths — pick one

### Path A — Workflow Builder (hosted UI, recommended)
Best when you want Didit to host the form, the file-upload UX, the
multi-language routing, the keyboard handling, and the mobile responsive
layout.

1. Create a workflow that contains the QUESTIONNAIRE feature:
   POST https://verification.didit.me/v3/workflows/
   Authorization header:  x-api-key: <your-api-key>
   Body: workflow_label, features array with the entry
         { feature: "QUESTIONNAIRE", questionnaire_id: "<id>" }
         (UPPERCASE — strict enum)
   Optional: chain QUESTIONNAIRE after ID_VERIFICATION + LIVENESS in the
   same workflow to collect Source of Funds as part of a full Know Your Customer (KYC).

2. Create a verification session for an end user:
   POST https://verification.didit.me/v3/session/
   Body: workflow_id (from step 1), vendor_data (your own user id).
   Response: session_url — redirect the user to it.

3. Listen for webhook callbacks (see "Webhooks" below).

### Path B — Standalone Questionnaire Verification
Run a questionnaire as its own verification — no KYC required.
Use a workflow whose only feature is QUESTIONNAIRE. Everything else is
identical to Path A. Useful for ongoing-due-diligence pulses,
post-onboarding declarations, periodic re-attestations.

## 4. Webhooks
- Register a webhook destination once via
  POST https://verification.didit.me/v3/webhook/destinations/
  Body: url, subscribed_events: ["session.verified", "session.review_started",
                                  "session.declined"]
- Response includes secret_shared_key — store it.
- Every webhook delivery carries an X-Signature-V2 header you MUST verify
  before trusting the payload.  HMAC-SHA256 verification MUST run against the raw body bytes (the raw payload as Didit sent it) BEFORE any JSON parsing — re-serialising the parsed body changes whitespace and key order, which invalidates the signature.Algorithm:
    1. sortKeys(payload) recursively
    2. shortenFloats (truncate trailing zeros after the decimal point)
    3. JSON.stringify the result
    4. HMAC-SHA256 with the secret_shared_key
    5. Hex-encode, compare to the X-Signature-V2 header.

## 5. Element catalog (use these in the builder)
Input elements:
  SHORT_TEXT, LONG_TEXT, NUMBER, EMAIL, PHONE, ADDRESS, DATE_PICKER, TIME
Choice elements:
  DROPDOWN, SINGLE_CHOICE, MULTIPLE_CHOICE, COUNTRY, CONSENT
  - DROPDOWN and SINGLE_CHOICE support per-option requires_text_input —
    selecting "Other" can demand a free-text follow-up.
Upload elements:
  IMAGE, FILE_UPLOAD
  - max_files (1-5) per element.
Layout elements:
  PARAGRAPH, SECTION_HEADER, SEPARATOR (read-only, not answerable).

## 6. Reading the report
The session report contains a questionnaire_responses array (one entry
per questionnaire step in the workflow graph). Each entry has:
- node_id: identifies the questionnaire step in the workflow graph
- questionnaire_id: which questionnaire this response is for
- title, description, languages, default_language, is_active
- sections: array of { title, description, items[] }
- each item: { uuid, order, element_type, is_required, title,
              description, placeholder, choices, max_files, answer }
- answer: { value, text, files[] } — only the fields relevant to the
  element_type are present.
- status: "Approved" | "In Review" | "Not Finished"

Status semantics:
- Not Finished — user has not completed the questionnaire yet.
- In Review — submitted, pending manual review. The Console flag
  "force manual review" pins every response to this state until a human
  approves it.
- Approved — reviewed and accepted.

Note: questionnaires do NOT emit risk warnings. Governance is achieved
through required fields, validation, manual review, and the workflow
graph (branching nodes route compliance-sensitive answers to In Review).

## 7. Hard rules — do not change
- Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
- Feature enum is UPPERCASE: QUESTIONNAIRE, ID_VERIFICATION, LIVENESS,
  FACE_MATCH, AML, IP_ANALYSIS.
- Element type enums are UPPERCASE + underscored: SHORT_TEXT, LONG_TEXT,
  FILE_UPLOAD, SINGLE_CHOICE, etc.
- Auth header is x-api-key (lowercase, hyphenated).
- Webhook signature header is X-Signature-V2 (NOT X-Signature).
- Always verify webhook signatures before trusting payload data.
- Status casing matches exactly: "Approved", "In Review", "Not Finished"
  (title-cased, space-separated).

## 8. Pricing reference (public)
- $0.10 per questionnaire submission (Path A or Path B).
- No minimums. No per-language surcharge. No per-element surcharge.
  Conditional branching, file uploads, manual review — all included at
  the same per-submission price.

## 9. Verify your integration
- Sandbox starts on signup at https://business.didit.me — no separate flag.
- Use one of the pre-built templates (Source of Funds, Employment
  Details, Purpose of Account, Beneficial Ownership, Tax Residency, Risk
  Assessment) to ship a draft in under a minute, then customise.
- Switch to live: flip the application's environment toggle in console.

When in doubt: https://docs.didit.me/core-technology/questionnaires/overview