Retrieving an Intake Form
An intake form comprises of some meta data like title, introduction message and questionnaire ID. It further comprises of a list of questions, where each question has one or more answer options. Each question can be of various answer_types, and each option can be of two types, as discussed below.
Answer Types
There are 4 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
To have more clarity, refer to the example response below, and to know how to attempt each type of question, refer to the "Attempting an Intake Form" section below.
Answer Options
There are two 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
To have more clarity, refer to the example response below, and to know how to deal with each option while attempting a question, refer to the "Attempting an Intake Form" section below.
Example Request
GET /intake-form/{id}/
Example Response
Let's consider a basic intake form containing the following questions
{
"id": "3c870f7b-fdde-41cc-b615-39754b6674bf",
"user_id": "ede136be-65ca-4bc7-99b9-7dfc7c053c47",
"created_at": "2024-11-25T14:39:23.863228Z",
"updated_at": "2024-11-25T14:39:23.863243Z",
"title": "Basic Intake Form",
"slug": "basic-intake-form-ede136",
"introduction_message": "",
"questionnaire_id": "6651883f-939a-4953-965e-e9954cad6f4c",
"archived": false,
"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
}
]
}
]
}
Attempting an Intake Form
After retrieving the intake form and getting a list of all the questions belonging to the form, each question has to be answered individually by a profile. To do so, use the POST /answer/ endpoint. Use the questionnaire_id from the response of the retrieve 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.
Special Instructions for Attempting Weight and Height Questions
Some intake forms 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.
Re-attempting Intake Form and Updating Answers
As an API user, for any profile, you can always revisit the questions, and simply re-answer them, exactly the way you answered them the first time, and your answers will be updated in the DB. You can choose to re-attempt the entire questionnaire by re-answering all questions, or just update one particular answer.
Listing Answers of a Profile for an Intake Form
Use the GET /answer/ endpoint to list all answers of a profile against a particular intake form / questionnaire. Use the questionnaire_id from the response of the retrieve endpoint.