---
updatedAt: 2026-09-29T07:58:18.000Z
agentTools:
projectIndex: https://docs.sumsub.com/llms.txt
---
# Add applicant questionnaire
# Table of contents
* [Overview](#overview)
* [Required permissions](#required-permissions)
* [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)
* [Errors list](#errors-list)
# Overview
Use this method to add a questionnaire completed by the applicant to their personal profile.
### Important
- Make sure to always provide a questionnaire `id` that exists on your client key.
- All subsequent requests with questionnaire answers overwrite the current applicant answers.
- Each element of an array in the request body must be a non-null string. Submitting an array that contains a null element (for example, `["file1.pdf", null])` is rejected with a `400` error. An empty array (`[]`) and an omitted array are both accepted.
## 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).
# Request example
The following is a complete request example with all possible answers to questions. For possible questionnaire arguments, refer to the [tables below](#questionnaire-arguments).
### Note
If a questionnaire ID is provided, the system automatically determines which step it belongs to and loads it accordingly. There is no need to specify the individual Questionnaire step in the request.
```curl
curl -X POST \
'https://api.sumsub.com/resources/applicants/63e096c51b6b400012df0023/questionnaires' \
-H 'X-App-Token: ' \
-H 'X-App-Access-Sig: ' \
-H 'X-App-Access-Ts: ' \
-d '{
"id":"questionnaireIdTest",
"sections":{
"section1Id":{
"items":{
"shortAnswerId":{
"value":"John Doe"
},
"shortAnswerWithFormatId":{
"value":"john@doe.com"
},
"countryId":{
"value":"ALB"
},
"phoneNumberId":{
"value":"+447400123456"
},
"dateId":{
"value":"2024-10-10"
}
}
},
"section2Id":{
"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 nostrud "
},
"dateAndTimeId":{
"value":"2024-10-15T16:07"
},
"dropdownId":{
"value":"drop_option1Id"
},
"checkboxesId":{
"values":[
"check_option2Id"
]
},
"multichoiceId":{
"value":"radio_option1Id"
}
}
},
"section3Id":{
"items":{
"fileUploadId":{
"value":"381914678"
},
"multiFileUploadId":{
"values":[
"1164252192",
"1041427802"
]
},
"consentId":{
"value":"true"
},
"multiCountrySelectId":{
"values":[
"AFG",
"ESP"
]
}
}
}
}
}'
```
## 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. |
# 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": "questionnaireIdTest",
"sections": {
"section1Id": {
"score": 0.0,
"items": {
"shortAnswerWithFormatId": {
"value": "john@doe.com"
},
"dateId": {
"value": "2024-10-10"
},
"phoneNumberId": {
"value": "+447400123456"
},
"countryId": {
"value": "ALB",
"score": 0.0,
"dataScores": [
{
"value": "ALB",
"score": 0.0
}
]
},
"shortAnswerId": {
"value": "John Doe"
}
}
},
"section2Id": {
"score": 24.0,
"items": {
"dropdownId": {
"value": "drop_option1Id",
"score": 5.0,
"dataScores": [
{
"value": "drop_option1Id",
"score": 5.0
}
]
},
"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"
],
"score": 12.0,
"dataScores": [
{
"value": "check_option2Id",
"score": 12.0
}
]
},
"multichoiceId": {
"value": "radio_option1Id",
"score": 7.0,
"dataScores": [
{
"value": "radio_option1Id",
"score": 7.0
}
]
}
}
},
"section3Id": {
"score": 6.0,
"items": {
"consentId": {
"value": "true"
},
"fileUploadId": {
"value": "381914678"
},
"multiFileUploadId": {
"values": [
"1164252192",
"1041427802"
]
},
"multiCountrySelectId": {
"values": [
"AFG",
"ESP"
],
"score": 6.0,
"dataScores": [
{
"value": "AFG",
"score": 6.0
},
{
"value": "ESP",
"score": 0.0
}
]
}
}
}
},
"score": 30.0
}
]
}
```
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"
}
```
## 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). |
| `400` | **Null value in item values** | An item `values` array contains a `null` element. The response description is `values[].` must not be null must not be null. |
# 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/applicants/{applicantId}/questionnaires": {
"post": {
"summary": "Add applicant questionnaire",
"description": "",
"operationId": "add-applicant-questionnaire",
"parameters": [
{
"name": "applicantId",
"in": "path",
"description": "Unique applicant identifier in the Sumsub system.
This identifier is a random combination of 24 digits and lowercase Latin characters. It is automatically generated when the applicant is created on the Sumsub side, and can be found in the [Dashboard](https://cockpit.sumsub.com/checkus/#/applicants/company?limit=10&page=0).
If the `applicantId` is unknown to you, use the [Get applicant data (externalUserId)](https://docs.sumsub.com/sumsub/reference/get-applicant-data-via-externaluserid) method to fetch it.",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"RAW_BODY": {
"type": "string",
"format": "json"
}
}
}
}
}
},
"deprecated": false
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": true,
"proxy-enabled": true
},
"x-readme-fauxas": true
}
```