Dot Health API
Welcome to the Dot Health API. Here, we'll detail the endpoints you can use to access health data stored on our platform. Health data on our platform is stored in a format based heavily off of FHIR. See a detailed description of our health data models here.
Terminology
Health Resource
- Any single health record (e.g. allergy, clinical note, diagnostic report). A list of our health resources can be found here.
LOINC
- Logical Observation Identifiers Names and Codes; a standardization of terminology for laboratory and clinical observations. More info can be found here.
SNOMED-CT
- Systematized Nomenclature of Medicine; a systematically organized computer processable collection of medical terms providing codes, terms, synonyms and definitions used in clinical documentation and reporting. More info can be found here.
Visualization
- A trend (ex. over time) generated based off of a collection of health resources.
Authentication
Access to each of the endpoints requires a valid bearer token. In this documentation, we provide a demo bearer token dotdotdot
that can be used in any of the endpoints described, that you can use for exploratory purposes. All data displayed is sample data.
The header for your requests should contain:
Authorization: Bearer dotdotdot
Health Resources
Get Multiple Health Resources
const axios = require('axios');
axios
.get(
'https://webapi.dothealth.ca/api/resources?include=related&exclude=nested',
{ headers: { 'Authorization': 'Bearer dotdotdot' } }
).then((result) => console.log(result));
import requests
result = requests.get(
'https://webapi.dothealth.ca/api/resources?include=related&exclude=nested',
headers={'Authorization': 'Bearer dotdotdot'}
)
curl --request GET \
--url 'https://webapi.dothealth.ca/api/resources?include=related&exclude=nested' \
--header 'authorization: Bearer dotdotdot'
Example response:
{
"resources": [
{
"id": 244733,
"createdAt": "2019-08-18T17:41:23.000Z",
"updatedAt": "2019-08-18T17:41:23.000Z",
"dosage": "100mg",
"instructions": "One per day",
"name": {
"text": "Lipitor"
},
"recordedAt": "2019-08-18T13:46:45.325Z",
"values": {
"dosage": "100mg",
"instructions": "One per day",
"name": {
"text": "Lipitor"
},
"recordedAt": "2019-08-18T13:46:45.325Z"
},
"resource_type": "medicationDispense",
"generated": {
"title": "Lipitor",
"text": "<ul><li><strong>Name: </strong>Lipitor</li><li><strong>Recorded at: </strong>2019-08-18</li><li><strong>Dosage: </strong>100mg</li><li><strong>Instructions: </strong>One per day</li></ul>"
},
"source": "patient",
"reviewed": false,
"draft": false,
"institution_address_id": "-1",
"UserId": 510,
"phi_checked": false,
"InformationRequestId": null
},
{
"id": 231560,
"createdAt": "2019-07-23T13:45:16.000Z",
"updatedAt": "2019-10-04T15:23:21.000Z",
"name": {
"text": "Hematocrit",
"coding": [
{
"system": "LOINC",
"code": "20570-8"
}
]
},
"recordedAt": "2019-05-01T04:00:00Z",
"result": "0.47",
"unit": {
"text": "L/L"
},
"referenceRange": [
{
"low": 0.38,
"high": 0.49
}
],
"values": {
"name": {
"text": "Hematocrit",
"coding": [
{
"system": "LOINC",
"code": "20570-8"
}
]
},
"recordedAt": "2019-05-01T04:00:00Z",
"result": "0.47",
"unit": {
"text": "L/L"
},
"referenceRange": [
{
"low": 0.38,
"high": 0.49
}
]
},
"resource_type": "observation",
"generated": {
"title": "Hematocrit",
"date": "2019-05-01T04:00:00Z",
"text": "<ul><li><strong>Name: </strong>Hematocrit<ul><li><strong>Coding: </strong><ul><li><ul><li><strong>System: </strong>LOINC</li><li><strong>Code: </strong>20570-8</li></ul></li></ul></li></ul></li><li><strong>Recorded at: </strong>2019-05-01</li><li><strong>Result: </strong>0.47</li><li><strong>Unit: </strong>L/L</li><li><strong>Reference range: </strong><ul><li><ul><li><strong>Low: </strong>0.38</li><li><strong>High: </strong>0.49</li></ul></li></ul></li></ul>"
},
"source": "admin",
"reviewed": false,
"draft": false,
"institution_address_id": "1724",
"UserId": 510,
"phi_checked": true,
"InformationRequestId": null
}
]
}
Retrieves all health resources for the logged in user as a list. Health resources can exist as sub-resources of other health resources (ex. a DiagnosticReport
may contain several Observation
sub-resources). By default the response will include a flat list of all health resources associated with a user, without discerning hierarchy that may exist between them.
Most commonly, this endpoint is used with the nested
exclude parameter and related
include parameter.
- By adding the nested
exclude parameter, the list will filter to only resources that are not sub-resources (or, "parent" level resources).
- By adding the related
include parameter, sub-resources can be retrieved and included in hierarchy underneath their "parent" resources
Patient-reported symptoms are considered Observation
resources that are included in the response. Often, there are many reported symptoms that may clutter other data in the response, so you can optionally filter them out using the symptoms
exclude parameter.
Lastly, files associated with a health resource can be retrieved by using the files
include parameter.
Dot Health's health resources follow the specifications laid out in FHIR. You can find a list of the subset of FHIR models that we use here
HTTP Request
GET https://webapi.dothealth.ca/api/resources
Query Parameters
Include parameters
Option | Description |
---|---|
related |
Include any child resources nested in the health resource |
files |
Include files associated with the health resource |
Exclude parameters
Option | Description |
---|---|
nested |
Exclude child resources in the list returned |
symptoms |
Exclude symptoms from the list returned |
Get Single Health Resource
const axios = require('axios');
axios
.get(
'https://webapi.dothealth.ca/api/resources/202286',
{ headers: { 'Authorization': 'Bearer dotdotdot' } }
).then((result) => console.log(result));
import requests
result = requests.get(
'https://webapi.dothealth.ca/api/resources/202286',
headers={'Authorization': 'Bearer dotdotdot'}
)
curl --request GET \
--url 'https://webapi.dothealth.ca/api/resources/202286' \
--header 'authorization: Bearer dotdotdot'
The command above returns the follow JSON structure:
{
"resource": {
"id": 57,
"createdAt": "2019-02-13T14:28:06.000Z",
"updatedAt": "2019-10-02T16:03:39.000Z",
"recordedAt": "2019-02-13T14:28:07Z",
"name": {
"text": "Smallpox"
},
"administeredAt": "2019-01-30T05:00:00Z",
"description": "50-59 years of age - may receive 1 dose; 60 years of age and older: 1 dose. If dose given before 60 years of age, additional dose at 60 years of age or older is not currently recommended",
"targetDisease": {
"text": "Shingles"
},
"seriesDose": 1,
"seriesDoses": 3,
"route": "Intramuscular",
"site": "Left arm",
"patientName": "Jane Doe",
"resource_type": "immunization",
"generated": {
"title": "Smallpox",
"date": "2019-02-13T14:28:07Z",
"text": "<ul><li><strong>Patient name: </strong>Jane Doe</li><li><strong>Name: </strong>Smallpox</li><li><strong>Recorded at: </strong>2019-02-13</li><li><strong>Target disease: </strong>Shingles</li><li><strong>Series dose: </strong>1</li><li><strong>Series doses: </strong>3</li><li><strong>Route: </strong>Intramuscular</li><li><strong>Site: </strong>Left arm</li><li><strong>Administered at: </strong>2019-01-30</li><li><strong>Description: </strong>50-59 years of age - may receive 1 dose; 60 years of age and older: 1 dose. If dose given before 60 years of age, additional dose at 60 years of age or older is not currently recommended</li></ul>"
},
"source": "patient",
"reviewed": true,
"draft": false,
"institution_address_id": "1232",
"UserId": 510,
"phi_checked": true,
"InformationRequestId": null
}
}
Retrieves a single health resource for the logged in user.
Similarly to the previous endpoint, you can add the related
include parameter to retrieve sub-resources in hierarchy underneath their "parent" resources. You can also add a parent
include parameter to retrieve any parent that may be associated with the resource you are fetching.
Dot Health's health resources follow the specifications laid out in FHIR. You can find a list of the subset of FHIR models that we use here.
HTTP Request
GET https://webapi.dothealth.ca/api/resources/:resource_id
URL Parameters
Parameter | Description |
---|---|
resource_id |
The id of the health resource to retrieve |
Query Parameters
Include parameters
Option | Description |
---|---|
related |
Include any child resources nested in the health resource |
files |
Include files associated with the health resource |
parent |
Include any parent resource associated with the health resource |
Visualizations
Generate Visualization
const axios = require('axios');
axios
.post(
'https://webapi.dothealth.ca/api/resource_visualizations/generate',
{ standardTestNameId: 205 },
{ headers: {
'Authorization': 'Bearer dotdotdot',
'Content-Type': 'application/json'
}
}
).then((result) => console.log(result));
import requests
result = requests.post(
'https://webapi.dothealth.ca/api/resource_visualizations/generate',
json={
'standardTestNameId': 205
},
headers = {
'Authorization': 'Bearer dotdotdot',
'Content-Type': 'application/json'
}
)
curl --request POST \
--url 'https://webapi.dothealth.ca/api/resource_visualizations/generate' \
--header 'Authorization: Bearer dotdotdot' \
--header 'Content-Type: application/json' \
--data-raw '{"standardTestNameId": 205}'
Example response:
{
"visualization": {
"standardTestName": "Hemoglobin",
"resources": [
{
"id": 231558,
"resource_type": "observation",
"name": {
"text": "Hemoglobin",
"coding": [
{
"system": "LOINC",
"code": "718-7"
}
]
},
"recordedAt": "2019-05-01T04:00:00Z",
"result": "150",
"unit": {
"text": "g/L"
},
"referenceRange": [
{
"low": 135,
"high": 170
}
],
"patientName": "Jane Doe"
},
{
"id": 247033,
"resource_type": "observation",
"name": {
"text": "Hemoglobin",
"coding": [
{
"system": "LOINC",
"code": "718-7"
}
]
},
"result": "129",
"referenceRange": [
{
"low": 120,
"high": 160
}
],
"unit": {
"text": "g/L"
},
"recordedAt": "2016-12-01T07:00:00Z"
}
],
"xRange": {
"max": "2019-07-28T08:47:59+00:00",
"min": "2016-09-04T02:12:00+00:00"
},
"yRange": {
"max": "188.5",
"min": "86.5"
}
}
}
Retrieves the data for a trend visualization of a particular Observation
over time.
To uniquely identify the type of each Observation
, Dot Health employs multiple medical terminology standardization systems. Our clinical observations follow the LOINC system and our user-logged symptom Observations follow the symptoms listed in the SNOMED-CT system. We encapsulate the codes from both of theses systems in our StandardTestName
object. A visualization can be retrieved by providing the StandardTestName
of the Observation
to be visualized as a value in the JSON body. You can find more information and an endpoint for retrieving the set of Standard Test Names below.
HTTP Request
POST https://webapi.dothealth.ca/api/resource_visualizations/generate
JSON Body Parameters
Parameter | Description |
---|---|
standardTestNameId |
The Standard Test Name Id of the Observation to generate a visualization for |
Get All Standard Test Names
const axios = require('axios');
axios
.get(
'https://webapi.dothealth.ca/api/standard_test_names?include=codes',
{ headers: { 'Authorization': 'Bearer dotdotdot' } }
).then((result) => console.log(result));
import requests
result = requests.get(
'https://webapi.dothealth.ca/api/standard_test_names?include=codes',
headers={'Authorization': 'Bearer dotdotdot'}
)
curl --request GET \
--url 'https://webapi.dothealth.ca/api/standard_test_names?include=codes' \
--header 'Authorization: Bearer dotdotdot'
Example response:
{
"standardTestNames": [
{
"id": 204,
"name": "Hematocrit",
"loinc_code": {
"id": 99999,
"number": "4544-3",
"short_name": "Hct VFr Bld Auto",
"long_name": "Hematocrit [Volume Fraction] of Blood by Automated count"
}
},
{
"id": 205,
"name": "Hemoglobin",
"loinc_code": {
"id": 128900,
"number": "718-7",
"short_name": "Hgb Bld-mCnc",
"long_name": "Hemoglobin [Mass/volume] in Blood"
}
},
{
"id": 294,
"name": "Hemoglobin - Urine (Presence)",
"loinc_code": {
"id": 129611,
"number": "725-2",
"short_name": "Hgb Ur Ql",
"long_name": "Hemoglobin [Presence] in Urine"
}
},
{
"id": 1098,
"name": "Dry skin",
"snomed_ct_code": {
"id": 291,
"created_at": "2020-01-21T15:50:39.000Z",
"updated_at": "2020-01-21T15:50:39.000Z",
"concept_id": "16386004",
"term": "Dry skin (finding)"
},
"symptom": {
"id": 51,
"created_at": "2020-02-07T21:24:24.000Z",
"updated_at": "2020-02-07T21:24:24.000Z",
"category": "Skin & Hair"
}
},
{
"id": 1068,
"name": "Ear pain",
"snomed_ct_code": {
"id": 158,
"created_at": "2020-01-21T15:50:39.000Z",
"updated_at": "2020-01-21T15:50:39.000Z",
"concept_id": "16001004",
"term": "Otalgia (finding)"
},
"symptom": {
"id": 15,
"created_at": "2020-02-07T21:24:24.000Z",
"updated_at": "2020-02-07T21:24:24.000Z",
"category": "Eyes, Ears, Nose & Throat"
}
}
]
}
Retrieves all StandardTestName
s in use by Dot Health. A StandardTestName
is a Dot Health-specific standardized name for Observation
type resources. These standardized names are used for display purposes and quick reference for an observation. StandardTestName
s include references to codes from the LOINC or SNOMED-CT coding systems. To view these in the response, add the codes
include parameter.
HTTP Request
GET https://webapi.dothealth.ca/api/standard_test_names
Query Parameters
Include parameters
Option | Description |
---|---|
codes |
Includes LOINC or SNOMED-CT codes associated with the StandardTestName s |
ranges |
Includes acceptable reference ranges associated with the StandardTestName s |
names |
Include alternate names associated with the StandardTestName s |