HealthEx FHIR Server
HealthEx provides a FHIR-compliant set of APIs that can be used to access a patient's data with their consent. Patient data is provided entirely in standards-compliant FHIR R4 format, and you can easily fetch a patient's entire health care record with a single API call.
To do this, you'll need the following:
- A patient who has consented to share their data with your organization (through one or more HealthEx projects)
- The HealthEx patient ID of that patient
- An idea of which FHIR resources you're interested in, or if you're just interested in everything
Example Values
For this example, we'll use the patient ID 19cff418-7d80. We'll also start by assuming you want to fetch all the patient's FHIR data.
Using the $everything API
HealthEx exposes a FHIR $everything API which you can use to fetch a patient's entire medical record. To make this API call:
GET https://api.healthex.io/FHIR/R4/Person/19cff418-7d80/$everything
Accept: application/json
Authorization: Bearer <your JWT token>
This API requires you to pass a JWT token to authenticate. See the Authentication guide for more info. Remember that your token will only give you permission to access data from patients who have consented to share their data with your organization.
The response body will be a FHIR bundle. You can read more about FHIR bundles in the FHIR R4 Bundle Documentation. The short summary is that a FHIR bundle is a wrapper around a list of many FHIR resources, with a little extra information thrown in.
Here is an example response:
{
"resourceType": "Bundle",
"type": "searchset",
"total": 2,
"link": [
{
"relation": "self",
"url": "https://api.healthex.io/FHIR/R4/Person/19cff418-7d80/$everything?_count=30&_offset=0"
},
],
"entry": [
{
"fullUrl": "https://api.healthex.io/FHIR/R4/Person/19cff418-7d80",
"search": {
"mode": "match"
},
"resource": {
"resourceType": "Person",
"id": "19cff418-7d80",
"name": [
{
"family": "Lin",
"given": [
"Derrick"
],
"use": "usual"
}
],
"birthDate": "1973-06-03T00:00:00.000Z",
"link": [
{
"target": {
"reference": "Patient/eq081-VQEgP8drUUqCWzHfw3",
"assurance": "level4"
}
}
]
}
},
{
"fullUrl": "https://api.healthex.io/FHIR/R4/Observation/00210fd0-9625-486b-a4fd-43f832798c75",
"search": {
"mode": "match"
},
"resource": {
"resourceType": "Observation",
"id": "fqzY4YiPBHqsNx9iRD99etRNX.LClJFf33HYpZC1E1R04",
"status": "final",
"category": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/observation-category",
"code": "vital-signs",
"display": "Vital Signs"
}
],
"text": "Vital Signs"
}
],
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "55284-4",
"display": "Blood pressure systolic and diastolic"
},
],
"text": "Blood Pressure"
},
"subject": {
"reference": "Patient/eq081-VQEgP8drUUqCWzHfw3",
"display": "Lin, Derrick"
},
"encounter": {
"reference": "Encounter/e6kBx6PwnxIv.5kCifScsWg3",
"identifier": {
"use": "usual",
"system": "urn:oid:1.2.840.114350.1.13.0.1.7.3.698084.8",
"value": "27556"
},
"display": "Office Visit"
},
"effectiveDateTime": "2020-11-26T15:28:31Z",
"issued": "2020-11-26T16:00:45Z",
"performer": [
{
"reference": "Practitioner/exfo6E4EXjWsnhA1OGVElgw3",
"display": "User E"
}
],
"component": [
{
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "8480-6",
"display": "Systolic blood pressure"
}
],
"text": "Systolic blood pressure"
},
"valueQuantity": {
"value": 137,
"unit": "mm[Hg]",
"system": "http://unitsofmeasure.org",
"code": "mm[Hg]"
}
},
{
"code": {
"coding": [
{
"system": "http://loinc.org",
"code": "8462-4",
"display": "Diastolic blood pressure"
}
],
"text": "Diastolic blood pressure"
},
"valueQuantity": {
"value": 90,
"unit": "mm[Hg]",
"system": "http://unitsofmeasure.org",
"code": "mm[Hg]"
}
}
]
}
}
]
}
As you can see, there will be multiple child objects inside the entry[].resource properties. These are the FHIR resources you're looking for!
Streaming Responses and Paging
All responses are streamed to the client as long as the client supports it. This means that we start sending data to your client as soon as we find even one FHIR record to return to you. For smaller numbers of records, you may not even notice or care about this, but for larger use cases this can become valuable.
If you do not wish to receive a single large response, you can also use paging by passing the _count query parameter. This will limit the number of bundle entries to the count that you supply. So for example:
GET https://api.healthex.io/FHIR/R4/Person/19cff418-7d80/$everything?_count=30
will only return the first 30 records. You will also notice additional info in the link section at the top of the returned bundle:
...
"link": [
{
"relation": "self",
"url": "https://api.healthex.io/FHIR/R4/Person/19cff418-7d80/$everything?_count=30&_offset=0"
},
{
"relation": "first",
"url": "https://api.healthex.io/FHIR/R4/Person/19cff418-7d80/$everything?_count=30&_offset=0"
},
{
"relation": "next",
"url": "https://api.healthex.io/FHIR/R4/Person/19cff418-7d80/$everything?_count=30&_offset=30"
},
{
"relation": "last",
"url": "https://api.healthex.io/FHIR/R4/Person/19cff418-7d80/$everything?_count=30&_offset=990"
}
],
...
The most important of these is the next value. You can follow this link to get the next 30 records. You can continue following the next link until either the next link is no longer present, or until no remaining results are returned.
For full details, you can consult the FHIR Specification on Paging.
More Advanced Use Cases
You can use the HealthEx FHIR APIs to accomplish several other advanced use cases.
Only Getting Certain FHIR Resources
You may only be interested in certain portions of the patient's health care record. For example, perhaps you only need a list of the patient's allergies and immunizations. This can be accomplished by using the _type parameter:
GET https://api.healthex.io/FHIR/R4/Person/19cff418-7d80/$everything?_type=AllergyIntolerance,Immunization
The resulting bundle will be much smaller and contain only FHIR resources of type AllergyIntolerance and Immunization.
Only Getting Updated Records
If you make ongoing calls to update a patient's health care record from HealthEx, you may only be interested in getting records that have been newly added or changed. This kind of "incremental data pull" can be very powerful for minimizing the amount of work your application has to do.
To only fetch records that have been updated since a certain date, you can use the _since parameter:
GET https://api.healthex.io/FHIR/R4/Person/19cff418-7d80/$everything?_since=2026-02-27T12:00:00Z
We recommend that you record the timestamp at which you started this API call, so that you can then use that timestamp as the _since parameter the next time you need an update.
Error Responses
HTTP 400 Bad Request - The request contains invalid parameters. For example, you may have passed a malformed date.
HTTP 401 Unauthorized - The authorization token is missing, invalid, or expired
HTTP 403 Forbidden - The token does not have permission to access this patient's data. The patient may not have consented to share their data with your organization (or may have withdrawn their consent)
Supported FHIR Resources
HealthEx supports fetching data for any type of FHIR resource that is included in the FHIR R4 spec. You can get a full list here.
However, HealthEx can only provide data that was included in the patient's original health care record, and some resources are more common than others. If you're just getting started or just testing, we recommend you look for resources that are mandated by the USCDIv3 standard. A list of these can be found as part of the US Core FHIR Profile.