Health questionnaire API

Overview

Most telehealth visits typically collect a series of clinical related questions prior to a provider consult. These questions are bundled into an object known as the patient questionnaire in the Truepill ecosystem. These questionnaires are most commonly based on a specific therapy area or disease state that the patient is inquiring about. Health questionnaires can range in complexity from a three-step yes/no screening questionnaire to more complex 30+ questions with various question types, file/data uploads and answer-based branching logic.

Question types

The health questionnaire supports a range of questions types for your specific needs. The most commonly used question types are listed below:

Type

Definition

free_text

Free text answer to capture answer in string format

multiple_choice

Multiple choice questions with answers stored in array format

date

Date provided as string, formatted `MM-DD-YYYY`

numeric

Free text that only allows for numeric answers

file_upload

Documentation or image required

checkbox

True/False values with answers stored in array format

Question type examples

Below are a series of clinical and survey questions that have been translated into a question object. A patient questionnaire consists of multiple questions.

Free_text question

List any trips to emergency room, hospital admissions or surgical procedures in the last 12 months

Success response


{
  "question_id": 2,
  "default_next_question_id": 3,
  "question_type": "free_text",
  "question_text": "List any trips to the emergency room, hospital admissions or surgical procedures in the last 12 months.",
  "required": true,
  "info_text": null,
  "answers": {
    "answer_id": 1,
    "answer_value": null,
    "next_question_id": null
  }
}

Multiple_choice question

How would you describe your overall health?

Excellent
Good
Fair
Poor

Success response


{
  "question_id": 1,
  "default_next_question_id": 2,
  "question_type": "multiple_choice",
  "question_text": "How would you describe your overall health? (multiple choice)",
  "required": true,
  "info_text": null,
  "answers": [
    {
      "answer_id": 1,
      "answer_value": "Excellent",
      "next_question_id": null
    },
    {
      "answer_id": 2,
      "answer_value": "Good",
      "next_question_id": null
    },
    {
      "answer_id": 3,
      "answer_value": "Fair",
      "next_question_id": null
    },
    {
      "answer_id": 4,
      "answer_value": "Poor",
      "next_question_id": null
    },
  ]
}

Date question

When was the last time you tested your blood sugar?

Success response


{
  "question_id": 4,
  "default_next_question_id": 5,
  "question_type": "date",
  "question_text": "When was the last time you tested your blood sugar?",
  "required": true,
  "info_text": null,
  "answers": {
    "answer_id": 1,
    "answer_value": null,
    "next_question_id": null
  }
}

Numeric question

How often do you test your blood sugar in a given month?

Success response


{
  "question_id": 3,
  "default_next_question_id": 4,
  "question_type": "numeric",
  "question_text": "How often do you test your blood sugar in a given month?",
  "required": true,
  "info_text": null,
  "answers": {
    "answer_id": 1,
    "answer_value": null,
    "next_question_id": null
  }
}

Checkbox question

Please mark all answers that apply to your current overall health condition and symptoms (check all that apply)

I am unable to go up and down stairs
I lose control of my urine and get wet
I have chest pain or shortness of breath when I do work or exercise
I have had temporary loss of vision in one eye
I have pain in my legs that makes me stop when I walk

Success response


{
  "question_id": 5,
  "default_next_question_id": null,
  "question_type": "checkbox",
  "question_text": "How would you describe your overall health? (checkbox)",
  "required": true,
  "info_text": null,
  "answers": [
    {
      "answer_id": 1,
      "answer_value": "I am unable to go up and down stairs",
      "next_question_id": null
    },
    {
      "answer_id": 2,
      "answer_value": "I lose control of my urine and get wet",
      "next_question_id": null
    },
    {
      "answer_id": 3,
      "answer_value": "I have chest pain or shortness of breath when I do work or exercise",
      "next_question_id": null
    },
    {
      "answer_id": 4,
      "answer_value": "I have had temporary loss of vision in one eye",
      "next_question_id": null
    },
    {
      "answer_id": 4,
      "answer_value": "I have pain in my legs that makes me stop when I walk",
      "next_question_id": null
    }
  ]
}

