Questions
Overview
Questions enable the user to provide more information about their condition to Buoy. For example, the Buoy Symptom Checker API may ask a user, "How severe is your back pain?" or, "How long has your chest pain been going on?"
Question sequences
Questions are generated in sequences dictated by the interview mode. Buoy is interested in learning about different pieces of information depending on where the user is at in the interview.
Input mode
In the 'input' mode, Buoy asks questions meant to help clarify and characterize a complaint. For example, in response to a complaint of chest pain, Buoy will want to know if the chest pain is getting better or worse, when the user's chest hurts, how long the chest pain has been going on, and how severe the chest pain is.
Protocol mode
In the 'protocol' mode, Buoy asks questions meant to quickly assess the user's risk for dangerous or emergent scenarios. Buoy will typically ask the user, "Do you have any of the following related symptoms?" followed by, "Do you have any of the following related risk factors?" Depending on the user's responses, additional questions may be asked.
Differential mode
In the 'differential' mode, Buoy asks questions meant to narrow down a differential diagnoses, similar to how a PCP would ask questions during a patient visit. For example, Buoy may ask if a user's hip pain is affecting one or both hips.
Working with the questions endpoint
New questions will be returned in the '_links.next' parameter found within various response bodies. Questions should first be read and displayed to the user by calling the read question endpoint, and then updated with the user's answer by calling the update question endpoint.
Response types
The 'choice' attribute of a question can take on three values: S, M, and D; S is for single-select; M is for multiple-select; D is for duration. It expects the duration of the complaint, in hours, in the "extra" field. Note that submitting the "extra" field in the request body is optional for S- and M-type questions.
API clients must leverage the boolean 'exclusive' attribute in order to determine which answer options are mutually exclusive (e.g., "None of the above" and "Unsure"). Buoy recommends visually distinguishing exclusive options from non-exclusive options. For example, on our public symptom checker separates exclusive options within M-type questions with a separator line. Additionally, for consistency, all answer options for single-select questions will have the exclusive
field set to True.
API clients may optionally leverage the free_text
attribute. For options in which free_text
is True (e.g., "Something else"), free text answers can be supplied as an “extra” string in the answer object.
Media
Buoy offers a variety of media that may be displayed with the question text or as part of an answer option. Most media in use are images (.png or .jpg), but API clients should expect to handle video (.mp4) as well. API clients should use the content-type of the media in order to determine how to render the media to the user. Additionally, clients should leverage the media_alttext
field for accessibility purposes.
Some questions and options with media (images or video) will have words surrounded by square brackets (i.e., "[" and "]"). This is the text that is most relevant to the media. The Buoy client styles this text to look like a link and displays the media when users hover over it.
For more details on handling media with the interview, refer to the how-to display media in the interview guide.
Modifying previously answered questions
To allow users to modify complaints or question answers, the client should update or delete the relevant complaint or answer on behalf of the user (via PUT/DELETE calls) and clear any subsequent resources from view. Clearing content ensures the UI state reflects the actual interview state. This is because any modification to an interview-related resource (i.e.. complaints, and questions) will invalidate resources that followed it in the application flow. In other words, if a user answers five questions, then modifies the third question, the fourth and fifth questions and their answers are automatically deleted. This allows Buoy to change the sequence of the interview and forces the user to re-confirm details that may have also changed.
Using the /explain/ endpoint
When in the protocol or differential interview mode, API clients may leverage the /explain/ endpoint to provide more context to the user about why a specific question is being asked. Clients should leverage the 'diagnosis' and 'predictors' fields to form a user-friendly string describing why a given question is being asked. API clients are welcome to use the following language, mimicking what is in available in the public Buoy symptom checker: "This question is about 'diagnosis', which can cause your 'predictors', among other things.
For example: If a call to the /explain/ endpoint returns the following JSON response, the client should display: "This question is about mild frostbite of the upper limbs, which can cause your abnormal coldness of the bothersome body part(s) and exposure to the freezing cold, among other things."
{
"token":"<QuestionToken>",
"interview":"<InterviewToken>",
"diagnosis":"mild frostbite of the upper limbs",
"predictors": [
"abnormal coldness of the bothersome body part(s)",
"exposure to the freezing cold"
]
}
Updated over 2 years ago