How to Filter Claims Data

BCDA offers 3 query parameters to filter or specify the resources returned:

• _since: applies a date boundary to your request
• _type: limits your request to 1 or more specific resource types
• _typeFilter: limits your request to resources matching the provided criteria

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

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/v3/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/v3/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/v3/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/v3/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 _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.

Using _type

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/v3/Group/all/$export?_type=Patient

Example request for 2 resource types

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

Example curl command using _type

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

The _typeFilter parameter lets you use resource metadata to create finer-grained filtering criteria. BCDA will only return claims data that meets the specified criteria provided as a URL Encoded FHIR REST API query.

Using _typeFilter

Currently, _typeFilter only supports queries using the meta.tag element of ExplanationOfBenefit resources.

Example request using _typeFilter

The request below will return:

• All Patient and Coverage resources
• ExplanationOfBenefit resources of only partially adjudicated claims only

GET /api/v3/Group/all/$export?_typeFilter=ExplanationOfBenefit?_tag=PartiallyAdjudicated

Example curl command using _typeFilter

curl -X GET "https://sandbox.bcda.cms.gov/api/v32/Group/all/\$export?_typeFilter=ExplanationOfBenefit%3F_tag%3DPartiallyAdjudicated" \
    -H "Accept: application/fhir+json" \
    -H "Prefer: respond-async" \
    -H "Authorization: Bearer {bearer_token}" \
    -i

Filtering claims by adjudication status using _typeFilter

By default, any unfiltered request made to either BCDA v2 or v3 by a REACH ACO will include both partially adjudicated and fully adjudicated claims data.

In BCDA v3, the ExplanationOfBenefit Resource represents both partially adjudicated and fully adjudicated claims data. You can differentiate adjudication status by using the _tag property for the values “Adjudicated” or “PartiallyAdjudicated”.

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.

Using the runout identifier

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

Example request for 1 resource type using runout

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

curl -X GET "https://sandbox.bcda.cms.gov/api/v3/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/v3/Group/runout/$export?_type=ExplanationOfBenefit,Patient

curl -X GET "https://sandbox.bcda.cms.gov/api/v3/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/v3/Group/runout/$export

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