Create a health questionnaire

A health questionnaire can be created using our /telehealth/health_questionnaire API endpoint. Truepill will provide a receipt confirmation of the request, and you will be required to reference your health_questionnaire_id when creating or updating a patient record.

Create patient request


const body = {
 metadata: 'cfe146',
 patient_health_questionnaire: [
   {
     question_id: 1,
     default_next_question_id: 2,
     question_type: 'multiple_choice',
     question_text: 'How would you describe your overall health? (multiple choice)',
     required: true,
     info_text: null,
     answers: [
       {
         answer_id: 1,
         answer_value: 'Excellent',
         next_question_id: null
       },
       {
         answer_id: 2,
         answer_value: 'Good',
         next_question_id: null
       },
       {
         answer_id: 3,
         answer_value: 'Fair',
         next_question_id: null
       },
       {
         answer_id: 4,
         answer_value: 'Poor',
         next_question_id: null
       }
     ]
   },
   {
     question_id: 2,
     default_next_question_id: 3,
     question_type: 'free_text',
     question_text: 'List any trips to the emergency room, hospital admissions or surgical procedures in the last 12 months.',
     required: true,
     info_text: null,
     answers: {
       answer_id: 1,
       answer_value: null,
       next_question_id: null
     }
   },
   {
     question_id: 3,
     default_next_question_id: 4,
     question_type: 'numeric',
     question_text: 'How often do you test your blood sugar in a given month?',
     required: true,
     info_text: null,
     answers: {
       answer_id: 1,
       answer_value: null,
       next_question_id: null
     }
   },
   {
     question_id: 4,
     default_next_question_id: 5,
     question_type: 'date',
     question_text: 'When was the last time you tested your blood sugar?',
     required: true,
     info_text: null,
     answers: {
       answer_id: 1,
       answer_value: null,
       next_question_id: null
     }
   },
   {
     question_id: 5,
     default_next_question_id: null,
     question_type: 'checkbox',
     question_text: 'How would you describe your overall health? (multiple choice)',
     required: true,
     info_text: null,
     answers: [
       {
         answer_id: 1,
         answer_value: 'I am unable to go up and down stairs',
         next_question_id: null
       },
       {
         answer_id: 2,
         answer_value: 'I lose control of my urine and get wet',
         next_question_id: null
       },
       {
         answer_id: 3,
         answer_value: 'I have chest pain or shortness of breath when I do work or exercise',
         next_question_id: null
       },
       {
         answer_id: 4,
         answer_value: 'I have had temporary loss of vision in one eye',
         next_question_id: null
       },
       {
         answer_id: 4,
         answer_value: 'I have pain in my legs that makes me stop when I walk',
         next_question_id: null
       }
     ]
   }
 ]
}


fetch('https://api.truepill.com/v1/telehealth/health_questionnaire', {
   method: 'POST',
   headers: {
     Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
     'Content-Type': 'application/json'
   },
   body: JSON.stringify(body)
 })
 .then(response => response.json())
 .then(response => console.log(response))

Success response


{
 "request_id": "health_questionnaire_bd6825a9d66a49b3d7a7",
 "timestamp": 1592183925,
 "status": "success",
 "details": {
   "health_questionnaire_token": "health_questionnaire_bd6825a9d66a49b3d7a7",
   "message": "Your health questionnaire has been updated successfully.",
   "metadata": "cfe146"
 }
}

Updating a health questionnaire

There are timing dependencies that distance when you can update your health questionnaire.

You currently cannot update a health questionnaire after it has been created and used for a provider consult. You may however update your health questionnaire at any point before it has been used for a consult. This ensures that any historical provider consults are anchored to a specific health questionnaire that cannot be changed after the consult has taken place. This preserves the data in our EMR, maintaining the actual health questionnaire used during a consult which is important for both compliance and quality purposes. In other words, you cannot change the questions/details of a health questionnaire AFTER it has been used for a real consult.

