Questionnaire

Learn about onboarding questionnaires for seamless user information gathering.

Questionnaires let you collect additional information about your applicants (mostly businesses, traders, and owners of crypto wallets).

You can use questionnaires for the following purposes:

  • Collecting source of funds data
  • Collecting basic KYC data
  • Collecting onboarding KYC/KYB data
  • Determining PEP/HIO status
  • Determining trading experience
  • Gathering financial details(annual income / net worth)
  • Identifying the SoF (Source of Funds) / SoW (Source of Wealth) details: salary / real estate / investments
  • Identifying transaction amounts
  • Defining the beneficiary when an applicant is acting on someone's behalf
  • Gathering SoF (Source of Funds) / SoW (Source of Wealth) details

How it works

Questionnaires are usually filled in by applicants during verification. However, an operator who runs a video identification can also complete the questionnaire using the answers provided by the applicant.

A typical flow of working with questionnaires is as follows:

  1. You create a questionnaire and extend your verification level with a questionnaire step.
  2. Applicants pass verification in WebSDK or MobileSDK and answer your questions. Alternatively, an operator can complete the questionnaire on behalf of the applicant if needed.
  3. You review the submitted answers.
  4. You use the Workflow builder to assign an automated action to a specific answer if needed.

Create questionnaire

Questionnaires consist of sections. Each section may contain one or more items (questions) and allows you to group your questions into different areas of application, depending on your scenario.

To create a questionnaire:

  1. In the Dashboard, go to the Questionnaires page and click Create a questionnaire.
  2. Give a unique ID to your questionnaire. This field basically sets the name of your questionnaire.
  3. Provide a questionnaire title which would be shown at the top-middle when applicants pass the questionnaire and enter an optional description.
  4. Select the Allow users to edit questionnaires checkbox to allow your team members to change questionnaires.
  5. Click Add new section to add a questionnaire section.

📘

Note

To change questionnaires, your Dashboard account must be granted the Change personal data permission.

Add questionnaire section

Group your questions into independent sections; each section per set of questions. You can add as many sections as you need, depending on your scenario.

To create a question section:

  1. Provide a section title that you want to be shown to your applicants. For example, you may want to group your questions into several sections in case you want to collect answers from different areas. This means that you can create several sections, each of them having different titles.
  2. In the Section id field, review the automatically assigned identification number. You can use this number when specifying conditions. Mind that you cannot change this number manually.
  3. In the Section description field, enter an optional section description.
  4. In the Condition field, you can specify a condition that defines the way how the data in each section should be displayed and processed. Such a condition might be based on answers to certain questions or whether the questions is answered at all. You can combine conditions by using logical operators, such as AND (&&) and OR (||). To refer to questions, use the Section id and Item id variables in the format sectionid.itemid.
  5. Click Add new item to add a new question.

Add question

Specify question details. You can add as many questions as you need, depending on your scenario.

To specify questions:

  1. In the Item title field, enter a title for the question.
  2. In the Item id field, review the automatically assigned identification number. You can use this number when specifying conditions. Mind that you cannot change this number manually.
  3. In the Item description field, enter an optional item description.
  4. From the Type drop-down list, select a question type.
  5. Select the Required checkbox if you want to mark the question as required. This way, your applicants will not be able to skip the question.
  6. Click Additional settings if you want to extend the default settings.
  7. Click Add option if you want to define custom values and configure risk scoring. Available only if Type is select, selectDropdown or multiSelect.

Question types

Question types define the way the data should be collected. For example, if you want to receive some textual information from your applicants, you can select text. If you want to give your applicants the ability to select from different options, you can opt for select, selectDropdown or multiSelect.

Available question types include:

OptionDescription
textA simple text field.
textAreaAn expandable text area.
dateA date field in format mm/dd/yyyy.
dateTimeA calendar control that allows you to select date and time.
boolA single checkbox.
selectAn array of options. Creates radio buttons.
selectDropdownAn array of options. Creates a drop-down list.
multiSelectAn array of options. Creates check boxes.
countrySelectA drop-down list with available countries.
fileAttachmentAllows uploading a file as an attachment.

Settings

Additional settings let you set auxiliary parameters, such as logical conditions, formats, and custom placeholders.

Available settings include:

