Goal

By the end of this tutorial, you will have completed an interview that triggers a triage-only result from the protocol interview mode using Buoy's symptom checker API.

Notes

We recommend completing the tutorial, "Completing your first interview", and then responding to these questions before completing this tutorial. To learn more about the difference between the "protocol" and "differential" interview modes, please revisit steps 3 and 4 of the interview flow explainer.
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 to provide flexibility for change. However, if you have any questions, please review our service desk documentation.

Respond to questions

1. Ensure that you are 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. Ensure that you replace <token> with your access token in each of the requests below.

2. Create an anonymous interview

To do this, POST to the /api/interviews/anonymous/ endpoint. You will be starting the interview on behalf of a 72-year-old male.

curl -XPOST \
-H 'Authorization: Bearer <token>' \
-H "Content-type: application/json" \
-d '{
    "profile": {
        "sex": "m",
        "age": 72
    }
}' 'https://api.sandbox.buoyhealth.com/symptom-checker/v2/interviews/anonymous/'

You should receive a HTTP 200 response like the one below, indicating that an interview was successfully started. Note that the interview returns a token. This token uniquely identifies an interview 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": 72.0,
        "sex": "m"
    },
    "start_time": "04/07/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. Add a user complaint of "difficulty breathing"

To do this, POST a request to the /api/complaints/ endpoint.

curl -XPOST \
-H 'Authorization: Bearer <token>' \
-H "Content-type: application/json" \
-d '{
    "query": "difficulty 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": "difficulty breathing",
    "interpretations": [
        {
            "token": "<InterpretationToken1>",
            "title": "mouth breathing",
            "description": "I am breathing with my mouth"
        },
        {
            "token": "<InterpretationToken2>",
            "title": "difficulty getting enough air",
            "description": "I have breathlessness or difficulty getting air into my chest"
        },
        {
            "token": "<InterpretationToken3>",
            "title": "choking",
            "description": "I am choking"
        },
        {
            "token": "<InterpretationToken4>",
            "title": "stuffy nose",
            "description": "My nose is stuffed"
        },
        {
            "token": "<InterpretationToken5>",
            "title": "trouble swallowing",
            "description": "Food or drinks get stuck or will not go down when I swallow"
        }
    ],
    "clarification": []
}

Update the complaint with the interpretation token corresponding to "I have breathlessness or difficulty getting air into my chest" by sending a PUT request to the /api/complaints/<ComplaintToken> endpoint.

curl -XPUT \
-H 'Authorization: Bearer <token>' \
-H "Content-type: application/json" \
-d '{
    "interview": "<InterviewToken>",
    "clarification": [{
        "token": "<InterpretationToken2>"
    }]
}' '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": "difficulty breathing",
    "interpretations": [
        {
            "token": "<InterpretationToken1>",
            "title": "mouth breathing",
            "description": "I am breathing with my mouth"
        },
        {
            "token": "<InterpretationToken2>",
            "title": "difficulty getting enough air",
            "description": "I have breathlessness or difficulty getting air into my chest"
        },
        {
            "token": "<InterpretationToken3>",
            "title": "choking",
            "description": "I am choking"
        },
        {
            "token": "<InterpretationToken4>",
            "title": "stuffy nose",
            "description": "My nose is stuffed"
        },
        {
            "token": "<InterpretationToken5>",
            "title": "trouble swallowing",
            "description": "Food or drinks get stuck or will not go down when I swallow"
        }
    ],
    "clarification": [
        {
            "token": "<InterpretationToken2>"
        }
    ],
    "_links": {
        "next": "https://api.sandbox.buoyhealth.com/symptom-checker/v2/questions/<QuestionToken>/"
    }
}

GET the first question from 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:

{
    "token": "<QuestionToken>",
    "text": "How long have you been having difficulty breathing?",
    "choice": "D",
    "media": "",
    "options": [
        {
            "token": "<AnswerToken>",
            "text": "Sole duration option",
            "media": "",
            "exclusive": true,
            "media_alttext": "",
            "free_text": false
        }
    ],
    "answer": [],
    "interview": "<InterviewToken>",
    "media_alttext": ""
}

