healthR is a service that allows healthcare organisations and digital health solution providers to access data from the best health apps and devices through a single API and data model.
This document provides an overview of the different ways the service can be used, along with information on how to use the API and the normalised data model.
The service currently supports the following data sources via Web APIs provided by device vendors:
We can also help you integrate data from Apple Health natively from your app into your backend / cloud platforms. Data from Apple Health resides on the device and needs to be integrated by calling the Apple Health APIs locally on the device.
The healthR service allows your users to connect and authorise their wearables device account to your app. The service then polls the device account for new data at regular intervals. Data from the different devices is normalised into a simple data model that can be consumed via a HTTP API (with JSON payload) or directly via the data store.
Below is a list of the data categories available:
As well as data from consumer and clinical wearable devices, we also integrate with the following EHR vendors. Our integration allows patients to authorise their records to be shared with health providers using healthR for remote patient monitoring and care management.
The integration allows for a patient's CCD (Continuity of Care Document) to be retrieved and accessed alongside the wearable data. The CCD is stored in the CDA XML format as part of the records for a particular user.
The normalised data model contains the following fields:
| Name | Description | Type | Additional information |
|---|---|---|---|
| ID |
Record ID |
globally unique identifier |
None. |
| AccountID |
ID for the account |
globally unique identifier |
None. |
| RecordDate |
Record Date |
date |
None. |
| Category |
Record Category |
string |
None. |
| Reading |
Reading value |
decimal number |
None. |
| SNOMEDCode |
The SNOMED Code for the record |
string |
None. |
| Unit |
Reading Unit |
string |
None. |
| Device |
Device the data came from |
string |
None. |
| Data |
Text data value |
string |
None. |
| Title |
Record title |
string |
None. |
| UserAccount |
Details of the account |
AccountDataResponse |
None. |
Example output as JSON is below:
[
{
"ID": "cffac13a-6ad0-40e9-9fe2-53867fe1dcc9",
"AccountID": "3302f99a-d455-40c5-877f-22e4170f5950",
"RecordDate": "2022-12-31T12:00:48.2974266+00:00",
"Category": "sample string 4",
"Reading": 5.0,
"SNOMEDCode": "sample string 6",
"Unit": "sample string 7",
"Device": "sample string 8",
"Data": "sample string 9",
"Title": "sample string 10",
"UserAccount": {
"ID": "d13096d7-c65b-4c61-bdc3-364cf0e149c0",
"ExternalID": "sample string 2",
"Created": "2022-12-31T12:00:48.2974266+00:00",
"Country": "sample string 3",
"Name": "sample string 4",
"Age": "sample string 5",
"Location": "sample string 6",
"DateOfBirth": "sample string 7",
"Gender": "sample string 8"
}
},
{
"ID": "cffac13a-6ad0-40e9-9fe2-53867fe1dcc9",
"AccountID": "3302f99a-d455-40c5-877f-22e4170f5950",
"RecordDate": "2022-12-31T12:00:48.2974266+00:00",
"Category": "sample string 4",
"Reading": 5.0,
"SNOMEDCode": "sample string 6",
"Unit": "sample string 7",
"Device": "sample string 8",
"Data": "sample string 9",
"Title": "sample string 10",
"UserAccount": {
"ID": "d13096d7-c65b-4c61-bdc3-364cf0e149c0",
"ExternalID": "sample string 2",
"Created": "2022-12-31T12:00:48.2974266+00:00",
"Country": "sample string 3",
"Name": "sample string 4",
"Age": "sample string 5",
"Location": "sample string 6",
"DateOfBirth": "sample string 7",
"Gender": "sample string 8"
}
}
]
The healthR service is built using a multi-tenant model and the HTTP API has the following main functions:
The API uses GET and POST verbs to manage operations.
An API Key is used to authenticate an organisation / tenant. The key is provided by our admin team and should passed using the Authorization header in each request made to the API, as follows:
Authorization: ApiKey 1234567890abcdef
Before being able to connect to a user’s wearable account, you will need to connect the user against your tenant. In order to do this, you need to POST details of the user to the following API method:
POST https://platform.healthr.cloud/api/accounts
{
"ID": "cd86b77b-5680-4adb-8cf7-d87febc1beec",
"ExternalID": "sample string 2",
"Name": "sample string 3",
"DOB": "2022-12-28T00:28:14.932825+00:00",
"Gender": "sample string 4",
"Devices": "sample string 5",
"Country": "sample string 6",
"Age": 1,
"Location": "sample string 8",
"Created": "2022-12-28T00:28:14.948461+00:00",
"HasDevices": true
}
In order to initiate the authorisation flow for a device account, POST details of the User and the type of device you wish to connect with. For example, in order to connect to a Fitbit account, you would make the following call:
POST https://platform.healthr.cloud/api/accounts
{
"ExternalID": "87394732947892",
"Device": "Fitbit",
"ConnectionKey": "78343676dghsd67512fgh",
"DirectAccess": false
}
The user will be redirected to the Fitbit Authorisation page where they will be asked to login and authorise their data to be used by the calling app (in this case healthR). Note: Any screens leading up to this point can be customised by the calling app to explain the process, however, once the call to connect to a device is made, the authorisation screens for the device account will differ depending on the device manufacturer and there is no ability to customise those (standard OAuth screens).
By default, once a user has connected their wearable account with healthR, the data will be automatically synchronised and stored in our platform ready to query. If you do not want this to happen and instead would like to query the data directly, then you can set the DataAccessOnly flag to true. This will disable the auto-sync and you will need to use the Direct Data Access API method in order to query data directly from source. Note: this will be slower than having the data stored on the platform and you may be limited to the last 30 days worth of data (or whatever restrictions the wearable device manufacturers have in place with their APIs).
Once a connection to a device has been made, the healthR service will fetch data in the background and store this in the healthR database. This data can be queried by date, category, user. At least one parameter for the query must be provided.
POST https://platform.healthr.cloud/api/records/query
Further details of the Request and Response data can be found here.
If during the connection process you specified Direct Data Access only (therefore not storing data in healthR for querying purposes), you will need to use the following API call to access data directly from source (manufacturers API). All of the parameters specified in the request below are mandatory and you can only request data on a per user basis (you can’t request data across a number of users as you can using Query method above).
POST https://platform.healthr.cloud/api/records/direct
Further details of the Request and Response data can be found here.
healthR supports the ability for apps / services / devices to push data to the healthR platform to create a longitudinal record for an individual. This allows apps to use the platform as their main data store for all health-related data for an individual. It’s also allows new wearable device vendors to use the platform as their main data store for data generated from their devices.
POST https://platform.healthr.cloud/api/records/create
Further details of the Request and Response data can be found here.
Where there is text-based data that needs to be stored rather than numerical readings, the Title and Data fields can be used to store long text such as consultation notes, summaries or general information. Structured data / documents (JSON / XML) can also be stored in the Data field.
You can add multiple records in one API call using the CreateMultiple endpoint. This helps reduce unecessary network traffic creating a single record at a time.
Client apps can allow a user to de-authorise a device and prevent any further data from being retrieved by calling the following API method:
POST https://platform.healthr.cloud/api/account/deauthorise
{
"ExternalID": "87394732947892",
"Device": "Fitbit"
}
healthR now supports Optical Character Recognition (OCR) and Medical Concept detection via our new Vision API. You can now upload images containing text (prescriptions, medical notes, readings from non-connected devices) and the API will return the text from the image along with all associated medical concepts (classification of text).
In order to get the text and medical concepts detected from an image, simply POST a base64 string of an image as below.
POST https://platform.healthr.cloud/api/vision/detect
{
"ImageString": "/9j/4AAQSkZJRgABAQEBLAEsAAD/4Q7RRXhpZgAATU0AKgAAAAgACAEOAAIAAAD8AAAAfgESAAMAAA..."
}
The output from the query will be a list of the Classified Terms along with their associated SNOMED codes. An example can be seen below:
[
{
"Text": "Ibuprofen",
"MedicalConcepts": [
{
"Text": "Medication",
"Code": "1029288102"
}
]
},
{
"Text": "sample string 1",
"MedicalConcepts": [
{
"Text": "sample string 1",
"Code": "sample string 2"
},
{
"Text": "sample string 1",
"Code": "sample string 2"
}
]
}
]