OptionDescription
ConditionA logical condition that defines the way how the data in each section should be displayed and processed. Such a condition is based on the answers to certain question or whether the question is answered at all. You can combine conditions by using logical operators, such as AND (&&) and OR (|). To refer to questions, use the Section id and Item id variables in the format sectionid.itemid.
FormatThis drop-down list is available when Type is either text or multiFileAttachments. Depending on which option is selected and while answering the questions, applicants must adhere to the format that you define here. For example, you can force your applicants to provide only numeric answers or answers that fall within the specified range using the min_value and max_value.
PlaceholderPlaceholder text shown in fields.

Options

Options let you configure risk scoring.

Available options include:

OptionDescription
ValueSets the value that you will get via the API after the applicant selects it.
TitleSets the number of points the applicant gets per answer. Accepts a numeric value.
Risk scoreUpon completion of the questionnaire, the system simply sums up the number of points according to the applicant's answers. The way the received points are interpreted is decided independently, depending on your scenario. The risk score feature does not affect verification results.

Add questionnaire to verification level

Each level consists of different check sequences (steps), depending on how you want your applicants to be verified. You can request applicants to complete a questionnaire as one of such steps.

To add a questionnaire to the verification level:

  1. Set up a verification level.
  2. Add a Questionnaire step and specify the questionnaire that you want to use for the level.
  3. Save your changes.

Review applicant answers

As soon as the applicant completes the questionnaire, all of the answers and uploaded files are added to their profile.

There are two ways of how to view the answers:

  • You can get the answers and files via this API method.
  • You can open the Applicants page and filter your applicants by the level name to which you assigned the questionnaire. Then select any applicant profile and open the Questionnaire section to see the submitted answers.

Manage questionnaires

Questionnaires are flexible; you can manage any of them in any of the following ways:

  • You can import and export a questionnaire as a JSON file.
  • You can change the existing questionnaire by altering its settings in a preferred way.
  • You can reset a questionnaire in case your applicants have already completed it and you want them to resubmit the answers. You can also reset a questionnaire by passing the questionnaire argument to this API method.
  • You can remove a questionnaire at any time in case you no longer need it.

Use workflow builder

Apart from collecting the applicant data, you can use questionnaires in your verification flows to assign an automated action to a specific answer. Such actions may include adding specific tags or changing the applicant risk level.

For example, you can create a flow that adds a medium risk label to all unemployed applicants aged between 35 and 45:

  1. Create a questionnaire that requests applicants to provide their employment status.
  2. Create a respective applicant tag.
  3. Start building your flow.
  4. Create the following condition: if Field: applicant.info.age -> greater than -> Value: 35 -> And -> Field: applicant.info.age -> less than -> Value: 45-> And -> Field: questionnaires.[your questionnaire name].[questionnaire section name].
  5. Proceed with setting up all the branches of your flow and publish it when done.

Questionnaire API

To get the results of the questionnaire step via API, use this method.

Items with the type of fileAttachment contain the imageId value that you can use to fetch the uploaded files.

The following is a response example:

{
  "id": "5e9a35d30a975a656d67d473",
  "createdAt": "2020-04-17 23:03:47",
  "clientId": "yourClientId",
  "inspectionId": "5e9a35d30a975a656d67d474",
  "externalUserId": "random-userId",
  "requiredIdDocs": {
    "docSets": [
      {
        "idDocSetType": "QUESTIONNAIRE",
        "questionnaireDefId" : "ExampleQuestionnaire"
      }
    ]
  },
  "review": {
    "elapsedSincePendingMs": 302957,
    "elapsedSinceQueuedMs": 25213,
    "createDate": "2020-04-17 23:05:46+0000",
    "reviewDate": "2020-04-17 23:10:49+0000",
    "startDate": "2020-04-17 23:10:24+0000",
    "reviewResult": {
      "reviewAnswer": "GREEN"
    },
    "reviewStatus": "completed"
  },
  "lang": "en",
  "type": "individual",
  "questionnaires": [
    {
      "id": "ExampleQuestionnaire",
      "sections": {
        "bankDetails": {
        "score" : 0.0,
          "items": {
            "2-1": {
              "value": null,
              "values": null
            },
            "2-2": {
              "value": null,
              "values": null
            },
            "2-3": {
              "value": null,
              "values": null
            },
            "2-4": {
              "value": null,
              "values": null
            },
            "2-5": {
              "value": null,
              "values": null
            },
            "2-6": {
              "value": null,
              "values": null
            },
            "2-7": {
              "value": null,
              "values": null
            },
            "2-8": {
              "value": null,
              "values": null
            }
          }
        },
        "withInstitution": {
          "score" : 0.2,
          "items": {
            "3-1": {
              "value": "e-wallet",
              "score" : 0.2
            }
          }
        },
        "fileAttachments": {
          "score" : 0.0,
          "items": {
            "firstFile": {
              "value": "2046918100", //imageId
              "values": null
            },
            "anotherFile": {
              "value": "2046918189", //imageId
              "values": null
            }
          }
        },
        "accountDetails": {
          "score" : 1.4,
          "items": {
            "1-2one": {
              "value": null,
              "values": null
            },
            "1-1": {
              "value": "Legal Name LTD"
            },
            "1-2": {
              "value": "two"
            },
            "1-2two": {
              "value": "sumsub.com"
            },
            "1-4": {
              "value": "no",
              "score" : 0.4
            },
            "1-5": {
              "value": "no",
              "score" : 1.0
            },
            "1-email": {
              "value": "[email protected]"
            },
            "1-country": {
              "value": "GBR"
            }
          }
        }
      },
    "score" : 1.6
    }
  ]
}