Respond to the question by sending a PUT request to the /api/complaints/<ComplaintToken> endpoint. Populate the "extra" parameter with the value "2" to indicate that the user's difficulty breathing has been ongoing for two hours.

curl -XPUT \
-H 'Authorization: Bearer <token>' \
-H "Content-type: application/json" \
-d '{
  "answer": [
    {
        "token": "<AnswerToken>",
        "extra": "2"
    }
  ]
}' 'https://api.sandbox.buoyhealth.com/symptom-checker/v2/questions/<QuestionToken>'

You will receive an HTTP 200 response similar to the following:

{
    "token": "<QuestionToken>",
    "text": "How long have you been having difficulty breathing?",
    "choice": "D",
    "media": "",
    "options": [
        {
            "token": "<AnswerToken>",
            "text": "Sole duration option",
            "media": "",
            "exclusive": true,
            "media_alttext": "",
            "free_text": false
        }
    ],
    "answer": [
        {
            "token": "<AnswerToken>",
            "extra": "2"
        }
    ],
    "interview": "<InterviewToken>",
    "media_alttext": "",
    "_links": {
        "next": "https://api.sandbox.buoyhealth.com/symptom-checker/v2/questions/<QuestionToken>/"
    }
}

GET the next question from the /api/questions/<QuestionToken> endpoint. Respond to the question, "How severe is your difficulty breathing?", with the answer token associated with, "Uncomfortable, can only say a few words at a time."

curl -XPUT \
-H 'Authorization: Bearer <token>' \
-H "Content-type: application/json" \
-d '{
  "answer": [
    {
        "token": "<AnswerToken2>",
        "extra": ""
    }
  ]
}' 'https://api.sandbox.buoyhealth.com/symptom-checker/v2/questions/<QuestionToken>'

After responding to the question, you will receive an HTTP 200 response similar to the following:

{
    "token": "<QuestionToken>",
    "text": "How severe is your difficulty breathing?",
    "choice": "S",
    "media": "",
    "options": [
        {
            "token": "<AnswerToken1>",
            "text": "Noticeable, but can still speak in full sentences",
            "media": "",
            "exclusive": true,
            "media_alttext": "",
            "free_text": false
        },
        {
            "token": "<AnwerToken2>",
            "text": "Uncomfortable, can only say a few words at a time",
            "media": "",
            "exclusive": true,
            "media_alttext": "",
            "free_text": false
        },
        {
            "token": "<AnswerToken3>",
            "text": "Feels or seems like suffocating, can only say one word at a time",
            "media": "",
            "exclusive": true,
            "media_alttext": "",
            "free_text": false
        }
    ],
    "answer": [
        {
            "token": "<AnswerToken2>",
            "extra": ""
        }
    ],
    "interview": "<InterviewToken>",
    "media_alttext": ""
}

Note that there are no additional questions for the complaint.

4. Advance the interview to "protocol" mode

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 200 response similar to the following:

{
    "token": "<InterviewToken>",
    "start_time": "04/07/2021 12:55:45",
    "end_time": null,
    "location": {
        "latitude": 45.5496,
        "longitude": -122.8293,
        "postal_code": "97229",
        "country": "US",
        "approximate": true
    },
    "mode": "protocol",
    "should_display_alarm": false,
    "_links": {
        "next": "https://api.sandbox.buoyhealth.com/symptom-checker/v2/questions/<QuestionToken>/"
    }
}

GET the first protocol mode question from the /api/questions/<QuestionToken> endpoint. You will receive an HTTP 200 response similar to the following:

