Table of contents
- Overview
- Request example
- Examples of different item types
- Questionnaire arguments
- Response explained
Overview
Use this method to add a questionnaire completed by the applicant to their personal profile.
Important
- Make sure to always provide a questionnaire
idthat exists on your client key.- All subsequent requests with questionnaire answers overwrite the current applicant answers.
Request example
The following is a complete request example with all possible answers to questions. For possible questionnaire arguments, refer to the tables below.
curl -X POST \
'https://api.sumsub.com/resources/applicants/63e096c51b6b400012df4500/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 attributes of each questionnaire:
| Field | Type | Description |
|---|---|---|
id | String | 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.
| Name | Type | Description |
|---|---|---|
id | String | Unique section identifier. |
items | Object | 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 | Type | Description | Supported values |
|---|---|---|---|
id | String | Unique item identification number. | 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. |
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.
Response examples
If the request is successfully sent and processed, you will get a response like the one below.
{
"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"
]
}
}
}
}
}
]
}
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"
}
Errors list
If you submit a valid request with the applicant answers in a structure that differs from the questionnaire attached to the level, the request will still be processed successfully, and no error will be returned in the response.
The Questionnaire section will include data for any matching fields (for example, score for the corresponding section). If no matching fields are found, the applicant questionnaire will be marked as completed but will not contain any answers.
The following table lists the most common error types that you may encounter.
| Code error | Title | Comment |
|---|---|---|
409 | Wrong ID | If the questionnaire ID provided in the id field differs from the questionnaire ID associated with the level. |
400 | Incorrect request structure | If the request body includes a questionnaire answer in the incorrect JSON section (for example, placing the answer within the questionnaires array). |