NAV Navbar
cURL python javascript

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 StandardTestNames 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. StandardTestNames 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 StandardTestNames
ranges Includes acceptable reference ranges associated with the StandardTestNames
names Include alternate names associated with the StandardTestNames