Import questionnaire data via API
Sumsub’s Questionnaire is a multifaceted tool used for collecting applicant data, calculating risk scoring, and building flexible verification flows in Workflow Builder and Transaction Monitoring.
When working with Questionnaire, you can send questionnaire answers via API in addition to the SDK-based verification option.
Why do you need to upload questionnaires via API
The following method might benefit all scenarios when you use your own SDK and custom questionnaires, and need to handle risk scoring while storing that data directly in applicant profiles within the Sumsub system.
Send questionnaire data using API
To import questionnaires via API, you need to create a questionnaire and add this step to a required verification level. Once done, you will be able to send us a filled out questionnaire and perform required checks.
The instructions described below work the same for both Individuals and Companies applicants.
Step 1. Add questionnaire.
You can add a questionnaire by creating it from scratch or by importing an existing one as JSON.
There is an instruction on how to create a questionnaire in the Dashboard:
- Go to Integrations, navigate to the Questionnaires section, and click Create questionnaire.
- Give it a name and optional description.
- View the generated questionnaire ID and edit it if needed. This ID is a crucial parameter required for API interactions.
- Set up questionnaire content as per documentation.
To import a questionnaire, follow these steps:
- Go to the Questionnaires page and click Import questionnaire on the top right.
- Paste the questionnaire structure and select Create questionnaire.
Tip
- Find more information about managing questionnaires and view a sample questionnaire in JSON format in this article.
- Perform test imports on smaller questionnaires to minimize errors.
Questionnaire example
Here is is an example of a questionnaire in JSON format.
{
"id": "questionnaireIdTest",
"title": "Full questionnaire",
"desc": "Questionnaire description",
"modifiable": null,
"sections": [
{
"id": "section1",
"title": "Section 1",
"localizedTitle": {
"values": [
{
"lang": "en",
"value": "Section 1"
},
{
"lang": "de",
"value": "Abschnitt 1"
}
]
},
"desc": "Section 1 desription",
"condition": "",
"showCondition": null,
"items": [
{
"id": "shortAnswerId",
"title": "Short answer",
"desc": "Question 1",
"type": "text",
"required": true,
"format": null,
"condition": null,
"showCondition": null,
"placeholder": "Type something"
},
{
"id": "shortAnswerWithFormat",
"title": "Short answer with Email format",
"desc": "Question 2",
"type": "text",
"required": true,
"format": "email",
"condition": null,
"showCondition": null,
"placeholder": "Type something"
},
{
"id": "countryId",
"title": "Country",
"desc": "Question 3",
"type": "countrySelect",
"required": true,
"format": null,
"condition": null,
"showCondition": null,
"placeholder": "Select country"
},
{
"id": "phoneNumberId",
"title": "Phone number",
"desc": "Question 4",
"type": "phone",
"required": true,
"format": null,
"condition": null,
"showCondition": null,
"placeholder": "Type something"
},
{
"id": "dateId",
"title": "Date",
"desc": "Question 5",
"type": "date",
"required": true,
"format": null,
"condition": null,
"showCondition": null,
"placeholder": "Type something"
}
],
"delimiter": null
},
{
"id": null,
"title": null,
"desc": null,
"condition": null,
"showCondition": null,
"items": null,
"delimiter": true
},
{
"id": "section2Id",
"title": "Section 2",
"desc": "Section 2 description",
"condition": null,
"showCondition": null,
"items": [
{
"id": "paragraphId",
"title": "Paragraph",
"desc": "Question 6",
"type": "textArea",
"required": null,
"format": null,
"condition": null,
"showCondition": null,
"placeholder": "Type something"
},
{
"id": "dateAndTimeId",
"title": "Date and time",
"desc": "Question 7",
"type": "dateTime",
"required": null,
"format": null,
"condition": null,
"showCondition": null,
"placeholder": "Type something"
},
{
"id": "dropdownId",
"title": "Dropdown",
"desc": "Question 8",
"type": "selectDropdown",
"required": true,
"format": null,
"condition": null,
"showCondition": null,
"placeholder": "Type something",
"options": [
{
"value": "drop_option1Id",
"title": "Option 1 dropdown",
"localizedTitle": {
"values": [
{
"lang": "en",
"value": "Option 1 dropdown"
}
]
},
"score": 5.0
},
{
"value": "drop_option2Id",
"title": "Option 2 dropdown",
"localizedTitle": {
"values": [
{
"lang": "en",
"value": "Option 2 dropdown"
}
]
},
"score": 10.0
}
]
},
{
"id": "checkboxesId",
"title": "Checkboxes",
"desc": "Question 9",
"type": "multiSelect",
"required": true,
"format": null,
"condition": null,
"showCondition": null,
"placeholder": "",
"options": [
{
"value": "check_option1Id",
"title": "Option 1 checkbox",
"localizedTitle": {
"values": [
{
"lang": "en",
"value": "Option 1 checkbox"
}
]
},
"score": 6.0
},
{
"value": "check_option2Id",
"title": "Option 2 checkbox",
"localizedTitle": {
"values": [
{
"lang": "en",
"value": "Option 2 checkbox"
}
]
},
"score": 12.0
}
]
},
{
"id": "multichoiceId",
"title": "Multichoice",
"desc": "Question 10",
"type": "select",
"required": true,
"format": null,
"condition": null,
"showCondition": null,
"placeholder": "",
"options": [
{
"value": "radio_option1Id",
"title": "Option 1 radio",
"localizedTitle": {
"values": [
{
"lang": "en",
"value": "Option 1 radio"
}
]
},
"score": 7.0
},
{
"value": "radio_option2Id",
"title": "Option 2 radio",
"localizedTitle": {
"values": [
{
"lang": "en",
"value": "Option 2 radio"
}
]
},
"score": 14.0
}
]
}
],
"delimiter": null
},
{
"id": "section3Id",
"title": "Section 3",
"desc": "Section 3 description",
"condition": null,
"showCondition": null,
"items": [
{
"id": "fileUploadId",
"title": "File upload",
"desc": "Question 11",
"type": "fileAttachment",
"required": true,
"format": null,
"condition": null,
"showCondition": null,
"placeholder": ""
},
{
"id": "multiFileUploadId",
"title": "Multi file upload",
"desc": "Question 12",
"type": "multiFileAttachments",
"required": null,
"format": "max_value:5",
"condition": null,
"showCondition": null,
"placeholder": ""
},
{
"id": "consentId",
"title": "Consent",
"desc": "Question 13",
"type": "bool",
"required": true,
"format": null,
"condition": null,
"showCondition": null,
"placeholder": "Type something"
}
],
"delimiter": null
}
]
}
Step 2. Create verification level with questionnaire step.
Add a verification level including the Questionnaire step:
- In the Dashboard, open the Individuals/Companies page and click Create level.
- Include the Questionnaire step in the level and select the created questionnaire from the list.
- Configure the verification level as needed.
Step 3. Add applicant
You can create a new applicant profile assigned to the verification level you set up earlier, or change the verification level for an existing profile.
Create a new applicant profile:
- Add a new applicant using the Create applicant method.
- Make sure that the
levelNameparameter includes the verification level with the Questionnaire step. - Provide the rest of the parameters as per documentation of the method.
To change a verification level for an existing applicant profile, use the Change required documents API method.
Step 4. Fill out questionnaire and send its data
Complete the questionnaire and send its data via API:
- Use the questionnaire structure of this request example to prepare the API request for filling out a questionnaire.
- Get the attributes of your questionnaire by one of the following methods:
- Open the Questionnaires page, find the necessary questionnaire, and select Export.
- Open the Questionnaires page, click on any questionnaire from the list, and find all the necessary IDs in editing mode.
- Fill out the questionnaire.
- Send the completed request using the Add applicant questionnaire method.
Note
- If there is any data in an applicant’s profile that you want to use to prefill the questionnaire, you can retrieve it using the Get applicant data method.
- Risk score (if applicable) and questionnaire answers will be automatically applied upon completion of the Add applicant questionnaire API request.
- Applicants with access to the SDK will still be able to review and modify the questionnaire responses during the fill-out stage.
Request example
This is a full request example for the Add applicant questionnaire method.
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"
]
}
}
}
}
}'
Step 5. Request applicant check
Once you send the questionnaire data, the applicant profile will have the Documents requested status.
To complete verification, use the Request applicant check method.
Note
- If there is only the Questionnaire step in the verification level, the applicant’s status will switch to Approved automatically.
- If there are any other checks included in the verification level, the status will change in accordance with the results received during these checks.
Step 6. View results
After completing verification, you can view the questionnaire and its results in the Dashboard.
- Go to the Applicants page and select a profile from the list.
- In the applicant profile, navigate to the User Verification tab and find the Questionnaire section.
Updated 3 days ago