Intro to FHIR
#What is FHIR?
FHIR, or Fast Healthcare Interoperability Resources, is a standard for exchanging healthcare information electronically.
FHIR defines a set of resources that represent different aspects of healthcare information, such as patients, medications, and clinical observations.
Each resource is defined using a set of standardized data elements, or "fields", that describe the information being represented.
Flexpa API offers access to healthcare data using the FHIR standard in JSON format.
#How to pull patient data
This guide will walk through the steps required to pull all data on a patient that a payer has made available.
We recommend starting here to gain a sense of the availability and formatting of patient FHIR data.
#Prerequisites
Ensure you have completed the quickstart and obtained a patient access token.
All interactions with the FHIR API require authentication.
#1. Read Patient resource
To begin, make a GET request to the Patient resource.
This request will pull basic data on a patient and will typically include a name, phone, email, member ID, address etc.
#Example request to Patient
ACCESS_TOKEN=flexpa-link-access-token
curl "https://api.flexpa.com/fhir/Patient/$PATIENT_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN"
View a sample response.
#2. Patient $everything and _include
You may find that the example request in Step 1 returned the referenced resources that you need.
However, you may instead find that the data returned in the previous step is limited to the patient's personal demographic information and does not include any claims or clinical data.
This happens because many servers require requests to be more explicit when asking for data.
FHIR defines two useful options that can enhance our requests by explicitly asking servers for more data:
Patient $everything operation_include search parameter
#Patient $everything operation
Unique to the Patient resource, the Patient $everything operation requests all resources that link to the Patient resource at once.
This operation frees the client from needing to determine what it could or should ask for.
Note that executing this operation without any search parameters may result in a very large Bundle.
In the following example, we use Patient $everything to ask the server for all resources referencing a Patient:
ACCESS_TOKEN=flexpa-link-access-token
curl "https://api.flexpa.com/fhir/Patient/$PATIENT_ID/$everything" \
-H "Authorization: Bearer $ACCESS_TOKEN"
Flexpa resolves your FHIR queries to the Endpoint you obtain an authorization from during the Flexpa Link flow.
While some Endpoints may support the Patient $everything operation, not all do.
We recommend referring to the Endpoint's CapabilityStatement to check whether Patient $everything is supported by the Endpoint.
#_include search parameter
The _include search parameter allows clients to explicitly request referenced resources from an Endpoint.
If the Patient $everything operation is not supported by a payer or doesn't return enough relevant data for your use case, we recommend using the _include search parameter.
In this case, use the * wildcard value to ask the server for all referenced resources:
ACCESS_TOKEN=flexpa-link-access-token
curl "https://api.flexpa.com/fhir/Patient/$PATIENT_ID?_include=*" \
-H "Authorization: Bearer $ACCESS_TOKEN"
Keep in mind that not all Endpoints support a * value.
Instead, Endpoints may allow queries on specific referenced resources based on the CapabilityStatement's searchInclude.
The following request explicitly asks for generalPractitioner and managingOrganization.
The syntax is typically Resource:property, for example:
ACCESS_TOKEN=flexpa-link-access-token
curl "https://api.flexpa.com/fhir/Patient/$PATIENT_ID?_include=Patient:generalPractitioner&_include=Patient:managingOrganization" \
-H "Authorization: Bearer $ACCESS_TOKEN"
#3. Follow reference links
Many resources returned by the API will contain references to other resources.
A reference is a string that points to the location where the referenced resource can be retrieved.
For instance, a Patient may contain a reference to an Organization or a Practitioner.
You can resolve these references by making additional requests.
#Example response with referenced resources
{
"resourceType" : "Patient",
"generalPractitioner" : {
"reference" : "Practitioner/12345"
},
"managingOrganization" : {
"reference" : "Organization/12345"
}
}
For more detail, see the official Reference resource profile in the FHIR standard.
#Relative references
The example above includes relative references.
Relative reference URLs conform to the structure [resourceType]/[id].
When referenced relatively, resources are assumed to be found on the same FHIR server as the referring resource.
In other words, the reference is said to be relative to the base URL.
In the case of a relative reference, you can follow the reference by appending the value of the reference property onto the base URL in a subsequent API request:
ACCESS_TOKEN=flexpa-link-access-token
curl "https://api.flexpa.com/fhir/Practitioner/12345" \
-H "Authorization: Bearer $ACCESS_TOKEN"
ACCESS_TOKEN=flexpa-link-access-token
curl "https://api.flexpa.com/fhir/Organization/12345" \
-H "Authorization: Bearer $ACCESS_TOKEN"
#Internal references
If a reference is internal, it begins with #. For example:
{
"resourceType" : "Patient",
"generalPractitioner" : {
"reference" : "#p1"
},
"contained" : [
{
"resourceType" : "Practitioner",
"id" : "p1",
"name" : "Dr. Adam Smith"
}
]
}
In the case of an internal reference, the target resource is contained (embedded directly) in the same resource.
You can access it in the contained field by filtering for the matching id.
#Absolute references
Resources may also contain absolute reference URLs.
An absolute reference is not relative to the base URL since it implies that the referenced resource is located on another server.
You can usually expect references to be either relative or internal.
However in the rare case that you come across an absolute reference, following it would mean making an additional request to a server that is unknown to Flexpa.
When making requests to external servers, please exercise caution.
For example:
{
"resourceType" : "Patient",
"generalPractitioner" : {
"reference" : "https://other.fhir.server.com/Practitioner/12345"
},
"managingOrganization" : {
"reference" : "https://other.fhir.server.com/Organization/12345"
}
}
In this case, you may be able request more data using the URL in its entirety.
Note that this request will be to a FHIR API separate from Flexpa's.
curl "https://other.fhir.server.com/Practitioner/12345"
curl "https://other.fhir.server.com/Organization/12345"
Following URLs to external servers is always risky.
Please consider the security implications of doing so and take the appropriate steps to mitigate unintended access to malicious servers, such as an allowlist of trusted servers for example.
Alternatively, the most conservative approach is to avoid following absolute references altogether.
#4. Search other resources
Steps 1-3 each targeted the Patient resource.
To pull as much data as possible on a patient, we can repeat steps 1-3 for other resources.
For example, payers typically support the ExplanationOfBenefit resource.
#Example request to ExplanationOfBenefit
ACCESS_TOKEN=flexpa-link-access-token
curl "https://api.flexpa.com/fhir/ExplanationOfBenefit?patient=$PATIENT_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN"
Often Endpoints will require the patient ID to be explicitly queried using the patient search parameter.
We recommend always including patient=$PATIENT_ID in search queries.
Based on the payer's CapabilityStatement you may also be able to use search parameters such as _include to request referenced resources.
ACCESS_TOKEN=flexpa-link-access-token
curl "https://api.flexpa.com/fhir/ExplanationOfBenefit?patient=$PATIENT_ID&_include=ExplanationOfBenefit:care-team" \
-H "Authorization: Bearer $ACCESS_TOKEN"
#Iterate through all supported resources
To cover all the resources that a payer makes available, you can iterate through a list of supported FHIR resources.
Lists of supported resources can be found in the Endpoints reference.
For convenience, the exchange API also returns a list of FHIR resources that are supported by the payer in the endpoint.resources array.
We recommend using this list to construct your FHIR requests programmatically.
Doing so ensures that, at the time of patient authorization, your application uses an up-to-date list of supported resources.
ACCESS_TOKEN=flexpa-link-access-token
curl "https://api.flexpa.com/fhir/<fhir-resource>?patient=$PATIENT_ID&<available-include-params>" \
-H "Authorization: Bearer $ACCESS_TOKEN"
Keep in mind that not all resources can be searched.
Attempting a search operation on a read-only resource will result in an error.
Check for the presence of the search operation per resource in the Endpoint's CapabilityStatement.
#Read vs. Search
In the guide above, we demonstrated examples of both Read and Search operations.
#Read
Reading a resource in FHIR refers to retrieving the details of a single resource instance.
For example, you might want to read the details of a patient, medication, or a specific clinical observation.
Reading requires knowledge of the resource id ahead of time.
See more about reading resources.
#Search
Searching in FHIR allows you to find and retrieve multiple resources based on specific search criteria or filters.
This operation is handy when you want to locate resources that match certain conditions or attributes, such as finding all patients with a specific condition, retrieving all medications prescribed by a particular practitioner, or searching for observations within a specific date range.
Searching does NOT require knowledge of any resource ids ahead of time.
However, the resource must be made explicitly searchable by the payer.
Look for the presence of the search operation in the Endpoint's CapabilityStatement.
See more about searching resources.
#Resources List
The following table lists all the FHIR resources supported by Flexpa.