---
updatedAt: 2026-09-29T09:29:35.000Z
agentTools:
projectIndex: https://docs.sumsub.com/llms.txt
---
# Add applicant action questionnaire
# Table of contents
* [Overview](#overview)
* [Required permissions](#required-permissions)
* [Add images to questionnaires](#add-images-to-questionnaires)
* [Request example](#request-example)
* [Examples of different item types](#examples-of-different-item-types)
* [Text types](#text-types)
* [Variant types](#variant-types)
* [Phone type](#phone-type)
* [Country select types](#country-select-types)
* [Date types](#date-types)
* [File upload types](#file-upload-types)
* [Consent (Agreement) type](#consent-agreement-type)
* [Optional question without answer](#optional-question-without-answer)
* [Questionnaire arguments](#questionnaire-arguments)
* [sections element fields](#sections-element-fields)
* [items element fields](#items-element-fields)
* [Response explained](#response-explained)
* [Response examples](#response-examples)
# Overview
Use this method to add a questionnaire completed by the applicant to a specific applicant action.
Each subsequent request with questionnaire answer will overwrite the existing answer for that applicant action. This enables you to update the questionnaire answers by repeatedly calling this method.
However, if you do not include some of the answers from the previous request, those missing answers will also be overwritten and become empty.
## Required permissions
To use this method, your [app token](https://docs.sumsub.com/sumsub/docs/app-tokens) must have the **Change applicant's personal data** [permission](https://docs.sumsub.com/sumsub/docs/user-roles#permissions).
# Add images to questionnaires
This method allows you to attach images to a questionnaire. To proceed, follow these steps:
1. [Create an applicant action](https://docs.sumsub.com/sumsub/reference/create-applicant-action) using a level that includes a questionnaire. It is not required to submit questionnaire answers during this step.
2. [Upload image(s) to the applicant action](https://docs.sumsub.com/sumsub/reference/add-images-to-applicant-actions).
3. Use the method described on this page to link the previously uploaded image(s) to the questionnaire within the applicant action.
### Attention
- Questionnaire data must be submitted as raw JSON in the request body.
- Ensure that the JSON structure and questionnaire arguments comply with the required format as [described here](#questionnaire-arguments).
- Always provide a valid questionnaire `id` that exists under your client key.
# Request example
The following is a request example with possible answers to questions. For possible questionnaire attributes, refer to the tables below.
```curl
curl -X POST \
'https://api.sumsub.com/resources/applicantActions/6851645d0fa781263c000000/questionnaires' \
-H 'Content-Type: multipart/form-data' \
-H 'X-App-Token: ' \
-H 'X-App-Access-Sig: ' \
-H 'X-App-Access-Ts: ' \
-d '{
"id":"testQuestionnaire",
"sections":{
"section1Id":{
"items":{
"dateId":{
"value":"2024-10-10"
},
"phoneNumberId":{
"value":"+447400123456"
},
"shortAnswerWithFormat":{
"value":"john@doe.com"
},
"countryId":{
"value":"GBR"
},
"multiplecountryIds":{
"values":[
"PRT",
"ESP"
]
},
"shortAnswerId":{
"value":"John Doe"
}
}
},
"section2Id":{
"items":{
"dropdownId":{
"value":"drop_option1Id"
},
"paragraphId":{
"value":"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud "
},
"dateAndTimeId":{
"value":"2024-10-15T16:07"
},
"checkboxesId":{
"values":[
"check_option2Id"
]
},
"multichoiceId":{
"value":"radio_option1Id"
}
}
},
"section3Id":{
"items":{
"consentId":{
"value":"true"
},
"fileUploadId":{
"value":"381914678"
},
"multiFileUploadId":{
"values":[
"1164252192",
"1041427802"
]
}
}
}
}
}'
```
# Examples of different item types
Below, you can find the examples of different item types (question types) that can be submitted within a questionnaire structure in the request.
To understand the difference between the answer types, refer to [this page](https://docs.sumsub.com/sumsub/docs/create-questionnaire#question-types).
### Text types
```json Short answer
// Example of the questionnaire with the `short answer` item type.
{
"id":"questionnaireIdTest",
"sections":{
"section1":{
"items":{
"shortAnswerWithFormat":{
"value":"john@doe.com"
},
"shortAnswerId":{
"value":"John Doe"
}
}
}
}
}
```
```json Paragraph
// Example of the questionnaire with the `paragraph` item type.
{
"id":"questionnaireIdTest",
"sections":{
"section1":{
"items":{
"paragraphId":{
"value":"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis"
}
}
}
}
}
```
### Variant types
```json Checkboxes
// Example of the questionnaire with the `checkboxes` item type.
{
"id":"questionnaireIdTest",
"sections":{
"section1":{
"items":{
"checkboxesId":{
"values":[
"check_option2Id"
]
}
}
}
}
}
```
```json Multiple choice
// Example of the questionnaire with the `multi-choice` item type.
{
"id":"questionnaireIdTest",
"sections":{
"section1":{
"items":{
"multichoiceId":{
"value":"radio_option1Id"
}
}
}
}
}
```
```json Dropdown
// Example of the questionnaire with the `dropdown` item type.
{
"id":"questionnaireIdTest",
"sections":{
"section1":{
"items":{
"dropdownId":{
"value":"drop_option1Id"
}
}
}
}
}
```
### Phone type
```json Phone number
// Example of the questionnaire with the `phone` item type.
{
"id":"questionnaireIdTest",
"sections":{
"section1":{
"items":{
"phoneNumberId":{
"value":"+447400123456"
}
}
}
}
}
```
### Country select types
```json Single country
// Example of the questionnaire with the `country` item type.
{
"id":"questionnaireIdTest",
"sections":{
"section1":{
"items":{
"countryId":{
"value":"ALB"
}
}
}
}
}
```
```json Multiple countries
// Example of the questionnaire with the `multiple countries` item type.
{
"id":"questionnaireIdTest",
"sections":{
"section1":{
"items":{
"multipleCitizenshipCountryIds":{
"values":[
"AFG",
"ESP"
]
}
}
}
}
}
```
### Date types
```json Date
// Example of the questionnaire with the `date` item type.
{
"id":"questionnaireIdTest",
"sections":{
"section1":{
"items":{
"dateId":{
"value":"2024-10-10"
}
}
}
}
}
```
```json Date and time
// Example of the questionnaire with the `date-time` item type.
{
"id":"questionnaireIdTest",
"sections":{
"section1":{
"items":{
"dateAndTimeId":{
"value":"2024-10-15T16:07"
}
}
}
}
}
```
### File upload types
```json Single file
// Example of the questionnaire with the `file upload` item type.
{
"id":"questionnaireIdTest",
"sections":{
"section1":{
"items":{
"fileUploadId":{
"value":"381914678"
}
}
}
}
}
```
```json Multi upload
// Example of the questionnaire with the `multi file upload` item type.
{
"id":"questionnaireIdTest",
"sections":{
"section1":{
"items":{
"multiFileUploadId":{
"values":[
"1164252192",
"1041427802"
]
}
}
}
}
}
```
### Consent (Agreement) type
```json Consent
// Example of the questionnaire with the `consent` item type.
{
"id":"questionnaireIdTest",
"sections":{
"section1":{
"items":{
"consentId":{
"value":"true"
}
}
}
}
}
```
### Optional question without answer
If the question is optional, you can ignore this field or pass it without any value.
For example, in the case below, the `dateId` value is not specified and the `phoneNumberId` field is not provided.
```json Optional question without answer
{
"id":"questionnaireIdTest",
"sections":{
"section1":{
"items":{
"dateId":{},
"countryId":{
"value":"ALB"
},
"shortAnswerId":{
"value":"John Doe"
}
}
}
}
}
```
# Questionnaire arguments
The following are the root-level arguments required for each questionnaire:
[block:parameters]
{
"data": {
"h-0": "Field",
"h-1": "Value type",
"h-2": "Description",
"0-0": "`id`",
"0-1": "String",
"0-2": "Attribute value: unique identifier of the questionnaire. You assign this ID to the questionnaire when [creating it](https://docs.sumsub.com/sumsub/docs/questionnaire-get-started#create-questionnaire).",
"1-0": "`sections`",
"1-1": "[Object](#sections-element-fields)",
"1-2": "Includes the objects each of those is a separate [group of questions](https://docs.sumsub.com/sumsub/docs/questionnaire-get-started#add-questionnaire-section) added to the questionnaire. \n \nA section object has an ID representing the section given when the questionnaire was created. Each section consists of items (single questions), and has its own score based on the score of the items included."
},
"cols": 3,
"rows": 2,
"align": [
"left",
"left",
"left"
]
}
[/block]
> 📘 Note
>
> Each questionnaire `ID` attribute should be unique. If you intend to change the questionnaire structure, IDs should not be reused.
## `sections` element fields
The following table describes the `sections` attributes.
| Field | Value type | Description |
| ------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Object | Attribute key: unique section identifier. Attribute value contains an `items` object. |
| `items` | [Object](#items-element-fields) | Attribute value includes the objects each of those stands for a [single question](https://docs.sumsub.com/sumsub/docs/questionnaire-get-started#add-question) added to the questionnaire, and has an ID—item identifier—representing this question. |
## `items` element fields
The `items` object contains internal objects where each object stands for a single question added to the questionnaire, and has the attributes described in the table below.
| Field | Value type | Description | Supported values |
| :------- | :--------------- | :----------------------------------------------------------------------------------------------------------------- | :-------------------------- |
| `id` | Object | Attribute key: unique item identification number. Attribute value includes either a `value` or `values` attribute. | Any unique item identifier. |
| `value` | String | Contains the value that represents an answer to a question. | Any string value. |
| `values` | Array of strings | Contains the values that represent multiple answers to a question (for example, for checkboxes). | Any string values. |
### Notes
To associate previously uploaded image(s) with a questionnaire:
- Retrieve the `imageId` from the response after [uploading the image(s) to the applicant action](https://docs.sumsub.com/sumsub/reference/add-images-to-applicant-actions).
- Insert that `imageId` into the `value` or `values` field of the corresponding questionnaire item.
# Response explained
The response is a JSON file that includes the questionnaire structure. For more details and descriptions of the questionnaire element fields, refer to [this page](https://docs.sumsub.com/sumsub/reference/get-applicant-data#questionnaires-element-fields).
# Response examples
If the request is successfully sent and processed, you will get a response like the one below.
```json
{
"questionnaires": [
{
"id":"testQuestionnaire",
"sections":{
"section1Id":{
"items":{
"dateId":{
"value":"2024-10-10"
},
"phoneNumberId":{
"value":"+447400123456"
},
"shortAnswerWithFormat":{
"value":"john@doe.com"
},
"countryId":{
"value":"GBR"
},
"multipleCountryIds":{
"values":[
"PRT",
"ESP"
]
},
"shortAnswerId":{
"value":"John Doe"
}
}
},
"section2Id":{
"items":{
"dropdownId":{
"value":"drop_option1Id"
},
"paragraphId":{
"value":"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud "
},
"dateAndTimeId":{
"value":"2024-10-15T16:07"
},
"checkboxesId":{
"values":[
"check_option2Id"
]
},
"multichoiceId":{
"value":"radio_option1Id"
}
}
},
"section3Id":{
"items":{
"consentId":{
"value":"true"
},
"fileUploadId":{
"value":"381914678"
},
"multiFileUploadId":{
"values":[
"1164252192",
"1041427802"
]
}
}
}
}
}
]
}
```
If the request fails, you will receive an HTTP response containing an error code along with a message explaining the error. For example:
```json
{
"description": "Malformed data provided in the request",
"code": 400,
"correlationId": "6830d5fa604f8bd422c9aad2affa371c"
}
```
### Attention
If the request payload includes applicant answers that do not conform to the structure of the questionnaire configured for the associated level, the API will return an error in the response.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "sumsub-api",
"version": "1.0"
},
"servers": [
{
"url": "https://api.sumsub.com"
}
],
"components": {
"securitySchemes": {
"sec0": {
"type": "apiKey",
"name": "X-App-Token",
"in": "header",
"x-default": ""
}
}
},
"security": [
{
"sec0": []
}
],
"paths": {
"/resources/applicantActions/{actionId}/questionnaires": {
"post": {
"summary": "Add applicant action questionnaire",
"description": "",
"operationId": "add-applicant-action-questionnaire",
"parameters": [
{
"name": "actionId",
"in": "path",
"description": "Unique applicant action identifier in the Sumsub system.
You can get this identifier in response to [action submission](https://docs.sumsub.com/sumsub/reference/create-applicant-action) or by calling [this method](https://docs.sumsub.com/sumsub/reference/get-applicant-actions).",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"RAW_BODY": {
"type": "string",
"description": "Questionnaire data to be submitted as raw JSON",
"format": "json"
}
}
}
}
}
},
"deprecated": false
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": true,
"proxy-enabled": true
},
"x-readme-fauxas": true
}
```