{
    "token": "<QuestionToken>",
    "text": "Do you have any of the following related symptoms?",
    "choice": "M",
    "media": "",
    "options": [
        {
            "token": "<AnswerToken1>",
            "text": "Change in alertness or responsiveness",
            "media": "",
            "exclusive": false,
            "media_alttext": "",
            "free_text": false
        },
        {
            "token": "<AnswerToken2>",
            "text": "Blue lips or tongue",
            "media": "",
            "exclusive": false,
            "media_alttext": "",
            "free_text": false
        },
        {
            "token": "<AnswerToken3>",
            "text": "Chest pain or discomfort",
            "media": "",
            "exclusive": false,
            "media_alttext": "",
            "free_text": false
        },
        {
            "token": "<AnswerToken4>",
            "text": "Fainting",
            "media": "",
            "exclusive": false,
            "media_alttext": "",
            "free_text": false
        },
        {
            "token": "<AnswerToken5>",
            "text": "None of the above",
            "media": "",
            "exclusive": true,
            "media_alttext": "",
            "free_text": false
        }
    ],
    "answer": [],
    "interview": "<InterviewToken>",
    "media_alttext": ""
}

The protocol interview mode typically starts by asking the user to select from a list of related symptoms. Respond to the question with the answer token corresponding to "Blue lips or tongue." After sending a PUT request to the /api/questions/<QuestionToken> endpoint, you will receive an HTTP 200 response similar to the following:

{
    "token": "<QuestionToken>",
    "text": "Do you have any of the following related symptoms?",
    "choice": "M",
    "media": "",
    "options": [
        {
            "token": "<AnswerToken1>",
            "text": "Change in alertness or responsiveness",
            "media": "",
            "exclusive": false,
            "media_alttext": "",
            "free_text": false
        },
        {
            "token": "<AnswerToken2>",
            "text": "Blue lips or tongue",
            "media": "",
            "exclusive": false,
            "media_alttext": "",
            "free_text": false
        },
        {
            "token": "<AnswerToken3>",
            "text": "Chest pain or discomfort",
            "media": "",
            "exclusive": false,
            "media_alttext": "",
            "free_text": false
        },
        {
            "token": "<AnswerToken4>",
            "text": "Fainting",
            "media": "",
            "exclusive": false,
            "media_alttext": "",
            "free_text": false
        },
        {
            "token": "<AnswerToken5>",
            "text": "None of the above",
            "media": "",
            "exclusive": true,
            "media_alttext": "",
            "free_text": false
        }
    ],
    "answer": [
        {
            "token": "<AnswerToken2>",
            "extra": ""
        }
    ],
    "interview": "<InterviewToken>",
    "media_alttext": "",
    "_links": {
        "result": "https://api.sandbox.buoyhealth.com/symptom-checker/v2/results/<ResultToken>/"
    }
}

Instead of a new question, a result will be returned. GET the result by calling the /api/results/<ResultToken> endpoint. You will receive an HTTP 200 response similar to the following:

{
    "token": "<ResultToken>",
    "alarm": true,
    "undiagnosed": true,
    "differential": [],
    "triage": {
        "token": "<TriageToken>",
        "level": 7,
        "description": "Emergency medical service"
    },
    "triage_explanation": {
        "explanation": "Because of your blue lips or tongue and difficulty getting enough air, you may have coronavirus.",
        "potential_condition": {
            "name": "coronavirus",
            "overview": "Call 911 and mention you may have coronavirus so they can prepare.",
            "care_notes": "There is no treatment to cure coronavirus (COVID-19), but it is advised to see a healthcare provider for testing. Mild symptoms can be treated the same as one would do for the common cold or flu. Very young children, the elderly, and people with known (heart- or lung) disease or a suppressed immune system can become more ill. These people might need extra support or treatment to help with breathing issues. It is very important to prevent the virus from spreading by washing hands frequently, covering mouth and nose while sneezing and coughing, and by staying away from other people when sick."
        }
    }
}

Compare this result to the result returned in the "Completing your first interview" tutorial. Note that the interview did not return a differential, but instead returned a triage and triage explanation. Remember – while in protocol mode, Buoy's primary concern is safety. Because of this, questions will result in triage recommendations instead of differential recommendations. In the example above, the user should be triaged to EMS because of to their blue lips or tongue and difficulty getting enough air.