FHIR API Implementation
This is a basic implementation guide for using Particle's API to request FHIR resources. We will cover supported resources and search parameters that will allow you to pull specific subsets of data in fully FHIR-formatted records.
Particle's FHIR API Flow
To use Particle's FHIR API, follow these steps in order. Your query can be further configured in Step 4 using search parameters that bound results by specific fields.
POST Patient
to submit a set of demographics and obtain a PatientID.POST Patient/{patient_ID}/$query
to submit a query against the CommonWell and CareQuality networks for a given PatientID.GET Patient/{patient_ID}/$query
to check the status of the query for completion or failure.GET {resource_type}
to pull all resources meeting query criteria, which can be further refined using the search parameters in the following section.
Polling for Query Status
Webhook Notification for Query Status
More detailed information about working with FHIR data can be found on our Resource Search Methodologies page.
Particle-Supported FHIR Search Parameters
Particle Health supports refining queries based on search parameters. We've presented some examples below, but comprehensive mappings between resources and supported search parameters can be found by clicking on a resource of interest on this page and scrolling to the bottom to see supported search parameters. A list of universally applicable parameters and general instructions for using parameters can be found here.
Only compatible with certain resources:
Search Parameter | Description | Example |
---|---|---|
Date | Filters returned resources by desired dates, exact syntax varies by resource type | ?patient={patient_id}&date=lt2021-10-19 |
code | Filters for resources having desired FHIR-supported medical coding terms | ?patient={patient_id}&code=4548-4 |
Compatible with all resource types:
Search Parameter | Description | Example |
---|---|---|
_count | Limits number of resources returned on a single response page. If, for example, a person has 500 observation resources available, and a client only wants to return 50 observations per page, _count=50 can be added to the search request to apply this to the response. | ?patient={patient_id}&_count=50 |
_sort | Sorts returned resources by date , status , or category | ?patient={patient_id}&_sort=date |
_content and _text | Filters for resources containing desired strings in their whole body and narrative fields, respectively | ?patient={patient_id}}&_text=nebulization |
_include and _revinclude | Provides full body of resources that are referenced by or refer to given resource, respectively | ?patient={patient_id}&_include=MedicationStatement:medication |
Note: If the
_count
is not specified, then the default_count
is 100
https://sandbox.particlehealth.com/R4/MedicationStatement/?patient={patient_id}&_count=50
The last element at the bottom of the response contains a JSON element labeled link
. If one of the relation
elements in link
contains next
this indicates there are more pages as a part of the response. If "relation": "next"
is present, copy the url
and use it as the next endpoint to query. That will provide the next page of entries. Once there is no "relation": "next"
present, there are no more entries or pages to review.
"link": [
{
"relation": "search",
"url": "search_url"
},
{
"relation": "next",
"url": "url_to_return_next_50_resources"
},
{
"relation": "first",
"url": "url_to_first_page"
},
{
"relation": "self",
"url": "url_to_current_page"
}
]
The maximum number of resources that the API will return per-page is 1000. To force the maximum number of resources returned on each query and avoid needing to page through responses (for resource counts under 1000), add \_count=1000
to your search.
If over 1000 resources exist, the link array must be used to paginate through all results.
Usage Examples
Get all resources for a given person:
- Request Composition resources for a given person and save all URLs returned
curl -X GET 'https://api.particlehealth.com/R4/Composition?patient={patient_id}' -H 'Authorization: {jwt}'
- Make a request for each URL saved from the returned Compositions in Step 1
curl -X GET 'https://api.particlehealth.com/R4/{saved_url_resource_type}/{saved_url_id}' -H 'Authorization: {jwt}'
Get all MedicationStatement resources for a given person that have active prescriptions after October 19th, 2021:
curl -X GET 'https://api.particlehealth.com/R4/MedicationStatement?patient={patient_id}&effective=gt2021-10-19' -H 'Authorization: {jwt}'
Get all Observation resources for a given person that contain lab results for hemoglobin A1c values:
curl -X GET 'https://api.particlehealth.com/R4/Observation?patient={patient_id}&code=4548-4' -H 'Authorization: {jwt}'
Compliance
Particle Health follows the full required set of functionality for the latest released version of FHIR, R4. As such, we support all FHIR resources and most operations on top of them.
For the full conformance specification that Particle Health follows get the CapabilityStatement for the FHIR R4 server.
Updated 7 months ago