Skip to main content
POST
/
v3
/
questionnaires
cURL
curl -X POST 'https://verification.didit.me/v3/questionnaires/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Customer Onboarding",
    "default_language": "en",
    "languages": ["en"],
    "form_elements": [
      {
        "id": "occupation",
        "element_type": "short_text",
        "label": {"en": "What is your occupation?"},
        "is_required": true
      }
    ]
  }'
{
  "questionnaire_id": "11111111-2222-3333-4444-555555555555",
  "title": "Customer Onboarding",
  "description": "Additional information needed for verification",
  "languages": [
    "en"
  ],
  "default_language": "en",
  "is_active": true,
  "is_simple_questionnaire": true,
  "graph": {
    "start_node": "occupation",
    "nodes": {
      "occupation": {
        "element_type": "SHORT_TEXT",
        "is_required": true,
        "title": {
          "en": "What is your occupation?"
        },
        "next": "source_of_funds"
      },
      "source_of_funds": {
        "element_type": "MULTIPLE_CHOICE",
        "is_required": true,
        "title": {
          "en": "Source of funds"
        },
        "choices": [
          {
            "value": "employment",
            "label": {
              "en": "Employment"
            }
          },
          {
            "value": "business",
            "label": {
              "en": "Business"
            }
          }
        ],
        "next": null
      }
    }
  },
  "sections": [],
  "questionnaire_group_id": "11111111-2222-3333-4444-555555555555",
  "version": 1,
  "status": "published",
  "published_at": "2026-04-23T10:00:00Z",
  "is_editable": false
}
Use this endpoint to create simple questionnaires through the API. Send a form_elements array in the order users should answer the questions. Didit builds the internal questionnaire graph for you. The API supports simple linear questionnaires only. Do not send graph, branches, next, or conditional rules.

​
Required fields

  • title is the internal questionnaire name.
  • languages must include en.
  • form_elements must contain at least one question.
  • Each form element needs an element_type and a translated label.

​
Element types

Use lowercase values such as short_text, multiple_choice, email, file_upload, or date_picker. Uppercase enum values such as SHORT_TEXT are also accepted. For dropdown, single_choice, and multiple_choice, add options. If you omit an option value, Didit generates one from the label. 
{
  "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" } }
      ]
    }
  ]
}
The response includes questionnaire_id. Store it, because you will use it as questionnaire_uuid when you add the questionnaire to a workflow.

Authorizations

​
x-api-key
string
header
required

Body

application/json

Create a simple linear questionnaire. The API converts form_elements into the internal questionnaire graph.

​
title
string
required

Internal name for the questionnaire.

​
languages
string[]
required

Languages included in every label. Must include en.

Example:
["en"]
​
form_elements
object[]
required

Questions in the exact order users should see them. Branching and conditional fields are not supported.

Minimum array length: 1
​
description
string | null
​
default_language
string

Default language. Must be included in languages.

Example:

"en"

​
is_active
boolean
default:true
​
status
enum<string>

Omit this field to create a published questionnaire ready for workflows.

Available options:
draft,
published

Response

Questionnaire created. The response includes the questionnaire_id — store it to reference this questionnaire from workflows or future update/delete calls.

Full questionnaire detail returned from GET, POST (create) and PATCH (update) endpoints.

​
questionnaire_id
string<uuid>

Unique identifier of the questionnaire. Use this id when referencing the questionnaire from a workflow or in subsequent update/delete requests.

​
title
string
​
description
string | null
​
languages
string[]
​
default_language
string
​
is_active
boolean
​
is_simple_questionnaire
boolean
​
graph
object

Graph structure with start_node and nodes map.

​
sections
object[]

Questionnaire content grouped into sections (derived from the graph).

​
questionnaire_group_id
string<uuid>

Stable identifier that groups all versions of the same questionnaire.

​
version
integer
​
status
enum<string>
Available options:
draft,
published
​
published_at
string<date-time> | null
​
is_editable
boolean

True when the questionnaire can still be edited in place (draft versions).