How to Filter Claims Data

DPC uses _type and _since parameters to filter your results by content, time, and range.

Filter claims data by FHIR Resource with _type

The _type query parameter allows you to specify which FHIR Resources you wish to export. If you do not specify a _type parameter in your request, all three resources will be exported: Explanation of Benefit, Patient, and Coverage. You can specify these Resources individually or as a group using a comma delimited list and the syntax ?_type=ExplanationOfBenefit,Patient,Coverage.

The following request will export the Patient and Coverage Resources, but NOT the Explanation of Benefit Resource.

Example request: Patient and Coverage

GET /api/v1/Group/{GROUP_ID}/$export?_type=Patient,Coverage

By contrast, the following request will export the Explanation of Benefit Resource but NOT the Patient or Coverage Resources.

Example request: Explanation of Benefit

GET /api/v1/Group/{GROUP_ID}/$export?_type=ExplanationOfBenefit

Request filtered data with _since

You can filter data using the _since parameter with either the /Patient or /Group endpoints. You may want to set _since queries as a repeating call or as a way to check for patient updates to avoid downloading duplicate data.

On subsequent calls you can begin retrieving incremental claims data for your patients using _since. We suggest using the transactionTime from your last bulk data request as the _since date.

Two ways to use _since:

1. Request the most recent data for all of your patients with Medicare: Use _since within the /Group endpoint.
2. Request data synchronously for an individual patient: Use _since within the /Patient endpoint.

Steps to request filtered data

1. Obtain a bearer token.
2. Start a job to acquire data (you will input the _since parameter here. Omit _since to download all data).
3. Check the job status.
4. Download the data.

Datetimes submitted using _since must follow the FHIR Instant format (e.g. YYYY-MM-DDThh:mm:ss.sss+zz:zz).

• Sample Date: February 20, 2020 12:00 PM EST
• Formatted Sample: 2020-02-20T12:00:00.000-05:00

The value of the _since parameter must be URL encoded

When using the Postman Collection, you’ll need to manually encode the _since parameter when it contains a + since Postman does not automatically encode this character.

You can do this either by replacing the + with %2B (e.g., 2020-01-23T04:00:00.000%2B07:00 instead of 2020-01-23T04:00:00.000+07:00), or you can select the value and choose “EncodeURIComponent” from the context menu to have Postman encode the entire parameter automatically.

The /Group/{GROUP_ID}/$export endpoint requires a bearer token as well as Accept and Prefer headers.

The Prefer header is NOT required for /Patient/{PATIENT_ID}/$everything, but it DOES require an X-Provenance header, whereas the /Group/{GROUP_ID}/$export endpoint does not. The format is defined by the FHIR Bulk Data Export spec. Consult the FHIR Datatypes page for more information.

Due to limitations in the Beneficiary FHIR Data (BFD) Server, data from before 02-12-2020 is marked with the arbitrary lastUpdated date of 01-01-2020. Data loads from 02-12-2020 onwards have been marked with accurate dates.

Request data using _since with the /Group endpoint

This operation will start a job for filtered data for existing Medicare patients at 8PM ET on May 13th, 2021 and will include all seven years of historical data for all patients in the Group who have a lastUpdated date that falls after the _since date. In the example, we request the Patient Resource Type. The steps and format would work similarly for other resource types.

If the request was successful, a 202 Accepted response code will be returned and the response will include a Content-Location header.

Example request

GET /api/v1/Group/{GROUP_ID}/$export?_type=Patient&_since=2021-05-13T08:00:00.000-05:00

Request headers

Authorization: Bearer $BEARER_TOKEN
Accept: application/fhir+json
Prefer: respond-async

Example cURL command

curl 'https://sandbox.dpc.cms.gov/api/v1/Group/{GROUP_ID}/$export?_since=2021-05-13T08:00:00.000-05:00' \
     -H 'Accept: application/fhir+json' \
     -H 'Prefer: respond-async' \
     -H "Authorization: Bearer $BEARER_TOKEN"

Example response

202 Accepted