Questionnaire

A Questionnaire defines a structured set of questions. Each questionnaire is versioned and includes metadata such as its name, description, and whether it is generic or specific to an entity.

Listing Questionnaires

Fetch available questionnaires for a specific entity type.

Endpoints:

• Retail: GET /questionnaires/persons or GET /questionnaires/persons/{person_id}
• Corporate: GET /questionnaires/corporates or GET /questionnaires/corporates/{corporate_id}

View Example Response

{
  "items": [
    {
      "id": "67e00f6f-97d3-4d5d-b5f9-82b4a8ac4c7f",
      "name": "Finances",
      "description": "Questionnaire required for DLT onboarding - asking about financial state of customer.",
      "owner_type": "person",
      "owner_type_id": null,
      "is_generic": true,
      "is_published": true,
      "created_at": "2024-09-03T14:55:26.346500Z"
    },
    {
      "id": "f0faa5a0-a492-44e3-8538-1696a59d48ee",
      "name": "DLT",
      "description": "Questionnaire required for DLT onboarding",
      "owner_type": "person",
      "owner_type_id": null,
      "is_generic": true,
      "is_published": true,
      "created_at": "2024-09-03T14:55:26.346500Z"
    }
  ],
  "page": 1,
  "size": 50
}

Getting Definitions (Rendering)

To render a form, fetch the detailed structure of a specific questionnaire.

Endpoint: GET /questionnaires/{id}

View Example Response

{
  "id": "f0faa5a0-a492-44e3-8538-1696a59d48ee",
  "name": "DLT",
  "description": "Questionnaire required for DLT onboarding",
  "is_published": true,
  "owner_type": "person",
  "owner_type_id": null,
  "is_generic": true,
  "created_at": "2024-09-03T14:55:26.346500Z",
  "data": {
    "id": "9680a1a2-811e-40bf-96e7-14aac0359f36",
    "version_number": 3,
    "questionnaire_id": "f0faa5a0-a492-44e3-8538-1696a59d48ee",
    "created_at": "2024-09-10T12:23:07.104279Z",
    "questions": [
      {
        "label": "Please select your  product usage.",
        "value": "products",
        "question_type": "multiple_choice",
        "position": 1,
        "is_optional": false,
        "id": "355ec732-2352-4e9f-9cfb-f5e950d1d299",
        "questionnaire_version_id": "9680a1a2-811e-40bf-96e7-14aac0359f36",
        "options": [
          {
            "label": "Spot",
            "value": "spot",
            "position": 1,
            "id": "52131052-134d-4428-a24e-4de823189041",
            "question_id": "355ec732-2352-4e9f-9cfb-f5e950d1d299"
          },
          {
            "label": "Futures",
            "value": "futures",
            "position": 2,
            "id": "5773e391-2f6e-4a36-87cf-d6721bf35fdf",
            "question_id": "355ec732-2352-4e9f-9cfb-f5e950d1d299"
          },
          {
            "label": "Margin",
            "value": "margin",
            "position": 3,
            "id": "5bb63677-6707-4b47-a533-6c32922ee7bd",
            "question_id": "355ec732-2352-4e9f-9cfb-f5e950d1d299"
          }
        ]
      },
      {
        "label": "Please select the purpose of your account.",
        "value": "accountPurpose",
        "question_type": "single_choice",
        "position": 2,
        "is_optional": false,
        "id": "3f51ece0-cf4f-4dfb-a86f-b635cec968b8",
        "questionnaire_version_id": "9680a1a2-811e-40bf-96e7-14aac0359f36",
        "options": [
          {
            "label": "Trade crypto",
            "value": "tradeCrypto",
            "position": 1,
            "id": "84354bbd-fa2b-453a-852c-d67482147937",
            "question_id": "3f51ece0-cf4f-4dfb-a86f-b635cec968b8"
          },
          {
            "label": "Convert crypto to fiat",
            "value": "convertCryptoToFiat",
            "position": 2,
            "id": "32a07d8e-c354-426b-8899-2ac8f5127af3",
            "question_id": "3f51ece0-cf4f-4dfb-a86f-b635cec968b8"
          },
          {
            "label": "Trade equities",
            "value": "tradeEquities",
            "position": 3,
            "id": "57d58f04-2e91-4a94-ab89-98b33bbc1778",
            "question_id": "3f51ece0-cf4f-4dfb-a86f-b635cec968b8"
          }
        ]
      },
      {
        "label": "Please provide Proof of Address document.",
        "value": "poaDocument",
        "question_type": "document",
        "position": 3,
        "is_optional": false,
        "id": "0b4e7db0-4ee2-4d74-b7c3-d0500497628c",
        "questionnaire_version_id": "9680a1a2-811e-40bf-96e7-14aac0359f36",
        "options": []
      }
    ]
  }
}

Description of Objects

Below are the core objects related to the Questionnaire mechanism and their field descriptions.

Questionnaire

A Questionnaire represents a collection of questions to be answered by an entity (e.g., person or corporate).

Field	Type	Description
id	UUID	Unique identifier of the questionnaire.
name	String	Name given to the questionnaire.
description	String	Short description of the questionnaire’s purpose.
owner_type	String	Defines which entity type can answer it. One of: person, corporate.
owner_type_id	UUID or NULL	If provided, questionnaire applies to a specific entity instance.
is_generic	Boolean	Indicates whether the questionnaire is generic (applies to all) or specific (applies to one entity).
is_published	Boolean	Indicates whether the questionnaire is active and can be answered.
created_at	DateTime	Timestamp of creation.
data	QuestionnaireVersion	Contains versioned questionnaire structure with questions.

Questionnaire Version

Each questionnaire can have multiple versions. A version defines the exact structure (questions, options, types, order).

Field	Type	Description
id	UUID	Unique ID of the questionnaire version.
version_number	Integer	Incremental version number (e.g., 1, 2, 3).
questionnaire_id	String	References the parent questionnaire.
created_at	DateTime	Timestamp when this version was created.
questions	Array[Question]	List of questions that make up this version.

Question

Defines a single question inside a questionnaire.

Field	Type	Description
id	UUID.	Unique identifier of the question.
label	String	The text displayed to the end user.
value	String	A machine-readable key used internally (stable even if label changes).
question_type	String	Specifies the expected input type: text integer bool single_choice multiple_choice document multiple_documents
is_optional	boolean	Indicates if answering the question is optional.
position	Integer	Order in which the question should be displayed.
options	Array[QuestionOption]	Possible answers for choice-based questions. Empty for other types.

Question Option

Represents a single selectable option for single_choice or multiple_choice questions.

Field	Type	Description
id	UUID	Unique identifier of the option.
label	String	User-facing text for this option.
value	String	Internal machine-readable key for logic or integrations.
position	Integer	Position/order of the option in the list.
question_id	UUID.	References the question this option belongs to.