Definition attributes

The following table describes the questionnaireDef attributes.

NameTypeRequiredDescription
idStringYesA unique questionnaire identification number.
titleStringNoA questionnaire title.
descStringNoAn optional questionnaire description.
sectionsArrayYesAn array of questionnaire sections.

📘

Note

Each questionnaire ID attribute should be unique. If you intend to change the questionnaire structure, IDs should not be reused.

Section fields

The following table describes the sections attributes.

NameTypeRequiredDescription
idStringYesA unique section identification number.
titleStringNoA section title.
descStringNoAn optional section description.
conditionStringNoA condition that makes the section visible, depending on the value of specified sectionId.itemId={options.value}.
itemsArrayYesAn array of questionnaire items (data fields).

Item fields

The following table describes the items attributes.

NameTypeRequiredDescriptionSupported values
idStringYesA unique item identification number.Any unique item identifier.
titleStringNoData field title.Any string value.
descStringNoAn optional data field description.Any string value.
typeStringYesData field type.See Supported types of items.
requiredBooleanNoSets the data field as mandatory to fill.true or false.
formatStringNoThe format of the data field with validation.min:3, max:9 (sets min/max amount of symbols), email.
placeholderStringNoA placeholder for text data field.Any string value.
optionsArrayNoAn array of values to select from.[{"value": "someValue", "title": "Yes", "score": 0}]
conditionStringNoA condition that makes item show up.sectionId.itemId={options.value} ( Example: 1-Section.1-2=someValue )

Supported types of items

The following table describes the supported types of items.

ValueDescription
textA text field.
textAreaAn expandable text area.
dateDate field in format mm/dd/yyyy.
dateTimeShows the calendar with date and time fields.
boolA single checkbox.
selectAn array of options. Creates radio buttons.
selectDropdownAn array of options. Creates a drop-down list with selectable values.
multiSelectAn array of options. Creates multi-select of checkboxes.
countrySelectA drop-down list with available countries.
fileAttachmentAllows uploading a file to the applicant as an attachment.

Option attributes

The following table describes the options attributes.

NameTypeRequiredDescriptionSupported values
valueStringYesThe value that you will get via API as the option selected by the applicant.Any unique item identifier.
titleStringYesAn optional title that will be shown to the applicant.Any string value.
scoreDoubleNoAdds a value to the overall questionnaire scoring (score).Double value.

Questionnaire translations

You can change a questionnaire locale by using SDK translations.

The following is a translation example:

"questionnaires": {
    "questionnaireTranslate": { //id of a questionnaire to change texts
      "title": "I18n questionnaire title",
      "desc": "I18n questionnaire description",
      "sections": {
        "section1": { //id of a section to change texts
          "title": "I18n section title",
          "desc": "I18n section description",
          "items": {
            "item1": {
              "title": "I18n item title",
              "desc": "I18n item description",
              "options":{ //In case of multiselect options
                "value1": "I18n option title 1",
                "value2": "I18n option title 2"
              }
            }
          }
        }
      }
    }
  }