Interviews

Overview

In medicine, a patient's "medical history" is the information a healthcare provider gathers to help formulate a diagnosis and provide medical care to the patient. The provider obtains this information by asking the patient (or in some cases, the patient's care taker) specific questions about their health. Buoy learns about a patient's medical history through the interview. It relates user demographics, chief complaints, questions, and answers in order to provide triage and care recommendations.

Interview Modes

Interviews operate in three different modes. The first mode is the "input" mode, the second is the "protocol" mode, and the third is the "differential" mode.

• Input mode: The user inputs demographics and complaints.
• Protocol mode: The user is screened for emergency scenarios.
• Differential mode: The user is asked questions to narrow down a possible differential.

Input Mode

Interviews begin in the input mode. This is when demographic data will be gathered, either in the form of an existing user profile for an authenticated interview or as part of the request body for an anonymous interview. The differences between an authenticated and anonymous interview are covered in greater depth in the "Anonymous vs Authenticated Interviews " portion of this explainer.

📘

User location data

When starting an anonymous or authenticated interview, the location field is not required explicitly, but is necessary if our system cannot approximate a location based on the IP address of the request. Additionally, if an API client communicates with the API via a server, and the X-Forwarded-For header is not set properly, approximations will reflect the location of the server, not the user. For these reasons, it is best to provide the user's location when possible.

After demographics have been provided and the interview has been started, users should input up to three complaints. Refer to the complaints explainer or the complaints API reference for more on how to create and update complaints using the Buoy symptom checker API.

📘

Adding or updating complaints outside of the input mode

Adding or updating a complaint from either the protocol or differential mode will automatically reset the interview to the input mode.

Once a user has finished inputting their complaints, the interview should be advanced to the protocol mode by calling the update interview endpoint.

Protocol Mode

The protocol mode focuses on identifying potentially alarming scenarios. Certain combination of inputs will trigger a line of questioning that aims to rule out potentially dangerous scenarios. For example, if an older user presents a complaint of chest pain, Buoy will quickly screen the user for a heart attack and then direct the user to call emergency services if appropriate.

❗️

API clients should not expect protocol questions to be present in every interview

Not every combination of demographics and complaints is likely to lead to an alarming scenario. This is why protocol-based questions do not exist for every combination of inputs entered in the input mode. In instances where an alarming scenario is not likely, but the interview is in protocol mode, the interview will generate a response body that contains a _msg parameter set to "No protocol-based questions or results. Try 'differential' mode." Additionally, the _links parameter will link back to the interview instead of a question. In this situation, the API client should proceed to the differential mode.

If a user responds to protocol-based questions in a way that leads Buoy to believe that a potentially dangerous situation is present, the interview will stop immediately and the user will receive a triage-only result. For more details on triage-only results, refer to the results explainer.

If a user's responses do not lead Buoy to believe that a potentially dangerous situation is present, the interview will stop asking questions. API clients should update the interview to the differential mode by calling the update interview endpoint.

Differential Mode

In the differential mode, the Buoy symptom checker API will generate questions designed to narrow down a potential differential diagnoses. At the conclusion of the differential mode, a result will be made available to the user. Refer to the results explainer for more details on results.

❗️

API clients should not expect differential questions to be present in every interview

While rare, there are scenarios where the interview may not have any differential-based questions. In these instances, updating the interview to the differential mode will generate a response body that contains a _msg parameter set to "No differential-based questions or results. Add or update complaints." Additionally, the _links parameter will link to the complaints endpoints instead of a question. In this situation, the API client should generate a message asking the user to try entering a different combination of complaints.

Authenticated vs. Anonymous Interviews

Interviews may be started with the user either known (authenticated) or unknown (anonymous) to Buoy.

Authenticated Interviews

Authenticated interviews enable Buoy to associate interview data with a known user profile. API clients using authenticated interviews should discuss establishing an SSO integration between the API client and Buoy with their Buoy implementation or support representative. Organizations interested in the authenticated interview flow should reach out their Buoy technical support representative.

Anonymous Interviews

An anonymous interview can begin without a Buoy user profile. Your UI should gather basic demographic information about a user before calling the anonymous interview endpoint. At minimum, this information should include the user's age and sex assigned at birth. API clients using anonymous interviews should discuss authenticating use of machine-to-machine (M2M) tokens with their Buoy implementation or support representative.

Interview Timeouts

The complaints and questions endpoints become either read-only or unavailable for interviews 1 hour from the start time depending on the interview mode. Anonymous interviews lose all access to the questions and complaints endpoint after 1 hour. Authenticated interviews retain access to the questions and complaints endpoint, however these endpoints become read-only. API clients should ensure that users are appropriately timed-out of an interview after 1 hour elapses.