post https://api.sumsub.com/resources/applicantActions//questionnaires
Table of contents
- Overview
- Add images to questionnaires
- Request example
- Examples of different item types
- Questionnaire arguments
- Response explained
- Response examples
Overview
Use this method to add a questionnaire completed by the applicant to a specific applicant action.
Each subsequent request with questionnaire answers will overwrite the existing responses for that applicant. This enables you to update the questionnaire answers by repeatedly calling this method.
Add images to questionnaires
This method allows you to attach images to a questionnaire. To proceed, follow these steps:
- Create an applicant action using a level that includes a questionnaire. It is not required to submit questionnaire answers during this step.
- Upload image(s) to the applicant action.
- 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.
- Always provide a valid questionnaire
idthat 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 -X POST \
'https://api.sumsub.com/resources/applicantActions/6851645d0fa781263c788676/questionnaires' \
-d '{
"id":"testQuestionnaire",
"sections":{
"section1Id":{
"items":{
"dateId":{
"value":"2024-10-10"
},
"phoneNumberId":{
"value":"+447400123456"
},
"shortAnswerWithFormat":{
"value":"[email protected]"
},
"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.
Text types
// Example of the questionnaire with the `short answer` item type.
{
"id":"testQuestionnaire",
"sections":{
"section1":{
"items":{
"shortAnswerWithFormat":{
"value":"[email protected]"
},
"shortAnswerId":{
"value":"John Doe"
}
}
}
}
}
// Example of the questionnaire with the `paragraph` item type.
{
"id":"testQuestionnaire",
"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
// Example of the questionnaire with the `checkboxes` item type.
{
"id":"testQuestionnaire",
"sections":{
"section1":{
"items":{
"checkboxesId":{
"values":[
"check_option2Id"
]
}
}
}
}
}
// Example of the questionnaire with the `multi-choice` item type.
{
"id":"testQuestionnaire",
"sections":{
"section1":{
"items":{
"multichoiceId":{
"value":"radio_option1Id"
}
}
}
}
}
// Example of the questionnaire with the `dropdown` item type.
{
"id":"testQuestionnaire",
"sections":{
"section1":{
"items":{
"dropdownId":{
"value":"drop_option1Id"
}
}
}
}
}
Phone type
// Example of the questionnaire with the `phone` item type.
{
"id":"testQuestionnaire",
"sections":{
"section1":{
"items":{
"phoneNumberId":{
"value":"+447400123456"
}
}
}
}
}
Country select types
// Example of the questionnaire with the `country` item type.
{
"id":"testQuestionnaire",
"sections":{
"section1":{
"items":{
"countryId":{
"value":"GBR"
}
}
}
}
}
// Example of the questionnaire with the `multiple countries` item type.
{
"id":"testQuestionnaire",
"sections":{
"section1":{
"items":{
"multipleCitizenshipCountryIds":{
"values":[
"PRT",
"ESP"
]
}
}
}
}
}
Date types
// Example of the questionnaire with the `date` item type.
{
"id":"testQuestionnaire",
"sections":{
"section1":{
"items":{
"dateId":{
"value":"2024-10-10"
}
}
}
}
}
// Example of the questionnaire with the `date-time` item type.
{
"id":"testQuestionnaire",
"sections":{
"section1":{
"items":{
"dateAndTimeId":{
"value":"2024-10-15T16:07"
}
}
}
}
}
File upload types
// Example of the questionnaire with the `file upload` item type.
{
"id":"testQuestionnaire",
"sections":{
"section1":{
"items":{
"fileUploadId":{
"value":"381914678"
}
}
}
}
}
// Example of the questionnaire with the `multi file upload` item type.
{
"id":"testQuestionnaire",
"sections":{
"section1":{
"items":{
"multiFileUploadId":{
"values":[
"1164252192",
"1041427802"
]
}
}
}
}
}
Note
The items of upload types contain the
imageIdvalues that you can use to fetch the uploaded files.
Consent (Agreement) type
// Example of the questionnaire with the `consent` item type.
{
"id":"testQuestionnaire",
"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.
{
"id":"testQuestionnaire",
"sections":{
"section1":{
"items":{
"dateId":{},
"countryId":{
"value":"GBR"
},
"shortAnswerId":{
"value":"John Doe"
}
}
}
}
}
Questionnaire arguments
The following are the root-level arguments required for each questionnaire:
| Field | Value type | Description |
|---|---|---|
id | String | Attribute value: unique identifier of the questionnaire. You assign this ID to the questionnaire when creating it. |
sections | Object | Includes the objects each of those is a separate group of questions added to the questionnaire. A 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. |
Note
Each questionnaire
IDattribute should be unique. If you intend to change the questionnaire structure, IDs should not be reused.
sections element fields
sections element fieldsThe 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 | Attribute value includes the objects each of those stands for a single question added to the questionnaire, and has an ID—item identifier—representing this question. |
items element fields
items element fieldsThe 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 (e.g. for checkboxes). | Any string values. |
Notes
To associate previously uploaded image(s) with a questionnaire:
- Retrieve the
imageIdfrom the response after uploading the image(s) to the applicant action.- Insert that
imageIdinto thevalueorvaluesfield of the corresponding questionnaire item.
Response explained
The response is a JSON file that includes the applicant action, questionnaire and attached images structure. For more details and descriptions of the questionnaire element fields, refer to this page.
Response examples
If the request is successfully sent and processed, you will get a response like the one below.
{
"id":"6851645d0fa781263c788676",
"createdAt":"2025-06-17 12:49:33",
"clientId":"yourId",
"externalActionId":"yourActionId",
"applicantId":"683448fbbcd8b9ba6ca51f24",
"type":"paymentMethod",
"review":{
"reviewId":"pjjDF",
"attemptId":"ZPMWb",
"attemptCnt":0,
"levelName":"test_level",
"levelAutoCheckMode":"standard",
"createDate":"2025-06-17 12:49:33+0000",
"reviewStatus":"init"
},
"requiredIdDocs":{
"docSets":[
{
"idDocSetType":"QUESTIONNAIRE",
"questionnaireDefId":"testfileupload"
}
]
},
"questionnaires":[
{
"id":"testQuestionnaire",
"sections":{
"section1Id":{
"items":{
"dateId":{
"value":"2024-10-10"
},
"phoneNumberId":{
"value":"+447400123456"
},
"shortAnswerWithFormat":{
"value":"[email protected]"
},
"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"
]
}
}
}
}
}
],
"images":[
{
"id":"66bb6c71546bfc57cffe92a8",
"addedDate":"2024-08-13 14:23:45",
"creatorClientId":"yourId",
"imageHash":"64d2f3aa8da8a98fffaf751a9c323981474f6375",
"imageFileName":"image-name.png",
"resizedImageId":603758274,
"mimeType":"png",
"sigHash":"3809bc3c-831d-4be3-8cee-1684553beffe",
"imageId":381914678,
"fileSize":1362,
"actualResolution":{
"width":192,
"height":192
},
"answer":"GREEN",
"idDocDef":{
"country":"GBR",
"idDocType":"PAYMENT_SOURCE"
},
"reviewResult":{
},
"attemptId":"teinm"
},
{
"id":"77bb6c71546bfc57cffe92a8",
"addedDate":"2024-08-13 14:25:45",
"creatorClientId":"yourId",
"imageHash":"55d2f3aa8da8a98fffaf751a9c323981474f6344",
"imageFileName":"image-name2.png",
"resizedImageId":222758274,
"mimeType":"png",
"sigHash":"4569bc3c-831d-4be3-8cee-1684553beffe",
"imageId":1164252192,
"fileSize":1362,
"actualResolution":{
"width":192,
"height":192
},
"answer":"GREEN",
"idDocDef":{
"country":"GBR",
"idDocType":"PAYMENT_SOURCE"
},
"reviewResult":{
},
"attemptId":"teinm"
},
{
"id":"88bb6c71546bfc57cffe92a8",
"addedDate":"2024-08-13 14:26:45",
"creatorClientId":"yourId",
"imageHash":"66d2f3aa8da8a98fffaf751a9c323981474f6366",
"imageFileName":"image-name3.png",
"resizedImageId":2021427802,
"mimeType":"png",
"sigHash":"2349bc3c-831d-4be3-8cee-1684553beffe",
"imageId":381914678,
"fileSize":1362,
"actualResolution":{
"width":192,
"height":192
},
"answer":"GREEN",
"idDocDef":{
"country":"GBR",
"idDocType":"PAYMENT_SOURCE"
},
"reviewResult":{
},
"attemptId":"teinm"
}
]
}
If the request fails, you will receive an HTTP response containing an error code along with a message explaining the error. For example:
{
"description": "Malformed data provided in the request",
"code": 400,
"correlationId": "6830d5fa604f8bd422c9aad2affa371c"
}