Responding to questions
Goal
At the end of this tutorial, you will have learned how to respond to the three different types of questions Buoy's symptom checker API asks. Those types are:
- Single-response questions
- Multi-response questions
- Duration-response questions
Notes
- We recommend completing the completing your first interview tutorial before completing this tutorial.
- We recommend using our Postman collection while completing this tutorial.
- Buoy's interviews are dynamic. The questions proposed by our AI as well as the answer options available may change from time to time. This tutorial is written in a way to provide flexibility for that change. However, if you have any questions, please review our service desk documentation.
Responding to questions, step by step
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 65-year-old female.
curl -XPOST \
-H 'Authorization: Bearer <token>' \
-H "Content-type: application/json" \
-d '{
"profile": {
"sex": "f",
"age": 65
}
}' '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. Note the token that the interview returns. This token uniquely identifies an interview to 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": 65.0,
"sex": "f"
},
"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. Add a user complaint of "knee pain"
To do this, POST a request to the /api/complaints/ endpoint.
curl -XPOST \
-H 'Authorization: Bearer <token>' \
-H "Content-type: application/json" \
-d '{
"query": "knee pain",
"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": "knee pain",
"interpretations": [
{
"token": "<InterpretationToken1>",
"title": "knee pain",
"description": "My knee hurts"
},
{
"token": "<InterpretationToken2>",
"title": "moderate knee pain",
"description": "My knee pain is moderate, like a 5 or 6 out of 10"
},
{
"token": "<InterpretationToken3>",
"title": "mild knee pain",
"description": "My knee pain is mild, like a 2 or 3 out of 10"
},
{
"token": "<InterpretationToken4>",
"title": "pain in the inside of the knee",
"description": "My knee pain is on the inner half (toward the midline of the body)"
}
],
"clarification": []
}
Update the complaint with the interpretation token corresponding to "My knee hurts" 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": "<InterpretationToken1>"
}]
}' 'https://api.sandbox.buoyhealth.com/symptom-checker/v2/complaints/<ComplaintToken>/'
You should receive an HTTP 200 response with a response similar to that in the screen below.
{
"token": "<ComplaintToken>",
"interview": "<InterviewToken>",
"query": "knee pain",
"interpretations": [
{
"token": "<InterpretationToken1>",
"title": "knee pain",
"description": "My knee hurts"
},
{
"token": "<InterpretationToken2>",
"title": "moderate knee pain",
"description": "My knee pain is moderate, like a 5 or 6 out of 10"
},
{
"token": "<InterpretationToken3>",
"title": "mild knee pain",
"description": "My knee pain is mild, like a 2 or 3 out of 10"
},
{
"token": "<InterpretationToken4>",
"title": "pain in the inside of the knee",
"description": "My knee pain is on the inner half (toward the midline of the body)"
}
],
"clarification": [
{
"token": "<InterpretationToken1>"
}
],
"_links": {
"next": "https://api.sandbox.buoyhealth.com/symptom-checker/v2/questions/<QuestionToken>/"
}
}
4. Responding to questions
Adding an interpretation of "My knee hurts" will generate follow-up questions designed to clarify the user's complaint.
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": "Is your knee pain getting better or worse?",
"choice": "S",
"media": "",
"options": [
{
"token": "<AnswerToken1>",
"text": "Getting better",
"media": "",
"exclusive": true,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken2>",
"text": "Staying the same",
"media": "",
"exclusive": true,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken3>",
"text": "Getting worse",
"media": "",
"exclusive": true,
"media_alttext": "",
"free_text": false
}
],
"answer": [],
"interview": "<InterviewToken>",
"media_alttext": ""
}
Single-response questions
Note that the "choice" parameter has a value of "S." The "S" indicates that a question type is single-response. With single-response questions, users may submit one answer option. To respond to the question, send a PUT request to the /api/questions/<QuestionToken> endpoint. Select the answer token corresponding to "Getting worse."
curl -XPUT \
-H 'Authorization: Bearer <token>' \
-H "Content-type: application/json" \
-d '{
"answer": [
{
"token": "<AnswerToken3>",
"extra": ""
}
]
}' 'https://api.sandbox.buoyhealth.com/symptom-checker/v2/questions/<QuestionToken>'
You will receive an HTTP 200 response similar to that in the screen below. The answer token associated with "Getting worse" should be returned in the answer parameter.
{
"token": "<QuestionToken>",
"text": "Is your knee pain getting better or worse?",
"choice": "S",
"media": "",
"options": [
{
"token": "<AnswerToken1>",
"text": "Getting better",
"media": "",
"exclusive": true,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken2>",
"text": "Staying the same",
"media": "",
"exclusive": true,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken3>",
"text": "Getting worse",
"media": "",
"exclusive": true,
"media_alttext": "",
"free_text": false
}
],
"answer": [
{
"token": "<AnswerToken3>",
"extra": ""
}
],
"interview": "<InterviewToken>",
"media_alttext": "",
"_links": {
"next": "https://api.sandbox.buoyhealth.com/symptom-checker/v2/questions/<QuestionToken>/"
}
}
When reading the next question, you will receive another single-response question: "Is your knee pain constant or come-and-go?" Try responding to the question with the answer token associated with the text "Constant."
Duration-response questions
Next, the Buoy symptom checker API will ask the user, "How long has your knee pain been going on?" If you haven't already, GET this question from the /api/questions/<QuestionToken> endpoint.
{
"token": "<QuestionToken>",
"text": "How long has your knee pain been going on?",
"choice": "D",
"media": "",
"options": [
{
"token": "<AnswerToken>",
"text": "Sole duration option",
"media": "",
"exclusive": true,
"media_alttext": "",
"free_text": false
}
],
"answer": [],
"interview": "<InterviewToken>",
"media_alttext": ""
}
Note that the "choice" parameter now has a value of "D", indicating that this question is requesting information around time duration from the user. You'll also see "Sole duration option" as the answer option text. To respond to duration-response questions like this one, populate the extra parameter with the duration, in hours, that the user has been experiencing the topic described in the question text. For example, if the duration time is eight hours, input "8" into the extra parameter (see below). If you are using our Postman collection, update the "AnswerExtra" environment variable.
curl -XPUT \
-H 'Authorization: Bearer <token>' \
-H "Content-type: application/json" \
-d '{
"answer": [
{
"token": "<AnswerToken>",
"extra": "8"
}
]
}' 'https://api.sandbox.buoyhealth.com/symptom-checker/v2/questions/<QuestionToken>'
Answer the remaining question, "How severe is your knee pain?", with the answer token associated with "Severe: close to the worst pain I have ever experienced." Next, advance the interview to the protocol mode and then retrieve the first protocol question.
If needed, review the tutorial, "Completing your first interview", for a refresher on advancing interview modes.
Multi-response questions
Next, the Buoy symptom checker API will ask the user, "Do you have any of the following related symptoms?" If you haven't already, GET this question from the /api/questions/<QuestionToken> endpoint.
{
"token": "<QuestionToken>",
"text": "Do you have any of the following related symptoms?",
"choice": "M",
"media": "",
"options": [
{
"token": "<AnswerToken1>",
"text": "Inability to stand on both legs",
"media": "",
"exclusive": false,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken2>",
"text": "Knee injury",
"media": "",
"exclusive": false,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken3>",
"text": "Change in shape (deformity) of leg",
"media": "",
"exclusive": false,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken4>",
"text": "None of the above",
"media": "",
"exclusive": true,
"media_alttext": "",
"free_text": false
}
],
"answer": [],
"interview": "<InterviewToken>",
"media_alttext": ""
}
Note that the "choice" parameter has a value of "M." The "M" indicates that a question type is multi-response, meaning that users may submit one or more answer options. You'll also see that the "None of the above" option has the "exclusive" parameter set to "True". Exclusive options may not be submitted with any other responses (e.g. a user can't select "Inability to stand on both legs" and "None of the above" as part of the same response).
To respond to the question with two responses – "Inability to stand on both legs" and "Knee injury" – send the following PUT request to the /api/questions/<QuestionToken> endpoint. Be sure to replace "<AnswerToken1>" and "<AnswerToken2>" with the tokens returned by the previous GET request to the endpoint.
curl -XPUT \
-H 'Authorization: Bearer <token>' \
-H "Content-type: application/json" \
-d '{
"answer": [
{
"token": "<AnswerToken1>",
"extra": ""
},
{
"token": "<AnswerToken2>",
"extra": ""
}
]
}' 'https://api.sandbox.buoyhealth.com/symptom-checker/v2/questions/<QuestionToken>'
You will receive an HTTP 200 response similar to the following. Note that both tokens are returned in the response.
{
"token": "<QuestionToken>",
"text": "Do you have any of the following related symptoms?",
"choice": "M",
"media": "",
"options": [
{
"token": "<AnswerToken1>",
"text": "Inability to stand on both legs",
"media": "",
"exclusive": false,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken2>",
"text": "Knee injury",
"media": "",
"exclusive": false,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken3>",
"text": "Change in shape (deformity) of leg",
"media": "",
"exclusive": false,
"media_alttext": "",
"free_text": false
},
{
"token": "<AnswerToken4>",
"text": "None of the above",
"media": "",
"exclusive": true,
"media_alttext": "",
"free_text": false
}
],
"answer": [
{
"token": "<AnswerToken1>",
"extra": ""
},
{
"token": "<AnswerToken2>",
"extra": ""
}
],
"interview": "<InterviewToken>",
"media_alttext": "",
"_links": {
"result": "https://api.sandbox.buoyhealth.com/symptom-checker/v2/results/{ResultToken}/"
}
}
🎉 Congratulations! You've responded to all three question types.
Updated almost 3 years ago