Interview Flow

The Buoy Symptom Checker API allows clients to implement a chat-based medical history triage service. The interview experience is made up of several distinct phases, illustrated below:

1. Gathering demographics
2. Gathering and clarifying complaints
3. Screening for emergency (alarm) scenarios
4. Narrowing down possible differentials
5. Presenting results

1. Gathering Demographics

Depending on the user, an interview starts on one of two paths. If a user is known and has a stored profile, the "authenticated users" path should be followed. (Authenticated users are able to associate their interviews with their profiles, allowing them to view past interviews and bypass demographics entry with each visit.) If a user is not known to Buoy, the "anonymous" interview path should be followed. It is not necessary to create a profile for anonymous interviews. Refer to the interviews explainer for more details on anonymous and authenticated interviews.

2. Gathering and clarifying complaints

After beginning an interview, a user will submit and clarify complaints. A user's complaint may describe a symptom, problem, condition, diagnosis, or physician-recommended return. A complaint could be something like "hip pain" or "sneezing."

Users are able to submit free-text quarries to the complaints API. POSTing to the complaint endpoint will return a list of interpretations (clarifications) that a user can select from. Upon selecting an interpretation, the interview may return a series of questions designed to clarify a complaint (e.g. "How long have you been sneezing?").

When users are entering complaints, the interview is in the "input" mode. For a detailed explainer on Buoy's interview modes, refer to the Interviews explainer. Your UI should limit users to submitting three complaints.

📘

Certain complaints, such as blue lips, may trigger a result directly. Clients should monitor for a result link in the _links.result parameter.

3. Screening for emergency (alarm) scenarios

After the user has submitted and clarified their complaints, the interview should be advanced to the "protocol" mode. In this mode, the interview may ask the user a series of questions designed to assess the user for situations in which a more immediate escalation to emergency services should be provided.

📘

Alarm scenarios will directly trigger a result.

If a user triggers one of Buoy's alarm scenarios – like a possible heart attack – the user will immediately receive a result. In these instances, no differential results will be given. Refer to the results explainer for details.

Not every combination of complaints will generate protocol-based questions. In these instances, the API will return a message informing your application to proceed to the "differential" mode described in Step 4.

4. Narrowing down possible differentials

After the user has been screened for potential alarm scenarios, the interview should be advanced to the "differential" mode. In the differential mode, the user will be presented with a series of questions intended to drive to a final result.

5. Present results

At the end of the interview, users will be presented with results. The results endpoint provides triage and differential results. Users can be presented with up to three differential and triage recommendations.