How to Filter Claims Data

BCDA uses 2 parameters to filter or specify the resources returned:

• _type: limits your request to 1 or more specific resource types
• _since: applies a date boundary to your request

Use parameters in the sandbox or production environment to speed up download times and reduce file size.

The _type parameter

The _type parameter lets you specify which resource types you’d like returned. Otherwise, making a GET request to start a job with the /Group or /Patient endpoint will return all resource types.

You’ll need to use commas when specifying multiple resource types. The examples below are curl requests to /Group using _type.

Example request for 1 resource type

GET /api/v2/Group/all/$export?_type=Patient

Example request for 2 resource types

GET /api/v2/Group/all/$export?_type=ExplanationOfBenefit,Patient

Example request for 2 resource types (REACH ACOs only)

GET /api/v2/Group/all/$export?_type=Claim,ClaimResponse 

Example curl command using _type

curl -X GET "https://sandbox.bcda.cms.gov/api/v2/Group/all/\$export?_type=ExplanationOfBenefit,Patient" \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async" \
    -H "Authorization: Bearer {bearer_token}" \
    -i

The _since parameter

The _since parameter lets you filter for claims data last updated after a specified date. Dates must be in the FHIR standard instant format(YYYY-MM-DDThh:mm:sss+zz:zz.

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

We recommend new model entities run an unfiltered request for all historical data before using _since subsequently for incremental exports of new data. You can use the transactionTime from your most recent job as the specified date.

The _since parameter can be used with /Group or /Patient, but each endpoint will return data for newly attributed enrollees differently.

Using _since with /Patient

Using _since with /Patient will return resources updated after the date provided for existing and newly attributed enrollees.

Newly attributed enrollees are those who’ve been assigned to your model entity since your last attribution date. If you don’t apply _since, BCDA will return data as early as 2014.

Example request using _since with /Patient

GET /api/v2/Patient/$export?_type=Patient&_since=2020-02-13T08:00:00.000-05:00

Example curl command using _since with /Patient

This command combines the GET request and request header. The dollar sign $ before export in the URL indicates the endpoint is an action, not a resource.

curl -X GET "https://sandbox.bcda.cms.gov/api/v2/Patient/\$export?_type=Patient&_since=2020-02-13T08:00:00.000-05:00" \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async" \
    -H "Authorization: Bearer {bearer_token}" \
    -i

Using _since with /Group

Using _since with /Group will return resources updated after the date provided for existing enrollees and all resources for newly attributed enrollees.

This lets you retrieve all new claims data with a single request. If you don’t apply _since, BCDA will return data as early as 2014.

Example request using _since with /Group

The request below will return:

• Claims data last updated since February 13, 2020 for existing enrollees
• Claims data as far back as 2014 for all new enrollees attributed to your organization in the last month

GET /api/v2/Group/all/$export?_type=Patient&_since=2020-02-13T08:00:00.000-05:00

Example curl command using _since with /Group

curl -X GET "https://sandbox.bcda.cms.gov/api/v2/Group/all/\$export?_type=Patient&_since=2020-02-13T08:00:00.000-05:00" \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async" \
    -H "Authorization: Bearer {bearer_token}" \
    -i

The `runout` identifier

The `runout` identifier lets you request runouts data for enrollees attributed to your model entity the previous year, but not the current year. Claims data returned will have a service date no later than December 31 of the previous year.

The examples below are GET requests made to the /Group endpoint.

Example request for 1 resource type using `runout`

GET /api/v2/Group/runout/$export?_type=Patient

curl -X GET "https://sandbox.bcda.cms.gov/api/v2/Group/runout/\$export?_type=Patient" \
    -H "accept: application/fhir+json" \
    -H "Prefer: respond-async" \
    -H "Authorization: Bearer {bearer_token}" \
    -i

Example request for 2 resource types using `runout`

GET /api/v2/Group/runout/$export?_type=ExplanationOfBenefit,Patient

curl -X GET "https://sandbox.bcda.cms.gov/api/v2/Group/runout/\$export?_type=ExplanationOfBenefit,Patient" \
    -H "accept: application/fhir+json" \
    -H "Prefer: respond-async" \
    -H "Authorization: Bearer {bearer_token}" \
    -i

Request for all resources using `runout`

GET /api/v2/Group/runout/$export

curl -X GET "https://sandbox.bcda.cms.gov/api/v2/Group/runout/\$export" \
    -H "accept: application/fhir+json" \
    -H "Prefer: respond-async" \
    -H "Authorization: Bearer {bearer_token}" \
    -i