Skip to main content
Getting Started
Learn About BCDA in Sandbox

Version 2 of the Beneficiary Claims Data API (BCDA V2) endpoints are available as of Summer 2021. If you are interested in interacting with BCDA V2 endpoints, please navigate to the BCDA Version 2 (V2) section for more information.

What is an API?

The Beneficiary Claims Data API (BCDA) is an Application Programming Interface (API) that enables Accountable Care Organizations (ACOs) to retrieve Medicare claims data for their beneficiaries. BCDA serves as direct pipeline from CMS to ACO systems to provide claims data on at a more timely cadence. This includes Medicare claims data for instances in which beneficiaries receive care outside of the ACO, allowing a full picture of patient care.

This API follows the workflow outlined by the FHIR Bulk Data Export Proposal using the HL7 FHIR Standard. Claims data is provided as FHIR resources in NDJSON format.

Our documentation is written so that everyone – regardless of technical exposure – can access beneficiary data.

What is FHIR?

FHIR (Fast Healthcare Interoperability Resources) is a specification for exchanging healthcare data electronically. BCDA sends data acquired through the Beneficiary FHIR Data Server (BFD) API structured using the FHIR standard, making it more available, discoverable, and understandable. The FHIR standard is developed by HL7, a group dedicated to creating standardized ways of sharing and structuring health care data.

In FHIR, standardized data is structured using a basic building block called a “Resource.” All “exchangeable” data is defined as a resource. Resources are structured containers of data that systems and computers can easily understand. BCDA is one of CMS’ first APIs to use the bulk FHIR specification. The Bulk FHIR specification allows BCDA to send back records on all of an ACO’s assigned or assignable beneficiaries, rather than on a patient-by-patient basis.

BCDA's Environments

BCDA consists of two environments: sandbox and production. The environments feature the same endpoints, resources, and parameters. They differ only in who has access and whether synthetic or real beneficiary data is returned.

1. Sandbox Environment

In the sandbox environment, we provide generic credentials for you to use. We have provided five sets of synthetic credentials for use in the sandbox, corresponding to various amounts of synthetic beneficiaries. These will not work in the production environment. We suggest testing with the credentials that most closely align with the size of your ACO, so that you can get a feel for working with a similar amount of synthetic data to that which you’ll receive in production.

The sandbox environment contains all of the same endpoints, resource types, and parameters as production. You may complete all of the same operations as in production. However, sandbox data is not currently updated as frequently as your real data, and will not necessarily be as comprehensive or complete as real production data.

2. Production Environment

In order to obtain your organization’s claims data in the production environment, you must have obtained API credentials from either the ACO-MS system (for Shared Savings Program ACOs) or directly from the BCDA team (for non-SSP ACOs). Every request demands a bearer token which can only be obtained with active BCDA credentials.

Representatives of SSP ACOs are now able to generate BCDA credentials in their ACO-MS portal accounts. To view instructions on how to generate API credentials, log into your ACO-MS account and navigate to the ACO-MS Knowledge Library. Before you generate BCDA credentials, please try out the BCDA Sandbox experience.

BCDA's FHIR Resource Types

BCDA uses three resource types under the FHIR specification.

1. Explanation of Benefit (EOB)

The Explanation of Benefit resource type provides the same information ACOs receive in CCLF files 1-7. This file contains the lines within an episode of care, including where and when the service was performed, the diagnosis codes, the provider who performed the service, and the cost of care.

2. Patient

The Patient resource type can be thought of as an ACO’s CCLF files 8 and 9: this is where you get information about who your beneficiaries are, their demographic information, and updates to their patient identifiers.

3. Coverage

The Coverage resource type indicates the beneficiary’s enrollment record. It includes information on a beneficiary’s Part A, Part B, Part C, and Part D coverage, as well as markers for End-stage Renal Disease (ESRD) and Old Age and Survivors Insurance (OASI).

BCDA's Bulk FHIR Endpoints

1. /Metadata endpoint

The /Metadata endpoint allows you to request basic information on the API. You may check if the API is currently active and what version of the API you are interacting with. You are not required to provide authorization to make a request to the metadata endpoint.

2. /Patient endpoint

The /Patient endpoint allows you to request ExplanationOfBenefit, Patient, and/or Coverage data for all beneficiaries assigned or assignable to your ACO.

Note that the /Patient endpoint does not allow requests for data patient-by-patient. By the Bulk FHIR specification, only data for all patients associated with the authorized users’ credentials can be returned.

You may also filter data by date using the _since parameter. If no filter is applied, a request to the /Patient endpoint in BCDA returns seven years of historical data for all assigned and assignable beneficiaries.

3. /Group endpoint

