Cooking with FHIR

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.

Important Notes:

  • Target Audience: Individuals implementing the Particle Health API (including customers, sales engineers, new hires, etc.)
  • While we support read access for all resources, permissions may prevent you from creating certain resources.

Particle-Supported FHIR Resources

Particle Health supports querying the following FHIR resources:

  • AllergyIntolerance
  • Basic
  • CarePlan
  • Composition
  • Condition
  • Coverage
  • Device
  • DiagnosticReport
  • DocumentReference
  • Encounter
  • FamilyMemberHistory
  • Immunization
  • Location
  • Medication
  • MedicationRequest
  • MedicationStatement
  • Observation
  • Organization
  • Patient
  • Person
  • Practitioner
  • PractitionerRole
  • Procedure
  • RelatedPerson

As new resource types are supported, they will be updated here.

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.

  1. POST Person to submit a set of demographics and obtain a PersonID.
  2. POST Person/{person_ID}/$query to submit a query against the CommonWell and CareQuality networks for a given PersonID.
  3. GET Person/{person_ID}/$query to check the status of the query for completion or failure.
  4. GET {resource_type} to pull all resources meeting query criteria, which can be further refined using the search parameters in the following section.

More detailed information on our API endpoints and implementation details can be found here.

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. Furthermore, a list of universally applicable parameters and general instructions for using parameters can be found here.

Only compatible with certain resources:

Search ParameterDescriptionExample
DateFilters returned resources by desired dates, exact syntax varies by resource type?person={person_id}&date=lt2021-10-19
codeFilters for resources having desired FHIR-supported medical coding terms?person={person_id}&code=4548-4

Compatible with all resource types:

Search ParameterDescriptionExample
_countLimits number of resources returned on a single response page?person={person_id}&_count=50
_sortSorts returned resources by date, status, or category?person={person_id}&_sort=date
_content and _textFilters for resources containing desired strings in their whole body and narrative fields, respectively?person={person_id}&_text=nebulization
_include and _revincludeProvides full body of resources that are referenced by or refer to given resource, respectively?person={person_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/?person={person_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:

  1. Request Composition resources for a given person and save all URLs returned
    curl -X GET 'https://api.particlehealth.com/R4/Composition?person={person_id}' -H 'Authorization: {jwt}'
  2. 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?person={person_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?person={person_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.


Did this page help you?