If you need to make edits or updates to your health questionnaire after it has been used for a consult, you can simply create a new one and reference that patient_questionnaire_id for future consult requests.

Update health questionnaire


const body = {
 healh_questionnaire_token: 'health_questionnaire_bd6825a9d66a49b3d7a7',
 patient_health_questionnaire: [
   {
     question_id: 1,
     default_next_question_id: 2,
     question_type: 'numeric',
     question_text: 'How often do you test your blood sugar in a given month?',
     required: true,
     info_text: null,
     answers: {
       answer_id: 1,
       answer_value: null,
       next_question_id: null
     }
   },
   {
     question_id: 2,
     default_next_question_id: 3,
     question_type: 'multiple_choice',
     question_text: 'How would you describe your overall health? (multiple choice)',
     required: true,
     info_text: null,
     answers: [
       {
         answer_id: 1,
         answer_value: 'Excellent',
         next_question_id: null
       },
       {
         answer_id: 2,
         answer_value: 'Good',
         next_question_id: null
       },
       {
         answer_id: 3,
         answer_value: 'Fair',
         next_question_id: null
       },
       {
         answer_id: 4,
         answer_value: 'Poor',
         next_question_id: null
       }
     ]
   },
   {
     question_id: 3,
     default_next_question_id: null,
     question_type: 'free_text',
     question_text: 'List any trips to the emergency room, hospital admissions or surgical procedures in the last 12 months.',
     required: true,
     info_text: null,
     answers: {
       answer_id: 1,
       answer_value: null,
       next_question_id: null
     }
   }
 ]
}


fetch('https://api.truepill.com/v1/telehealth/update_health_questionnaire', {
   method: 'POST',
   headers: {
     Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
     'Content-Type': 'application/json'
   },
   body: JSON.stringify(body)
 })
 .then(response => response.json())
 .then(response => console.log(response))

Success response


{
 "request_id": "health_questionnaire_bd6825a9d66a49b3d7a7",
 "timestamp": 1592183925,
 "status": "success",
 "details": {
   "health_questionnaire_token": "health_questionnaire_bd6825a9d66a49b3d7a7",
   "updated": true,
   "message": "Your health questionnaire has been processed successfully.",
   "metadata": "cfe146"
 }
}

Submit answers to a health questionnaire

You can submit answers to your health questionnaire using the /telehealth/patient_record_questionnaire API endpoint. Truepill will provide a receipt confirmation of the request. You must submit a valid answer for all required questions in your questionnaire. Additionally, when you submit answers to your questionnaire, you must also provide a valid patient_record_token as this is the first point where you are mapping the provided answers (from your patient) to your patient record.

Submit health questionnaire answers


const body = {
 patient_record_token: '4526d90a',
 health_questionnaire_token: 'health_questionnaire_bd6825a9d66a49b3d7a7',
 questionnaire_answers: [
   {
     question_id: 1,
     answer_id: 1,
     answer: 'Excellent'
   },
   {
     question_id: 2,
     answer_id: 1,
     answer_value: 'No trips to the emergency room or hospital in the last 12 months'
   },
   {
     question_id: 3,
     answer_id: 1,
     answer_value: 4
   },
   {
     question_id: 4,
     answer_id: 1,
     answer_value: '03-24-2020'
   },
   {
     question_id: 5,
     answer_id: [1, 4],
     answer_value: [
       'I am unable to go up and down stairs',
       'I have pain in my legs that makes me stop when I walk'
     ]
   }
 ]
}


fetch('https://api.truepill.com/v1/telehealth/patient_record_questionnaire', {
   method: 'POST',
   headers: {
     Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
     'Content-Type': 'application/json'
   },
   body: JSON.stringify(body)
 })
 .then(response => response.json())
 .then(response => console.log(response))

