Intake Forms

Intake forms are questionnaires prepared by you, that you can use to gather information from your clients, using our platform. You can think of these as Google Forms, provided over the API. You have complete control over the number of questions you want to add, later remove or update.

The Intake Forms API allows you to create, archive, retrieve, update and answer intake forms.

Creating an Intake Form

Use the POST /intake-form/ endpoint to create a new intake form.

Creating Questions Within an Intake Form

To add questions for intake forms, use the POST /intake-form/{intake_form_id}/question/ endpoint. Replace {intake_form_id} with the id returned from the response of POST /intake-form/.

Answer Types

At the time of creating a question, you have to specify answer_type as a body parameter of the POST request. There are 4 answer types to choose from:

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 number

Answer Options

You also have to specify the answer options upon creating a question. 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

The type of answer option is determined by the resourcetype field. It can be set only at the time of option creation, and cannot be updated later. Refer below for examples.

Example Payloads

Free Response Questions

Free Response Text

Let's say you have a very basic question where you want to inquire your client's name, allowing free input from the user.

Payload:

{
  "question_text": "What is your name?",
  "answer_type": "free response",
  "position": 1,
  "answer_options": [
    {
      "resourcetype": "FreeResponseOption",
      "option_text": "Full Name:",
      "order": 1
    }
  ]
}

Free Response Number

Now let's consider you have a question that expects only a number as an input from the user, and not text, like upon inquiring their age:

Payload:

{
  "question_text": "What is your age?",
  "answer_type": "number",
  "position": 2,
  "answer_options": [
    {
      "resourcetype": "FreeResponseOption",
      "option_text": "Age:",
      "order": 1
    }
  ]
}

Note: Upon creating a question with an answer type of "free response" or "number", you always need to have only a single answer option with type "FreeResponseOption".

Multiple Choice Questions

An MCQ, be it with answer type "single choice" or "multiple choice", can have answer options of both types. Let's say you want to have a question like the one given below:

Do you have a history of diagnosis of any of the mental health conditions given below?

ADHD

Bipolar Disorder

Borderline Personality Disorder

Other (please specify)

Payload:

{
  "question_text": "Do you have a history of diagnosis of any of the mental health conditions given below?",
  "answer_type": "multiple choices",
  "position": 3,
  "answer_options": [
    {
      "resourcetype": "MultipleChoiceOption",
      "option_text": "ADHD",
      "order": 1
    },
    {
      "resourcetype": "MultipleChoiceOption",
      "option_text": "Bipolar Disorder",
      "order": 2
    },
    {
      "resourcetype": "MultipleChoiceOption",
      "option_text": "Borderline Personality Disorder",
      "order": 3
    },
    {
      "resourcetype": "FreeResponseOption",
      "option_text": "Other (please specify)",
      "order": 4
    }
  ]
}

Updating Intake Forms

PUT /intake-form/{id}/ and PATCH /intake-form/{id}/ endpoints are available to update and partially update the intake forms.

Updating Questions Within Intake Forms

PUT /intake-form/{intake_form_id}/question/{id}/, PATCH /intake-form/{intake_form_id}/question/{id}/ and DELETE /intake-form/{intake_form_id}/question/{id}/ endpoints are available to update, partially update and delete questions of an intake form.

Reorder Questions Within an Intake Form

To reorder questions that you have previously created within an intake form, use the PUT /intake-form/{id}/reorder-questions/ endpoint.

Adding Question Options

You can always add more options to a question after having created it, using the question update or partial update endpoints. Let's say you want to add a new option to the multiple choice question discussed above. A sample request can look like the following:

PATCH /intake-form/{intake_form_id}/question/{id}/

{
  "answer_options": [
    {
      "resourcetype": "MultipleChoiceOption",
      "option_text": "Obsessive-Compulsive Disorder (OCD)",
      "order": 5
    }
  ]
}

Updating Question Options

Question options can also be updated using the question update or partial update endpoints. To do so, in the request body, under the answer_options field, pass the id of the option you wish to update, along with the option fields. Let's say you want to update the first option of the multiple choice question discussed above from having option_text "ADHD" to "Hyperactivity". The sample request can look like the following:

PATCH /intake-form/{intake_form_id}/question/{id}/

{
  "answer_options": [
    {
      "id": "8227081c-7239-4c23-a709-03ffad2d503d", // option id returned from response of POST question endpoint
      "resourcetype": "MultipleChoiceOption",
      "option_text": "Hyperactivity",
      "order": 1
    }
  ]
}

Delete Question Options

Use the DELETE /intake-form/{intake_form_id}/question/{id}/delete-option/{option_id}/ endpoint to delete the option of a question.

Listing and Retrieving Intake Forms

To get a list of all intake forms created by you, use the GET /intake-form/ endpoint. It would return the metadata of the intake forms, but not the complete list of questions associated with each intake form.

To retrieve the questions for a particular intake form, along with its metadata, use the GET /intake-form/{id}/ endpoint. Let's say you have a basic intake form created comprising the 3 questions discussed above. Refer here to see how the response from the retrieve endpoint for that intake form would look like, including the questions.

Attempting an Intake Form

Please refer here.

Listing Answers of a Profile for an Intake Form

Please refer here.