HRA Quickstart
The HealthHero HRA API (Swagger/ReDoc) provides health age, risk and wellness reports for the Health Risk Assessment product.
Prerequisites
Authentication
All requests require a bearer token to be provided in the Authorization header. See the Client Authentication guide for further details.
Complete an HRA traversal
Before you can request an HRA report you must first use the Traversal API to create and complete an HRA traversal, passing the correct product short code for the Health Assessment product: this may depend on your client configuration, but is typically HRA.
Once you have a completed traversal (one in which the respond endpoint returns a response with an empty nodes property), you can request reports for the traversal from the HRA API.
Load conclusions
Several of the HRA reports refer to Conclusions: pieces of advice on how the user can improve their health. You will need to call the conclusions endpoint of the Traversal API (ReDoc) to get all conclusions relevant to the traversal; you can then look up conclusions by assetId to get the text to display to the user.
Reports
All reports are implemented as GET requests and return JSON responses. For all requests you will need the traversalId from your completed HRA traversal.
Health risks
GET /api/v1/{tenantId}/reports/{traversalId}/risksIf you call this endpoint with no query string you will receive information about the user's health age, looking something like this:
{
"age": 38,
"ageAtDeath": 83,
"minimumAgeAtDeath": 91,
"healthAge": 37,
"minimumHealthAge": 29,
"averageLifeExpectancy": 82,
"maximumLifeExpectancy": 91,
"gender": "F",
"risks": [],
"checkableConclusions": [
...
3495,
3501,
3622,
...
]
}The checkableConclusions array contains the IDs of conclusions (recommendations) that may improve the user's results if implemented. Note that only a subset of these will be relevant to this particular assessment. For example, 3495 ("Stop smoking") will almost certainly be on the list, whether or not the user is a smoker; however, that conclusion will only be included in the list of conclusions returned by the Traversal API (and should thus be displayed to the user) if they do smoke.
If you include a list of "checked" conclusions in the query string, the API returns updated results that show the effect of carrying out these recommendations.
GET /api/v1/{tenantId}/reports/{traversalId}/risks?conclusions=3495&conclusions=3501Here we have checked conclusions 3495 ("Stop smoking") and 3501 ("Strive for an optimally active lifestyle"), which results in the following response: note that ageAtDeath and healthAge have improved accordingly.
{
"age": 38,
"ageAtDeath": 89,
"minimumAgeAtDeath": 91,
"healthAge": 31,
...
}To get data on risks you need to include in the query string a list of ages for which you want to calculate the risks.
GET /api/v1/{tenantId}/reports/{traversalId}/risks?ages=80&ages=90Here we are requesting risks at ages 80 and 90. The response includes an array of risks, each with a time property: this means the number of years from now. So, for example, our user has a 16.74% chance of contracting heart disease at some point within the next 52 years; that is, before the age of 90 (since they are now 38 years old).
{
"age": 38,
"ageAtDeath": 83,
...
"risks": [
{
"name": "Breast cancer",
"time": 42,
"current": 7.42,
"minimum": 4.83
},
{
"name": "Breast cancer",
"time": 52,
"current": 11.0,
"minimum": 7.22
},
...
{
"name": "Heart disease",
"time": 42,
"current": 9.27,
"minimum": 2.94
},
{
"name": "Heart disease",
"time": 52,
"current": 16.74,
"minimum": 5.46
},
...
],
"checkableConclusions": [
...
3495,
3501,
3622,
...
]
}If we check conclusions 3495 and 3501 as above...
GET /api/v1/{tenantId}/reports/{traversalId}/risks?ages=80&ages=90&conclusions=3495&conclusions=3501...the risk is reduced to 10.78%:
{
"age": 38,
"ageAtDeath": 89,
...
"risks": [
...
{
"name": "Heart disease",
"time": 42,
"current": 5.87,
"minimum": 2.94
},
{
"name": "Heart disease",
"time": 52,
"current": 10.78,
"minimum": 5.46
},
...
],
...
}For further details see Risk Output.
Wellness
GET /api/v1/{tenantId}/reports/{traversalId}/wellnessThis report comprises an array of scores out of 100 (the higher the better) for seven wellbeing categories, along with an array of checkableConclusions.
{
"scores": [
{
"name": "Diet",
"score": 25.0
},
{
"name": "Stress",
"score": 85.0
},
{
"name": "Habits",
"score": 50.0
},
{
"name": "Fitness",
"score": 60.0
},
{
"name": "Prevention",
"score": 100.0
},
{
"name": "Screening",
"score": 80.0
},
{
"name": "Overall Wellbeing",
"score": 10.0
}
],
"checkableConclusions": [
...
3495,
3501,
3622,
...
]
}Once again, include conclusions in the query string to get an updated report showing the result of implementing those recommendations.
GET /api/v1/{tenantId}/reports/{traversalId}/wellness?conclusions=3495&conclusions=3501Checking conclusions 3495 and 3501 improves the "Habits", "Fitness" and "Overall Wellbeing" scores:
{
"scores": [
{
"name": "Diet",
"score": 25.0
},
{
"name": "Stress",
"score": 85.0
},
{
"name": "Habits",
"score": 90.0
},
{
"name": "Fitness",
"score": 82.5
},
{
"name": "Prevention",
"score": 100.0
},
{
"name": "Screening",
"score": 80.0
},
{
"name": "Overall Wellbeing",
"score": 19.0
}
],
"checkableConclusions": [...]
}For further details see Wellness Output.