The /Group endpoint allows you to request ExplanationOfBenefit, Patient, and/or Coverage data for all beneficiaries assigned or assignable to your ACO. You must supply a group parameter. The only supported parameter currently is ‘all’.

You may also filter data by date using the _since parameter. If no filter is applied, a request to the /Group endpoint in BCDA returns seven years of historical data for all assigned and assignable beneficiaries.

Differences between /Patient and /Group when using _since

Both /Patient and /Group support the _since parameter, but they have a key difference in how new beneficiaries are treated. New beneficiaries are those that are newly assigned to you since your last attribution date.

If you use _since within the /Patient endpoint, you will receive data filtered since the selected date for ALL of your assigned and assignable beneficiaries. Here, new beneficiary data is filtered along with all other beneficiaries.

If you use _since within the /Group endpoint, you will receive data filtered since the selected date for your existing beneficiaries AND you will receive 7 years of historical data unfiltered by date for new beneficiaries. Here, new beneficiaries are excluded from the _since filter so that your organization can easily retrieve all new data with a single request.

For more detail on these differences and examples of how to make the requests, see the Requesting Filtered Data section of the Building Your Application page.

BCDA's Parameters

Parameters are options that can be passed to the endpoint to influence the response. Parameters can be used to filter or select for certain desired data. We would like to highlight two query parameters used in BCDA.

1. The type parameter

The _type parameter allows you to request different Resource Types from the API. Instead of receiving data from all three Resource Types when no _type parameter is specified, you will be able to use the _type parameter to submit one or more Resource Types. The API will then produce data from the specified Resource Types.

To learn more about the Resource Types see the FHIR Resource Types section above.

2. The since parameter

The _since parameter allows you to apply a date parameter to your bulk data requests. Instead of receiving the full record of historical data every time you request data from an endpoint, you will be able to use _since to submit a date. The API will then produce claims data from the bulk data endpoints that have been loaded since the entered date.

To learn more about the differences using _since between the /Patient and /Group endpoints see the FHIR endpoints section above.

BCDA Version 2 (V2)

Version 2 of the Beneficiary Claims Data API (BCDA V2) is now available as of Summer 2021.

BCDA V2 conforms to the FHIR R4 specification and follows the CARIN Implementation Guide for industry alignment. BCDA will support all functionality for both V1 and V2 of the API for the foreseeable future; however, upgrading to BCDA’s V2 API ensures your product is aligned with the latest industry standards. For more information on BCDA V2, please visit the CMS V2 API FAQ Documentation. For more information on how BCDA data will change in BCDA V2, please visit the BCDA Understanding the Data page.

How will BCDA V2 change how I interact with the BCDA API?

BCDA V2 supports the same functionality as V1 API endpoints in both the Sandbox and Production API environments. All V2 API endpoints should work as described in existing BCDA documentation. If you wish to transition your implementation to utilize BCDA V2 endpoints instead of V1, users simply need to replace ‘v1’ in API call URLs with ‘v2’. Here is an example:

Sample cURL Command in BCDA V1:

curl -X GET 'https://sandbox.bcda.cms.gov/api/v1/Patient/$export' \
-H "accept: application/fhir+json" \
-H "Prefer: respond-async" \
-H "Authorization: Bearer {access_token}"

Sample cURL Command in BCDA V2:

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

Try the API

To get you started with BCDA, we have provided the bare minimum steps to access data in the sandbox. Using the four cURL commands below, you should be able to walk through the standard process of retrieving data from the API:

  1. Obtain an access token: How do I show the API that I can receive this data?
  2. Start a job to acquire data: How do I tell the API to get my data?
  3. Check the job status: How do I check when the API is done getting my data?
  4. Download the data: How do I get my data once it is done?

All requests for BCDA data follow this four step process, as do other APIs following the Bulk FHIR specifications.

For far more detail for each of these steps and specific information for retrieving production data, see the Building Your Application page. For this short demo, please follow along in your Terminal window or through an application such as Postman.

Client ID:

Client Secret:

Client ID:

Client Secret:

Client ID:

Client Secret:

Client ID:

Client Secret:

Client ID:

Client Secret:

Step 1: Obtain an Access Token

For this demonstration, we will provide sample API credentials to the sandbox environment. We will be using the sample credentials for an Extra-Small ACO (25 beneficiaries). Feel free to follow along with any of the sample credentials.

Our credentials come in two pieces: a Client ID and a Client Secret. We will submit these two pieces to the API. Notice that the credentials are included one of the headers (--user). You must use this format: --user {insert client id}{insert colon}{insert client secret}.

Sample cURL Command to Submit Credentials for an Access Token

