What Is an API?
The Beneficiary Claims Data API (BCDA) is an Application Programming Interface (API) that enables model entities – Accountable Care Organizations (ACO), Direct Contracting Entities (DCE), Kidney Care Entities (KCE), and Kidney Care First (KCF) Entities – to retrieve Medicare claims data for their beneficiaries. BCDA serves as a direct pipeline from CMS to model entity systems to provide claims data on a more timely cadence. This includes Medicare claims data for instances in which beneficiaries receive care outside of the model entities, 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 a model entity'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 in who has access and whether synthetic or real beneficiary data is returned. BCDA v2 is the only version compatible with partially adjudicated claims data.
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 model entity, so that you can experiment 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.
Try out the BCDA Sandbox!
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 from 4i for REACH ACOs, and DCEs, KCEs, and KCF Entities. Every request demands a bearer token which can only be obtained with active BCDA credentials.
Representatives of Shared Savings Program (SSP) ACOs can generate BCDA credentials by logging into their ACO-MS portal accounts and navigating to the ACO-MS Knowledge Library. REACH ACOs and DCEs, KCEs, and KCF Entities can do the same by logging into their 4i account and navigate to the 4i Knowledge Library.
Reminder: Before you generate BCDA credentials, please try out the BCDA Sandbox experience.
BCDA's FHIR Resource Types
BCDA uses five resource types under the FHIR specification, 3 (EOB, Patient, Coverage) are used for adjudicated claims and 2 (Claim and ClaimResponse) are used for partially adjudicated claims.
1. Explanation of Benefit (EOB)
The Explanation of Benefit resource type provides similar information to what was previously provided in CCLF files 1-7. The EOB files contain 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 your CCLF files 8 and 9. This is where you get your information about who your beneficiaries are, their demographic information, and updates to their patient identifiers.
3. Coverage
The Coverage resource type provides information about beneficiaries’ insurance coverage, including information about dual coverage.
4. Claim
The Claim resource type is available for partially adjudicated claims for REACH ACOs. The claim resource type provides information about professional and institutional claims providers submit for payment, including the services that beneficiaries receive.
5. ClaimResponse
The ClaimResponse resource type is available for partially adjudicated claims for REACH ACOs. The ClaimResponse resource type provides information about a claim’s adjudication status and results process.
BCDA's 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. For adjudicated claims the resource types that are available include Patient and/or Coverage data (all eligible model entities), while for partially adjudicated claims the resource types that are available include Claim and ClaimResponse (REACH ACOs only). Both kinds of data are available for all enrollees assigned or assignable to your model entity. 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 historical data for all assigned and assignable beneficiaries as far back as 2014.
3. /Group endpoint
The /Group endpoint allows you to request ExplanationOfBenefit, Patient, and/or Coverage data for all beneficiaries assigned or assignable to your model entity. For partially adjudicated claims, the resource types that are available include Claim and ClaimResponse (REACH ACOs only).
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 historical data for all assigned and assignable beneficiaries as far back as 2014.
4. /Jobs endpoint
The /Jobs endpoint allows you to request information about requests your model entity has previously made to the API. This data includes the Job ID, creation time, completion time, and the original request of the job.
If you cannot remember a Job ID after starting a job, you can use this endpoint to retrieve the ID, rather than restarting a new job. The data returned will be in the FHIR Task format.
5. /Attribution_Status endpoint
The /Attribution_Status endpoint will return a datetime timestamp representing the last time that BCDA updated the beneficiary list of your organization, which includes updates from runout files. Since attribution is updated monthly, it can be beneficial to know exactly when your organization's attributions were last updated. Depending on your use case, you may want to run a query excluding the _since parameter after organization's attributions have been updated so that you can establish a historic record of your newly attributed beneficiaries.
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)
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 the way 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, replace ‘v1’ in the API call URLs with ‘v2’. Here is an example:
| Sample cURL Command in BCDA V2: | Sample cURL Command in BCDA V1: |
|---|---|
|
|
Try the API
To get you started with BCDA, we provide the 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:
- Obtain an access token: How do I show the API that I can receive this data?
- Start a job to acquire data: How do I tell the API to get my data?
- Check the job status: How do I check when the API is done getting my data?
- 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 more detail for each of these steps and specific information for retrieving production data, see the Building Your Application page. For this short demo, follow along in your Terminal window or through an application such as Postman.
BCDA Synthetic Data
BCDA has provided nine synthetic data sample sets for use. Because all of these data sets are synthetic, they can be accessed without any BCDA production environment credentials or approval by BCDA.
Simple Datasets - Five Sizes
Five of these datasets are simple approximations of BCDA data designed for model entities to test the stress of retrieving and downloading large data files into their internal ingestion processes. These datasets are offered in various sizes so that organizations can test files with a number of beneficiaries that best matches the needs of their organization (the datasets range from 50 to 30,000 synthetic beneficiaries). However, the data in these API payloads will not reflect the distribution of disease and demographic information you might expect from production data.
Advanced Datasets - Two Sizes
These two datasets are designed to offer data that is a more accurate representation of BCDA production data. They follow BCDA’s Bulk FHIR format and should contain a more realistic distribution of disease and demographic information. The advanced datasets are offered in two sizes: Extra Small (100 beneficiaries) and Large (10,000 beneficiaries). We suggest using the Extra-Small Model Entity file to simply view and begin to understand the format of BCDA data. You may want to use the Large dataset for more in-depth exploration of the data or early load testing of your systems.
Partially Adjudicated Claims Datasets - Two Sizes
These last two datasets are examples representing data from our Partially Adjudicated Claims data. They include the additional FHIR® resources Claim and ClaimResponse for Partially Adjudicated Claims data. The Partially adjudicated claims data requires BCDA v2.
- Claim: Contains information about professional and institutional claims that providers submit for payment, including the services that beneficiaries receive.
- ClaimResponse: Provides information about a claim's adjudication status and results.
Sample Credentials
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 Model Entity (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 in 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 2462c96b-6427-4efb-aed7-118e20c2e997:8e87f0ebc50d10f1bc9734329a9900179b84ccd39e4d0920b905cc359cf6e94a6e760bbe3a0890c7 \
-H "accept: application/json"Response Example after Submitting Credentials for an Access Token
We 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 able to make more requests to the API. We will now tell the server to deliver our data.
In this example, we requested data from the /Patient endpoint with no date filter (no _since parameter) and no specified resource type (no _type parameter). We included the long string of characters from the previous step (our access token) in the authorization header (-H "Authorization: Bearer "). Notice that we needed to include the word "Bearer" followed by a space before the access token. We also added "-v" in order to see the Job ID.
Sample cURL Command to Start a Job
curl -X GET 'https://sandbox.bcda.cms.gov/api/v2/Group/all/$export' \
-H "accept: application/fhir+json" \
-H "Prefer: respond-async" \
-H "Authorization: Bearer {access_token}" \
-v
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/v2/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 model entities 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/v2/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 five files: one for each resource type. We will use these URLs to download the data in the final step.
{
"transactionTime": "2021-12-09T20:44:01.705398Z",
"request": "https://sandbox.bcda.cms.gov/api/v2/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"
},
{
"type": "Claim",
"url": "https://sandbox.bcda.cms.gov/data/42/6397b6b8-5842-493a-9206-e68b2995c001.ndjson"
},
{
"type": "ClaimResponse",
"url": "https://sandbox.bcda.cms.gov/data/42/0a0b1312-e0a2-4284-a094-1b98bdd0de3c.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
Congratulations!
If 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).
Go to the Building Your Application page to see how to download data for your organizations' real beneficiaries, download different combinations of Resource Types, filter data by date, and filter some beneficiary data by date while retrieving all data for others.