Success response


{
 "request_id": "patient_record_questionnaire_bd6825a9d66a49b3d7a7",
 "timestamp": 1592183925,
 "status": "success",
 "details": {
   "message": "Your patient record questionnaire has successfully been added to the patient record",
   "metadata": "cfe146",
   "patient_record_token": "4526d90a"
 }
}

Note: As you may notice, you cannot submit questions and answers at once without first creating a health questionnaire. The reason for this is that each questionnaire is reviewed and approved by our clinical team and ensures that changes are not made to the questionnaire without review and approval from our team. This ensures the highest quality of clinical care for your patients in accordance with a mutually agreed upon clinical protocol.

Branching logic

Overview

Questions presented to a patient may depend on the answer to previous questions. The multiple_choice, checkbox and numeric question types can have properties that specify the branching logic for your next question. This is accomplished using a next_question_id parameter in your answer block.

When next_question_id is not present for a given answer, the questionnaire will default to the default_next_question_id value.

Multiple_choice example

Success response


{
 "question_id": 1,
 "default_next_question_id": 2,
 "question_type": "multiple_choice",
 "question_text": "How would you describe your overall health? (multiple choice)",
 "required": true,
 "info_text": null,
 "answers": [
   {
     "answer_id": 1,
     "answer_value": "Excellent",
     "next_question_id": 4
   },
   {
     "answer_id": 2,
     "answer_value": "Good",
     "next_question_id": null
   },
   {
     "answer_id": 3,
     "answer_value": "Fair",
     "next_question_id": null
   },
   {
     "answer_id": 4,
     "answer_value": "Poor",
     "next_question_id": 5
   },
 ]
}

Checkbox example

Success response


{
 "question_id": 5,
 "default_next_question_id": 7,
 "question_type": "checkbox",
 "question_text": "How would you describe your overall health?",
 "required": true,
 "info_text": "Check all that apply",
 "answers": [
   {
     "answer_id": 1,
     "answer_value": "I am unable to go up and down stairs",
     "next_question_id": null
   },
   {
     "answer_id": 2,
     "answer_value": "I lose control of my urine and get wet",
     "next_question_id": 3
   },
   {
     "answer_id": 3,
     "answer_value": "I have chest pain or shortness of breath when I do work or exercise",
     "next_question_id": 6
   },
   {
     "answer_id": 4,
     "answer_value": "I have had temporary loss of vision in one eye",
     "next_question_id": null
   },
   {
     "answer_id": 4,
     "answer_value": "I have pain in my legs that makes me stop when I walk",
     "next_question_id": 8
   }
 ]
}

Numeric example

Success response


{
 "question_id": 3,
 "default_next_question_id": 4,
 "question_type": "numeric",
 "question_text": "How often do you test your blood sugar in a given month?",
 "required": true,
 "info_text": null,
 "answers": {
   "answer_id": 1,
   "answer_value": null,
   "next_question_id": [
     {
       "type": "EQUIVALENCY_COMPARISON",
       "comparison_value": 5,
       "next_question_id": null
     },
     {
       "type": "SINGLE_COMPARISON",
       "comparison_operator": "less_than_or_equal_to",
       "comparison_value": 25,
       "next_question_id": 23
     },
     {
       "type": "RANGE_COMPARISON",
       "lower_limit_comparison_value": 15,
       "lower_limit_comparison_operator": "greater_than",
       "upper_limit_comparison_value": 100,
       "upper_limit_comparison_operator": "less_than_or_rqual_to",
       "next_question_id": 43
     }
   ]
 }
}

Note: We understand that most clinical questionnaires will have some branching logic. The intent of the Truepill API for handling branching is to present the provider reviewing your health questionnaire with the most streamlined view of all data in order to deliver an efficient and high-quality clinical consult. In some cases, our clinical team may require you to incorporate some branching logic to ensure the high quality standards are met for your clinical questionnaires.