Completing your first interview
Goal
At the end of this tutorial you will have completed a basic interview using Buoy's Symptom Checker API.
Notes
- We recommend using our Postman collection while completing this tutorial.
- Buoy's interviews are dynamic. The questions proposed by our AI and the answer options available may change from time to time. This tutorial is written in a way to provide flexibility for change. If you have any questions, please review our service desk documentation.
Completing your first interview
1. Ensure that you're authenticated
A valid Bearer token is required to access the interview. If you need to obtain an access token, refer to the authorization how-to guide. Remember to replace <token> with your access token in each of the requests below.
2. Create a new anonymous interview
To create the interview, POST to the /api/interviews/anonymous/ endpoint. You will be starting the interview on behalf of a 25-year-old male answering for themselves.
curl -XPOST \
-H 'Authorization: Bearer <token>' \
-H "Content-type: application/json" \
-d '{
"profile": {
"sex": "m",
"age": 25
}
}' 'https://api.sandbox.buoyhealth.com/symptom-checker/v2/interviews/anonymous/'
You should receive a HTTP 200 response (similar to that in the screen below) indicating that an interview was successfully started. Take note of the token returned in the response body. This token uniquely identifies interviews for Buoy and will be used by subsequent endpoints. If you are using our Postman collection, this token will automatically be copied to the InterviewToken environment variable.
{
"token": "<InterviewToken>",
"profile": {
"is_self": true,
"age": 25.0,
"sex": "m"
},
"start_time": "03/16/2021 12:55:45",
"end_time": null,
"location": {
"latitude": 45.5496,
"longitude": -122.8293,
"postal_code": "97229",
"country": "US",
"approximate": true
},
"mode": "input",
"should_display_alarm": false
}
3. Create a user complaint of "rapid breathing"
To add this complaint to the interview, POST a request to the /api/complaints/ endpoint.
curl -XPOST \
-H 'Authorization: Bearer <token>' \
-H "Content-type: application/json" \
-d '{
"query": "rapid breathing",
"interview": "<InterviewToken>"
}' 'https://api.sandbox.buoyhealth.com/symptom-checker/v2/complaints/'
You should receive an HTTP 201 response, indicating that a complaint was successfully created.
{
"token": "<ComplaintToken>",
"interview": "<InterviewToken>",
"query": "rapid breathing",
"interpretations": [
{
"token": "<InterpretationToken1>",
"title": "pause in breathing",
"description": "I have experienced pauses in breathing for longer than 20 seconds"
},
{
"token": "<InterpretationToken2>",
"title": "stopped breathing (apnea)",
"description": "I have experienced pauses in breathing"
},
{
"token": "<InterpretationToken3>",
"title": "difficulty getting enough air",
"description": "I have breathlessness or difficulty getting air into my chest"
},
{
"token": "<InterpretationToken4>",
"title": "choking",
"description": "I am choking"
},
{
"token": "<InterpretationToken5>",
"title": "rapid breathing",
"description": "I am breathing abnormally fast"
}
],
"clarification": []
}
One or more interpretations of the user's query will be returned in the response. Users should be asked to select the correct interpretation from a list or to submit a new query. For this tutorial, you will proceed with the interpretation associated with "I am breathing abnormally fast." PUT an update to the /api/complaints/<ComplaintToken> endpoint with the following. Ensure that you replace the <ComplaintToken>, <InterviewToken>, and the <InterpretationToken5> in your request body. If you are using our Postman collection, all three tokens should be set in your environment variables (Postman will select the first interpretation option for you by default.) You will need to highlight the interpretation token associated with "I am breathing abnormally fast" then right click and save the token to the InterpretationToken environment variable.
curl -XPUT \
-H 'Authorization: Bearer <token>' \
-H "Content-type: application/json" \
-d '{
"interview": "<InterviewToken>",
"clarification": [{
"token": "<InterpretationToken5>"
}]
}' 'https://api.sandbox.buoyhealth.com/symptom-checker/v2/complaints/<ComplaintToken>/'
You should receive an HTTP 200 response with a response similar to the following:
{
"token": "<ComplaintToken>",
"interview": "<InterviewToken>",
"query": "rapid breathing",
"interpretations": [
{
"token": "<InterpretationToken1>",
"title": "pause in breathing",
"description": "I have experienced pauses in breathing for longer than 20 seconds"
},
{
"token": "<InterpretationToken2>",
"title": "stopped breathing (apnea)",
"description": "I have experienced pauses in breathing"
},
{
"token": "<InterpretationToken3>",
"title": "difficulty getting enough air",
"description": "I have breathlessness or difficulty getting air into my chest"
},
{
"token": "<InterpretationToken4>",
"title": "choking",
"description": "I am choking"
},
{
"token": "<InterpretationToken5>",
"title": "rapid breathing",
"description": "I am breathing abnormally fast"
}
],
"clarification": [
{
"token": "<InterpretationToken5>"
}
]
}
Many interpretations will generate follow-up questions – e.g. "How severe is your pain?" – designed to further clarify complaints. The rapid breathing interpretation does not have any questions associated with it. You will see how to respond to questions in a later section.
Users may submit up to three complaints. In this tutorial, we will submit only the complaint about rapid breathing.
4. Update the interview mode to "protocol"
In the protocol mode, Buoy's AI will ask the user questions designed to identify alarm scenarios that may require immediate care escalation to services like EMS. To update the interview mode, POST an update to the /api/interviews/ endpoint with the following:
curl -XPUT \
-H 'Authorization: Bearer <token>' \
-H "Content-type: application/json" \
-d '{
"mode": "protocol"
}' 'https://api.sandbox.buoyhealth.com/symptom-checker/v2/interviews/<InterviewToken>/'
You will receive an HTTP 202 response similar to the following:
{
"token": "<InterviewToken>",
"start_time": "03/16/2021 12:55:45",
"end_time": null,
"profile": "<ProfileToken>",
"location": {
"latitude": 45.5496,
"longitude": -122.8293,
"postal_code": "97229",
"country": "US",
"approximate": true
},
"mode": "protocol",
"should_display_alarm": false,
"_links": {
"interviews": "https://api.sandbox.buoyhealth.com/symptom-checker/v2/interviews/fd02920c-47df-4b23-bf73-2e97e4773def/"
},
"_msg": "No protocol-based questions or results. Try 'differential' mode."
}
A complaint of rapid breathing does not generate any protocol-based questions. This is indicated in the "_msg" parameter.
5. Update the interview mode to "differential"
In the differential mode, Buoy's AI will ask users questions designed to match their situation and then provide up to three diagnoses. To update the interview mode, POST an update to the /api/interviews/ endpoint with the following:
curl -XPUT \
-H 'Authorization: Bearer <token>' \
-H "Content-type: application/json" \
-d '{
"mode": "differential"
}' 'https://api.sandbox.buoyhealth.com/symptom-checker/v2/interviews/<InterviewToken>/'
You will receive an HTTP 202 response similar to the following:
{
"token": "<InterviewToken>",
"start_time": "03/01/2021 08:12:11",
"end_time": null,
"profile": "<ProfileToken>",
"location": {
"latitude": 42.3377967,
"longitude": -71.0705763,
"postal_code": "02118",
"country": "US",
"approximate": true
},
"mode": "differential",
"should_display_alarm": false,
"_links": {
"next": "https://api.sandbox.buoyhealth.com/symptom-checker/v2/questions/<QuestionToken>/"
}
}
Note that a link to a question appears in the "next" parameter.
6. Respond to differential questions
To respond to the question generated after switching the interview to the differential mode, send a GET request to the /api/questions/<QuestionToken> endpoint.
curl -XGET \
-H 'Authorization: Bearer <token>' \
-H "Content-type: application/json" \
'https://api.sandbox.buoyhealth.com/symptom-checker/v2/questions/<QuestionToken>'
You will receive an HTTP 200 request similar to the following. Note that you may see a different question text than below, but should see similar answer options.
{
"token": "<QuestionToken>",
"text": "Any of the following?",
"choice": "M",
"media": "",
"options": [
{
"token": "<AnswerToken1>",
"text": "Feeling down, depressed, or hopeless",
"preselected": null,
"media": "",
"exclusive": false,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken2>",
"text": "Anxiety",
"preselected": null,
"media": "",
"exclusive": false,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken3>",
"text": "Aggression",
"preselected": null,
"media": "",
"exclusive": false,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken4>",
"text": "Frequently losing my temper",
"preselected": null,
"media": "",
"exclusive": false,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken5>",
"text": "Thoughts of ending my or someone else's life",
"preselected": null,
"media": "",
"exclusive": false,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken6>",
"text": "None of the above",
"preselected": null,
"media": "",
"exclusive": true,
"media_alttext": "",
"free_text": false
}
],
"answer": [],
"interview": "<InterviewToken>",
"media_alttext": ""
}
In the response body, you will see the question for the user in the "text" parameter. Answer options available to the user are provided in the "options" parameter.
To respond to the question, save the token that corresponds with the "No" option. If you are using Buoy's Postman collection, you can select the token, right-click, and choose the "Set: Buoy Sandbox > AnswerToken" in order to save the token. Next, send a PUT request to the /api/questions/<QuestionToken> endpoint.
curl -XPUT \
-H 'Authorization: Bearer <token>' \
-H "Content-type: application/json" \
-d '{
"answer": [
{
"token": "<AnswerToken6>",
"extra": ""
}
]
}' 'https://api.sandbox.buoyhealth.com/symptom-checker/v2/questions/<QuestionToken>'
You will receive an HTTP 200 response similar to the following:
{
"token": "<QuestionToken>",
"text": "Any of the following?",
"choice": "M",
"media": "",
"options": [
{
"token": "<AnswerToken1>",
"text": "Feeling down, depressed, or hopeless",
"media": "",
"exclusive": false,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken2>",
"text": "Anxiety",
"media": "",
"exclusive": false,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken3>",
"text": "Aggression",
"media": "",
"exclusive": false,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken4>",
"text": "Frequently losing my temper",
"media": "",
"exclusive": false,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken5>",
"text": "Thoughts of ending my or someone else's life",
"media": "",
"exclusive": false,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken6>",
"text": "None of the above",
"media": "",
"exclusive": true,
"media_alttext": "",
"free_text": false
}
],
"answer": [
{
"token": "<AnswerToken6>",
"extra": ""
}
],
"interview": "<InterviewToken>",
"media_alttext": "",
"_links": {
"next": "https://api.sandbox.buoyhealth.com/symptom-checker/v2/questions/<QuestionToken2>/"
}
}
You'll see that the next question for the user is returned in the "next" parameter. Continue to respond to all remaining questions by getting the question and then answering with "No" or "None of the Above." If "No" or "None of the Above" are not answer options, respond with "Unsure." When you receive a link to a result, proceed to the next step.
7. Review results
To end the interview, send a GET request to the /api/results/<ResultToken> endpoint. You will receive an HTTP 200 response similar to the following:
{
"token": "<ResultToken>",
"alarm": false,
"undiagnosed": false,
"differential": [
{
"name": "Hyperventilation syndrome",
"overview": "In hyperventilation syndrome, one can experience shortness of breath and often a person breaths fast and heavily. There is usually no physical problem causing these symptoms, and symptoms are often caused by anxiety, stress or emotions. Next to shortness of breath, one can experience symptoms of chest pain, palpitations or tingling in hands, feet and face. These symptoms occur commonly as attacks.",
"care_notes": "You should go see your primary care doctor, who can diagnose you by interview and physical exam during an attack of hyperventilation. Most people get better with treatment. Treatment of an acute attack often includes reassuring and breathing instructions and sometimes taking a tranquilizer. Treatment to avoid recurrent episodes may include behavioural therapy, physiotherapy with breathing exercises and medication.",
"token": "<DxToken>",
"duration": "Lasts from 1 week up to many years",
"could_explain": "This could explain your rapid breathing.",
"cant_explain": "This wouldn't explain your sudden urgency to urinate.",
"usually_causes": "This is typically also associated with anxiety, difficulty getting enough air, and worsening symptoms with emotional stress.",
"triage": {
"token": null,
"level": 3,
"description": "Primary care doctor"
}
}
],
"triage": {
"token": null,
"level": 3,
"description": "Primary care doctor"
},
"triage_explanation": {
"explanation": "",
"potential_condition": null
}
}
🎉 Congratulations! You've completed your first interview. In the result, a differential diagnosis of "Hyperventilation syndrome" is returned, with "Primary care doctor" as the recommended care option. In the image below, you can see how the result is presented on Buoy's symptom checker.
Updated over 2 years ago