API endpoints

Answering Questions

📘

Questions may be shared among multiple questionnaires, and if you answer a question as part of one questionnaire, it would be answered for all questionnaires.

Answer Types

Each question can have either of the four answer types:

  • single choice - if the question is an MCQ that only accepts a single answer option
  • multiple choices - if the question is an MCQ that accepts multiple answer options
  • free response - if the question accepts input text as an answer
  • number - if the question accepts input text as an answer, with the restriction that that the input must be a numeric value

It's determined by the answer_type field of a question. To have more clarity, refer to the example questionnaire below, and to know how to attempt each type of question, refer to the "Answering Questions" section below.

Answer Options

There are three types of available answer options:

  • MultipleChoiceOption - if the said option has an option text of its own and does not expect a free response from a user, just like an option in an MCQ
  • FreeResponseOption - if the said option expects an input text from the user
  • NoneOption - quite like MultipleChoiceOption, except once this option is chosen as an answer to a multiple choice question, another option cannot be selected along. It helps with frontend user experience.

It's determined by the resourcetype field of an answer option. To have more clarity, refer to the example questionnaire below, and to know how to deal with each option while attempting a question, refer to the "Answering Questions" section below.

Example Questionnaire

Let's consider a sample questionnaire containing the following questions

{
    "questionnaire_id": "6651883f-939a-4953-965e-e9954cad6f4c",
    "number_of_questions": 3,
    "questions": [
        {
            "id": "c3025210-0546-4afa-a03c-9078e13aad69",
            "question_text": "What is your name?",
            "leading_text": "",
            "followup_text": "",
            "answer_type": "free response",
            "position": 1,
            "archived": false,
            "answer_options": [
                {
                    "id": "5c840021-3eb0-490c-86f0-f09b6431c317",
                    "resourcetype": "FreeResponseOption",
                    "question_id": "c3025210-0546-4afa-a03c-9078e13aad69",
                    "option_text": "Full Name:",
                    "order": 1,
                    "archived": false
                }
            ]
        },
        {
            "id": "7b329539-31cc-48b2-9bc9-27e650c38ed5",
            "question_text": "What is your age?",
            "leading_text": "",
            "followup_text": "",
            "answer_type": "number",
            "position": 2,
            "archived": false,
            "answer_options": [
                {
                    "id": "b66f2ccb-6b75-4bc0-8b0f-a04361401aae",
                    "resourcetype": "FreeResponseOption",
                    "question_id": "7b329539-31cc-48b2-9bc9-27e650c38ed5",
                    "option_text": "Age:",
                    "order": 1,
                    "archived": false
                }
            ]
        },
        {
            "id": "24edf55f-c50a-4fda-8649-687338f63dd0",
            "question_text": "Do you have a history of diagnosis of any of the mental health conditions given below?",
            "leading_text": "",
            "followup_text": "",
            "answer_type": "multiple choices",
            "position": 3,
            "archived": false,
            "answer_options": [
                {
                    "id": "4ccf76c6-c3c6-42dd-b2ba-bbf66ec9837a",
                    "resourcetype": "MultipleChoiceOption",
                    "question_id": "24edf55f-c50a-4fda-8649-687338f63dd0",
                    "option_text": "ADHD",
                    "order": 1,
                    "archived": false
                },
                {
                    "id": "45636ee6-02a3-4aeb-8843-3b4d18a1c3cb",
                    "resourcetype": "MultipleChoiceOption",
                    "question_id": "24edf55f-c50a-4fda-8649-687338f63dd0",
                    "option_text": "Bipolar Disorder",
                    "order": 2,
                    "archived": false
                },
                {
                    "id": "bad5f0aa-1c4c-4592-87e2-75ee35a8a7c2",
                    "resourcetype": "MultipleChoiceOption",
                    "question_id": "24edf55f-c50a-4fda-8649-687338f63dd0",
                    "option_text": "Borderline Personality Disorder",
                    "order": 3,
                    "archived": false
                },
                {
                    "id": "726074d9-60f8-4f10-a6fa-c2d89cd38bff",
                    "resourcetype": "FreeResponseOption",
                    "question_id": "24edf55f-c50a-4fda-8649-687338f63dd0",
                    "option_text": "Other (please specify)",
                    "order": 4,
                    "archived": false
                },
                {
                    "id": "c87148f0-eb2e-4032-9372-a55d35a82745",
                    "resourcetype": "NoneOption",
                    "question_id": "24edf55f-c50a-4fda-8649-687338f63dd0",
                    "option_text": "None",
                    "order": 5,
                    "archived": false
                }
            ]
        }
    ]
}

Answering Questions

Each question has to be answered individually by a profile, using the POST /answer/ endpoint.

Examples

Let's revisit the questions from the example response above, and sample payloads to answer them.

