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	`?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`

_count Search Parameter:

The count search parameter limits the total number of resources that are returned on a single 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.

📘
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.