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

Mandatory endpoints

In the mandatory category we place the endpoints which form the backbone of the consultations. These are the minimally required endpoints to complete a consultation.

Endpoint	Description
Login	To access the `chat` endpoint you must first authenticate against the API. Please see Partner Authentication for more information. The `login` endpoint returns `access_token` and `expires_in` values.
Get Terms	Endpoint meant for getting all the legal data to review.
Accept Legal Terms	Endpoint for accepting the legal terms returned in the `GET /legal` endpoint.
Initial	In the initial consultation endpoint, the end user reports their symptoms as free text. This endpoint also requires you to send the age and gender. You can collect this data either from your existing records or from user input at the time of consultation. This endpoint can only be called once per consultation.
Chat	The chat endpoint is the core of the consultation flow. It asks rounds of questions until our system can resolve a consultation report. The questions can be of multiple types, and the constraints are clearly expressed.
Symptom Search	When the autocomplete question is asked, the user should be presented with an autocomplete box that calls this endpoint. This endpoint does a fuzzy search in our database of symptoms.
Step back	The step back endpoint allows the end user to go back one step at a time and change the answers to the previous questions. Not all questions allow taking a step back for technical reasons, this is clearly expressed in the responses. The response of the step back is the same as Chat.
Report	The report endpoint presents the final report. It can only be called when the chat response indicates that a report is available. Once this phase has been reached there is no way to go back and revise the previous answers.

Optional endpoints

In the optional category we place endpoints which are not required for the consultation itself but enrich the experience and data.

Endpoint	Description
Analytics	The analytics endpoint allows you to send varied analytics data to Healthily, such as UI analytics. We have a recommended list of analytics events to send. This enriches the data reporting we are able to do.
Get state	This endpoint simply points you to where the consultation was left. It has the same response type as the main Chat endpoint. In case the last state (or question) of the conversation was lost, use this endpoint to get it.
Feedback	This endpoint allows sending end user feedback at the end of the consultation. This includes a star rating as well as free text.
Article ID	Most times, at the end of a consultation the end user will be presented with article snippets. The article endpoints allow fetching the entire medically reviewed article to be presented in your integration. Article text might include external links to other resources or references, as well as internal links to other Healthily articles, which can be fetched using the same endpoint.
Articles	Same as above, but for multiple articles.

How it works

The API uses JWT tokens that are ephemeral and narrowly scoped to a single consultation and cannot be renewed.

Login is required before any other API operation can take place. When you registered with Healthily, you received a set of credentials consisting of a partnerId, secret and api_key. Treat these as confidential credentials, store them in a secure vault and restrict access to a limited number of backend services and authorised employees.

Once you login, you will have access to the legal endpoints GET /terms and POST /terms. The terms must be first retrieved and then accepted. The response contains an upgraded JWT token, which needs to be then used for the rest of the API calls.

For as long as the login Authorization is valid, you can continue using the chat. From this point every API request will automatically be linked to a consultation based on the jwt, and you will not need to pass any discrete IDs to us.

📘
The JWT claim sid should be stored in your systems for your reference. In case of any bug reports this will be required for us to identify the consultation.