Introduction

Healthily offers an AI-driven symptom checker and assessment platform. It allows users to monitor health, manage 100s of conditions, track progress and much more.

The Healthily symptom checker can be integrated into third-party solutions by using our REST API.

The API allows developers to integrate Healthily's ground-breaking conversational AI technology into their own applications.

Endpoints

The API has 5 main endpoints:

Endpoint	Description
login	To access the `chat` endpoint you must first authenticate against the API. Please see Authentication for more information. The `login` endpoint returns `access_token` and `expires_in` values.
logout	The `logout` endpoint invalidates `access_token` provided by the `login` endpoint.
chat	The `chat` endpoint is responsible for the Conversational AI experience. Calls to the `chat` endpoint returns all the information necessary to develop a chatbot based on the Healthily symptom checker.
Search symptoms	Allows a search of symptoms to be formed based on complete or partial user input. Returns a list of recognised symptoms.
Search articles	Allows a search of articles from the Healthily library, based on recognised symptom ids returned from the `search/symptoms` endpoint.

How it works

The API uses JWT tokens that are ephemeral and may need to be renewed whilst a dialogue is in progress. The HTTP Authorization header is used to generate JWT tokens as well as verifying the supplied API key, using the “token” and “bearer” components of the header.

Login is required before any other API operation can take place. You will be issued with one or more API keys that are used for this purpose where login is performed on behalf of the user. The response includes a JWT "access_token" that is unique for the supplied user information and this must be used from this point by including it in the HTTP Authorization header using the “token_type” component.

For as long as the login Authorization is valid, you can continue using the chat. From this point every API response will contain a JSON object called "conversation". This object contains an "id" key, which must be passed to next request in a top level "conversation" object. For example:

{
    "answer": {
        "type": "generic",
        "input": {
            "exclude": [""],
            "include": ["add_symptoms"]
        }
    },
    "conversation": {
        "id": "YOUR_CONVERSATION_ID"
    }
}

The API consists of a single endpoint used through the duration of the chat which operates on a challenge/response basis and where the API request is constructed from information provided in the previous API response.

After POSTing the API request, a response is retrieved in the form of a JSON body and then depending on what stage of the interaction the user is at, the response may take the form of free text or a specifically required answer format, see responding to questions.

Before embarking on building a solution we would recommend looking at how we at Healthily have used the API ourselves to build the Smart Symptom Checker called Dot in our iOS and Android apps, or in our webapp here.