Complaints

Overview

In medicine, the chief complaint represents the reason for a medical encounter. The complaint may describe a symptom, problem, condition, diagnosis, or physician-recommended return. Some regions may use other terms, such as "reason for encounter" or "presenting problem." At Buoy, "chief complaint" refers to that same concept. The complaints API allows you to create and manage chief complaints within the context of an interview.

The process of entering a complaint is typically comprised of the following stages:

1. Complaint entry ("query")
2. Interpretation selection
3. Clarification

1. Complaint entry

Users are free to describe their symptoms as they choose. For example, a user may choose to describe a symptom as "My head hurts" or "hip pain." API clients should use the /api/queries/ endpoint in order to return a list of possible query suggestions based on past user entry. The suggestions array is ordered from best match to worst match and should be presented to the user in the order returned by the endpoint.

Request

curl -XGET -H "Authorization: Bearer <token>" \
'https://api.sandbox.buoyhealth.com/symptom-checker/v2/queries/?text=hip+pain&tag=1'

Response

{
    "text": "hip pain",
    "tag": "1",
    "suggestions": [
        "hip pain",
        "hip pain when walking",
        "hip pain radiating",
        "hip pain and swelling",
        "hip pain at night",
        "hip pain radiating down leg",
        "hip pain both sides",
        "hip pain and weakness",
        "hip pain left side",
        "hip pain on right side"
    ]
}

Example user query

Because network latency is sometimes greater than user typing speed, it is possible that the client will receive responses from the /api/queries/ endpoint out of order. For this reason, the API accepts an optional tag parameter. The server will include the tag, in addition to the original query text, with each response. The best tag is a monotonically increasing integer so the client knows only to display a response if the number is greater than the current number.

2. Interpretation selection

User queries should be submitted to the /api/complaints/ endpoint. A list of interpretations will be provided for the user to select from. For example, if a user enters a query of "hip pain", an interpretation might be, "I have hip pain." After a user selects an interpretation, the API client should put an update to the /api/complaints/ endpoint. If the user is unable to find an interpretation that matches their symptom, they should try again by entering a new query.

Request

curl -XPOST \
-H "Content-type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{
    "query": "hip pain",
    "interview": "<InterviewToken>"
}' 'https://api.sandbox.buoyhealth.com/symptom-checker/v2/complaints/'

Response

{
    "token": "<ComplaintToken>",
    "interview": "<InterviewToken>",
    "query": "hip pain",
    "interpretations": [
        {
            "token": "<InterpretationToken1>",
            "title": "hip pain",
            "description": "I have hip pain"
        },
        {
            "token": "<InterpretationToken2>",
            "title": "deep, throbbing hip pain",
            "description": "The hip pain is deep and throbbing"
        },
        {
            "token": "<InterpretationToken3>",
            "title": "dull, achy hip pain",
            "description": "The hip pain is dull and achy"
        },
        {
            "token": "<InterpretationToken4>",
            "title": "pain in one hip",
            "description": "One of my hips hurts"
        },
    ],
    "clarification": []
}

Example interpretations for a hip pain query, including "I have hip pain."

3. Clarification

Many complaints will generate several questions designed to clarify a complaint. These questions most commonly ask users to clarify the severity and duration of a complaint. For more details on how to respond to these questions, refer to the questions explainer or the questions API reference.

Example questions for the "I have hip pain" interpretation.

Limiting complaints

API clients must be sure to limit the number of chief complaints a user may submit. Too many chief complaints can confuse Buoy. One to three symptoms is an acceptable range of chief complaints. Buoy also performs better when the user limits these symptoms to those that are most pertinent. For example, "fatigue" may be a good chief complaint if the user believes its cause is not easily explained by a general lack of sleep. A good implementation will limit the number of chief complaints and provide helpful tips for choosing chief complaints.