Doctorlink has joined HealthHerohealthheroLearn More
doctorlink

Quickstart

This short tutorial will get you started with the HealthHero Traversal API. Subsequent sections of this documentation describe our API in greater detail, but if you're short on time and already have experience with web services, this is a quick overview of how to get up and running with the HealthHero Traversal API.

Setup

The current version of the HealthHero Traversal API (Swagger/ReDoc) is a standard web service that accepts GET and POST requests. All responses, including error messages, use JSON format. POST requests also accept a JSON body, and one must include the header Content-Type: application/json for them to function.

Authentication

All calls to the HealthHero APIs, whether from something like Postman or from your own application, require the HTTP authorisation header in the form of a bearer token: Authorization: Bearer ACCESS_TOKEN. The token itself should be obtained from the Identity Server using your client credentials with the grant_type of client_credentials.

For a more in-depth look at Authentication, please look at our Client Authentication guide.

If you do not have client credentials you can contact support team to request developers access.

First request

The first request you're likely to make will be a POST method to /api/v1/{tenantId}/Traversals, where {tenantId} is your client_id. This will require a JSON object describing the product you wish to start. There are a few products you could perform (given the access,) but let's assume you wish to begin an Online triage (aka Symptom Assessment). For simplicity's sake, we'll keep the data to a bare-minimum and only make the request with a product short code (the only required parameter).

The JSON object for an initial POST request is described in more detail in another section.

In the simplest case described above the POST request would be made with the following JSON object: 

{
    "shortCode": "XYZ"
}

So, your first request to the API, using cURL, could look like this:

curl ".../api/v1/{tenantId}/Traversals" \
  -X "POST" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" -d '{
    "shortCode": "XYZ"
}'

And, that's it! If you've set it up correctly, and your client credentials are authorised, you've taken the first step to performing an entire traversal.

Output

Nodes | Questions | Answers

The reponse returned from /api/v1/{tenantId}/Traversals will contain, among other properties, a TraversalId. This is a Guid representing your traversal through the Online triage (aka Symptom Assessment), and you will require this Id in all your calls to the API from this point onward.

There are several other properties in the response but we'll only go into the basics for now...

{
   ...
   "traversalId": "xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx",
   "nodes": [...]
   ...
}

Because the API is stateful, you may perform a GET /api/v1/{tenantId}/Traversals/{traversalId} request at any time to carry on from where you left off.

TraversalId : Your unique traversal Identifier.

Nodes : An array of Nodes. More than one Node indicates the content creator wishes you to see more than one set of questions at a time. If you opt to use the /api/v1/{tenantId}/ChatTraversals endpoints, you will only ever see one node with one question at a time.

A full sample of response data is available to see the whole package.

Nodes

Nodes are a collection of objects that contain, above all, the questions. Other properties include AssetId, Data, and Explanation. But the only parts you need to worry about for now are the nodeId and questions:

[
	{
	     "questions": [...],
	     "nodeId": 2,
	     "algoId": 4550
	 },
	 ...
 ]

A more detailed description can be found on the Node page.

Questions

Questions and answers are the bread and butter of our APIs. These can be used to build a conversation-like interface that could, for example, represent the way a clinician might interview a patient. Our first call to the API returned a single question asking the user who they're answering for:

{
	"answers": [...],
	"displayText": "Welcome. Before we start, we need to know a few basic things...",
	"explanation": "",
	"questionId": 13045,
	"title": null
}

More information about questions can be found on the Question page.

Answers

Answers come in a variety of types, and need to be displayed using the appropriate markup for your appllication. These are represented by the controlType property and will be one of the following string values: Checkbox, Radio, Text, Number, Date, Hidden.

As we can see, our first call has given us two answers. As they are both of the Radio controlType, the user must choose between them. 

[{
   "nodeId":2,
   "questionId":13045,
   "answerId":7527,
   "controlType":"Radio",
   "controlValue":null,
   "controlChecked":false,
   "displayText":"Myself",
   "explanation":"",
   "data":{
      "Properties":{
         "Self":"True"
      }
   }
},
{
   "nodeId":2,
   "questionId":13045,
   "answerId":7528,
   "controlType":"Radio",
   "controlValue":null,
   "controlChecked":false,
   "displayText":"Someone else",
   "explanation":"",
   "data":{
      "Properties":{
         "Self":"False"
      }
   }
}]

first-question.png

More information about answers can be found on the Answer page.

Next steps

Once the user has made their choice, you can POST the data to the API respond endpoint /api/v1/{tenantId}/Traversals/{traversalId}/respond. This endpoint requires a list of values that were answered. So, for our first question, we would respond with something like this:

[{
	"nodeId": 2,
	"questionId": 13045,
	"answerId": 7527,
	"value": null
}]
curl ".../api/v1/{tenantId}/Traversals/{traversalId}/respond" \
  -X "POST" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" -d '[{
	"nodeId": 2,
	"questionId": 13045,
	"answerId": 7527,
	"value": null
}]'

Because the question was a radio list, we only need to send one answer back. If it were a checkbox list, we may need to send many answers. And, in this instance, there is no value as nothing required the user to type. If the question had been Text, Date, or Number we would expect to see that value of the input in the value property.

Now that you can move forward, you may want to try moving back. To return to the previous node you must call the previous endpoint (ReDoc) .This is a Post request, but with no body content, and will return traversal to the last seen question:

curl ".../api/v1/{tenantId}/Traversals/{traversalId}/previous" \
  -X "POST" \
  -H "Authorization: Bearer ACCESS_TOKEN"

The previous answer supplied will be in the response and should be filled out on the UI components. The user may then choose to change it, or move forward again. In both cases the question will be reprocessed to determine the next question (which could change based on the new answer given).

Congratulations! You're now able to move forward and backward through an Online triage (aka Symptom Assessment).

But wait! There's more...

What happens when I get to the end? What if I answer a question wrong and need to go back? There are answers to these questions, and more, in our extended guides. See below for links.