curl -d '' -X POST 'https://sandbox.bcda.cms.gov/auth/token' \
--user 0c527d2e-2e8a-4808-b11d-0fa06baf8254:36e0ea2217e6d6180f3ab1108d02ca100d684ebdccc04817ce842300996e568c3d77fc61d84006a3 \
-H "accept: application/json"

Response Example after Submitting Credentials for an Access Token

We now have a key (an access token) to interact with the API! It expires after 20 minutes.

If the request was successful, we will receive a response with the code 200 containing a few headers. The first header ("access token") contains a long string of characters. This is our access token which must be attached to all of our other requests to the API.

{
"access_token": "eyJhbGciOiJSUzUxMiIsInR5c...",
"token_type":"bearer"
}

Step 2: Start a Job

With our new access token, we are clear to make more requests to the API. We will now tell the server to serve up our data.

In this example, we're requesting data from the /Patient endpoint with no date filter (no _since parameter) and no specified resource type (no _type parameter). We will include the long string of characters from the previous step (our access token) in the authorization header (-H "Authorization: Bearer "). Notice that we need to include the word Bearer with a space before the access token.

Sample cURL Command to Start a Job

curl -X GET 'https://sandbox.bcda.cms.gov/api/v1/Patient/$export' \
-H "accept: application/fhir+json" \
-H "Prefer: respond-async" \
-H "Authorization: Bearer {access_token}"

Response Example after Starting a Job

We've now started a data export job. It may take some time to complete, depending on how much claims data is contained in our job.

If the request was successful, we will receive a response with the code 202 containing a few headers. One of the headers (Content-Location) will contain a URL. Notice that the URL ends in a number. This is the Job ID of the job we just started. In the next step, we will use this URL and Job ID to check if the server is done preparing our file(s).

202 Accepted
Content-Location: https://sandbox.bcda.cms.gov/api/v1/jobs/42

Step 3: Check the Job Status

Now that our job is in progress, we can check back in occasionally to see if it is finished. The data for our synthetic sandbox ACOs should not take too long to compile.

We will make a request to the API to check on our job. Notice the URL in the first line (curl -X GET "URL") is the same as the URL from the previous step in the Content-Location header.

Sample cURL Command to Check the Job Status

curl -X GET 'https://sandbox.bcda.cms.gov/api/v1/jobs/42' \
-H "accept: application/fhir+json" \
-H "Authorization: Bearer {access_token}"

Response Example after Checking on a Job

It looks like our job is finished and our data is ready to be downloaded.

If the request was successful, and the job is finished, we will receive a response containing many headers. Some of these headers ("url") will contain a URL. Each of these URLs corresponds to a file containing claims data. We received three files: one for each resource type. We will use these URLs to download the data in the final step.

{
  "transactionTime": "2019-12-09T20:44:01.705398Z",
  "request": "https://sandbox.bcda.cms.gov/api/v1/Patient/$export",
  "requiresAccessToken": true,
  "output": [
    {
      "type": "ExplanationOfBenefit",
      "url": "https://sandbox.bcda.cms.gov/data/42/afd22dfa-c239-4063-8882-eb2712f9f638.ndjson"
    },
    {
      "type": "Coverage",
      "url": "https://sandbox.bcda.cms.gov/data/42/f76a0b76-48ed-4033-aad9-d3eec37e7e83.ndjson"
    },
    {
      "type": "Patient",
      "url": "https://sandbox.bcda.cms.gov/data/42/f92dcf16-63a2-448e-a12a-3bf677f966ed.ndjson"
    }
  ],
  "error": [],
  "JobID": 42
}

Step 4: Download the Data

The final step in the workflow is to download your data. Make another request to the API, this time using any of the URLs retrieved in the previous step. Each URL corresponds to a single file and will begin the download of that file. We will need to make three download requests to get all three of our files.

Sample cURL Command to Download the Data

curl 'https://sandbox.bcda.cms.gov/data/42/afd22dfa-c239-4063-8882-eb2712f9f638.ndjson' \
-H "Authorization: Bearer {access_token}" \
-H "Accept-Encoding: gzip"

Response Example after Downloading the Data

  1. Explanation of Benefit
  2. Patient
  3. Coverage

Congratulations!

If the all of the steps above worked, you will now have files of synthetic beneficiary claims data on your local machine! You have walked through the process of proving your authentication to the API, starting a job to compile your data, checking on that job using its ID number, and downloading the results using the filenames. This four step process is universal for BCDA data requests (and many other Bulk FHIR workflows).

Remember, this was just the most basic call for claims data that could be made to BCDA. To see how to download different combinations of Resource Types, filter data by date, filter some beneficiary data by date while retrieving all data for others, and (most importantly) to download data for your organizations' real beneficiaries, see the Building Your Application page.