Sample payload to answer the free response text question:

{
  "profile_id": "340507df-60e6-48cc-9f2e-303a92936131",
  "question_id": "c3025210-0546-4afa-a03c-9078e13aad69",
  "questionnaire_id": "6651883f-939a-4953-965e-e9954cad6f4c",
  "options": ["5c840021-3eb0-490c-86f0-f09b6431c317"],  // ID(s) of the chosen option(s)
  "response_text": "John Doe"
}

Sample payload to answer the free response number question:

{
  "profile_id": "340507df-60e6-48cc-9f2e-303a92936131",
  "question_id": "7b329539-31cc-48b2-9bc9-27e650c38ed5",
  "questionnaire_id": "6651883f-939a-4953-965e-e9954cad6f4c",
  "options": ["b66f2ccb-6b75-4bc0-8b0f-a04361401aae"],  // ID(s) of the chosen option(s)
  "response_text": "18"
}

Note: Upon answering a question with an answer type of "free response" or "number", you always need to provide the ID of the single free response answer option that is part of the question, along with the actual answer in the response_text field, as shown above.

Sample payload to answer the multiple choice question:

{
  "profile_id": "340507df-60e6-48cc-9f2e-303a92936131",
  "question_id": "24edf55f-c50a-4fda-8649-687338f63dd0",
  "questionnaire_id": "6651883f-939a-4953-965e-e9954cad6f4c",
  "options": [  // ID(s) of the chosen option(s)
    "4ccf76c6-c3c6-42dd-b2ba-bbf66ec9837a",
    "45636ee6-02a3-4aeb-8843-3b4d18a1c3cb",
    "726074d9-60f8-4f10-a6fa-c2d89cd38bff"
  ],
  "response_text": "PTSD"
}

Notice that since the question has answer_type "multiple choices", we can pass multiple option IDs in the answer. Also notice that the last option ID we have passed corresponds to the FreeResponseOption as can be seen in the response payload above, under the list of questions. Since we have chosen the FreeResponseOption option as one of our answer options, it becomes mandatory to provide the response_text field with a non-empty string. Otherwise, the said field can be omitted for multiple choice questions.

Sample payload to answer the multiple choice question, this time selecting the "None" option:

{
  "profile_id": "340507df-60e6-48cc-9f2e-303a92936131",
  "question_id": "24edf55f-c50a-4fda-8649-687338f63dd0",
  "questionnaire_id": "6651883f-939a-4953-965e-e9954cad6f4c",
  "options": ["c87148f0-eb2e-4032-9372-a55d35a82745"],  // ID(s) of the chosen option(s)
  "response_text": ""
}

The none option can be treated just like a multiple choice option having the option_text = "None", with the only difference being that if chosen, that'd be the only option in the answer. This helps with fronted user experience, where you can add validation or where you may want to immediately record their answer and display the next question if a user clicks on the none option, instead of waiting on the user to select multiple options and press "Continue" or "Next".

Special Instructions for Answering Weight and Height Questions

Some questionnaires may have the following questions:

    "questions": [
        {
            "id": "a1fa96ba-1ac1-4157-9d20-95a194e36742",
            "question_text": "<p>What is your current weight?</p>",
            "leading_text": "",
            "followup_text": "",
            "answer_type": "number",
            "position": 0,
            "archived": false,
            "answer_options": [
                {
                    "id": "017a5c0b-5983-4999-bf20-01f45ffb90e5",
                    "resourcetype": "FreeResponseOption",
                    "question_id": "a1fa96ba-1ac1-4157-9d20-95a194e36742",
                    "option_text": "My current weight is:",
                    "order": 1,
                    "archived": false
                }
            ]
        },
        {
            "id": "a9a5dd19-f269-4898-9b72-3c55115aa3d5",
            "question_text": "<p>What is your height?</p>",
            "leading_text": "",
            "followup_text": "",
            "answer_type": "number",
            "position": 1,
            "archived": false,
            "answer_options": [
                {
                    "id": "1f49f2ae-3ffb-495e-a066-1e10cffaa2b8",
                    "resourcetype": "FreeResponseOption",
                    "question_id": "a9a5dd19-f269-4898-9b72-3c55115aa3d5",
                    "option_text": "My height is:",
                    "order": 1,
                    "archived": false
                }
            ]
        },
        ...
    ]

For weight question, the response must be a number between 0 and 650. The value inputted will be interpreted in kg.

For height question, the response must be a number between 0 and 300. The value inputted will be interpreted in cm.

If you want to allow your UI to receive input for weight in pounds or for height in foot and inches, you have have to do the conversion to pounds and / or cm on your own before calling the API.

Updated about 1 year ago

Did this page help you?

Updated about 1 year ago

Did this page help you?