BCDA User Guide Documentation
For each request and operation, we provide example requests and example cURL commands. We will highlight any common errors or unique attributes of our API. Lastly, we will provide an example response from the API.
Request Metadata
You may want to retrieve metadata to check what version of the API is currently active or to check on the status of the API.
Metadata about the Beneficiary Claims Data API is available as a FHIR CapabilityStatement resource. A token is not required to access this information.
Metadata Request
GET /api/v1/metadata
Metadata cURL Command
curl https://api.bcda.cms.gov/api/v1/metadata
Metadata Response Example
{
"resourceType": "CapabilityStatement",
"status": "active",
"date": "2020-10-15",
"publisher": "Centers for Medicare & Medicaid Services",
"kind": "instance",
"instantiates": [
"https://prod-sbx.bfd.cms.gov/baseDstu3/metadata/",
"http://hl7.org/fhir/uv/bulkdata/CapabilityStatement/bulk-data"
],
"software": {
"name": "Beneficiary Claims Data API",
"version": "r79",
"releaseDate": "2020-10-15"
},
"implementation": {
"description": "The Beneficiary Claims Data API (BCDA) enables Accountable Care Organizations (ACOs) participating in the Shared Savings Program to retrieve Medicare Part A, Part B, and Part D claims data for their prospectively assigned or assignable beneficiaries.",
"url": "https://sandbox.bcda.cms.gov"
},
"fhirVersion": "3.0.1",
"acceptUnknown": "extensions",
"format": [
"application/json",
"application/fhir+json"
],
"rest": [
{
"mode": "server",
"security": {
"extension": [
{
"extension": [
{
"url": "token",
"valueUri": "https://sandbox.bcda.cms.gov/auth/token"
}
],
"url": "http://fhir-registry.smarthealthit.org/StructureDefinition/oauth-uris"
}
],
"cors": true,
"service": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/restful-security-service",
"code": "OAuth",
"display": "OAuth"
}
],
"text": "OAuth"
}
]
},
"interaction": [
{
"code": "batch"
},
{
"code": "search-system"
}
],
"operation": [
{
"name": "patient-export",
"definition": {
"reference": "http://hl7.org/fhir/uv/bulkdata/OperationDefinition/patient-export"
}
},
{
"name": "group-export",
"definition": {
"reference": "http://hl7.org/fhir/uv/bulkdata/OperationDefinition/group-export"
}
}
]
}
]
}
Metadata Explanation
This operation will return data about the API in an NDJSON format. You may view the version of the API that is currently active, the version of FHIR currently supported, and other useful information.
Requesting Data during End of Year Attribution
When will these changes end?
We expect these changes to be in effect until BCDA retrieves the January 2021 attribution file from CMS. This should be no later than January 31, 2021. After this time, requests to /Patient and /Group using `all` will return to their normal state of operation. In addition, you can continue to use /Group with `runout` to retrieve your 2020 claims runout data. BCDA will update the Google Group when you can begin using `all` again.
What changes does my ACO need to make?
In January 2021:
- To request any claims, users will need to use the `runout` identifier with the /Group endpoint.
- Requests to the /Group and /Patient endpoints without the `runout` identifier will result in an error message.
- When using the `runout` identifier, data returned by the API will be restricted to claims with a service date of 12/31/2020 or earlier.
Between February and April 2021:
- Requests to the /Group and /Patient endpoints can again use the `all` identifier, as normal and will return claims with a service date in 2021.
- To request runouts data, users can also make a call using the `runout` identifier with the /Group endpoint.
- When using the `runout` identifier, data returned by the API will be restricted to claims with a service date of 12/31/2020 or earlier.
List of Requests
During January, you can make a few different unfiltered requests for data, all of them must be to the /Group endpoint and include the 'runout identifier:
- Request all three Resource Types at once
- Request any two Resource Types
- Request a single Resource Type
Steps
Each request will follow the same four step process:
- Obtain an access token
- Start a job to acquire data
- Check the job status
- Download the data
Request All Three Resource Types with /Group and `runout`
Step 1: Obtain an Access Token
See Authentication and Authorization above.
Step 2: Start a job to acquire data
Requests to start a job
GET /api/v1/Group/runout/$export
GET /api/v1/Group/runout/$export?_type=ExplanationOfBenefit,Patient
GET /api/v1/Group/runout/$export?_type=Patient
Request Headers
Authorization: Bearer {access_token}
Accept: application/fhir+json
Prefer: respond-async
cURL Commands to start a job
-
curl -X GET 'https://api.bcda.cms.gov/api/v1/Group/runout/$export' \ -H "accept: application/fhir+json" \ -H "Prefer: respond-async" \ -H "Authorization: Bearer {access_token}"
-
curl -X GET 'https://api.bcda.cms.gov/api/v1/Group/runout/$export?_type=ExplanationOfBenefit,Patient' \ -H "accept: application/fhir+json" \ -H "Prefer: respond-async" \ -H "Authorization: Bearer {access_token}"
-
curl -X GET 'https://api.bcda.cms.gov/api/v1/Group/runout/$export?_type=Patient' \ -H "accept: application/fhir+json" \ -H "Prefer: respond-async" \ -H "Authorization: Bearer {access_token}"
Response Example: Successful Request
202 Accepted
Response Example: Runout Identifier Not Included
400 Bad Request
Response Headers
Content-Location: https://api.bcda.cms.gov/api/v1/jobs/42
Start a Job Explanation
This operation will start a data export job. We have provided three example requests and three example cURL statements to start a job for:
- All three resource types
- Any two resource types (we use EOB and Patient as an example)
- Any single resource type (we use Patient as an example)
For all of the requests, a GET request is made to the /Group endpoint with the `runout` identifier. To retrieve all three resource types, simply exclude the _type query parameter. For one or two resource types, the desired resources are set in the _type query parameter. Notice that, for multiple resource types, they must be separated by commas.
Your access token is required and set as a header. Accept and Prefer headers are also required. The dollar sign ('$') before the word "export" in the URL indicates that the endpoint is an action rather than a resource. The format is defined by the FHIR Bulk Data Export spec.
If the request was successful, a 202 Accepted response code will be returned and the response will include a Content-Location header. The value of the Content-Location header indicates the location to check for job status and outcome. In the example header below, the number 42 in the URL represents the ID of the export job. The claims returned in the job will be filtered to have a serviceDate of 12/31/2020 or before.
If you try to request data from the /Patient endpoint or from the /Group endpoint without using the 'runout' identifier, you will receive a `400 Bad Request` error. The operational outcome will direct you to make a new request to the /Group endpoint with `runout`.
If you're already requesting data from one endpoint and try to request data from that endpoint again while the first request is processing, you'll receive a 429 Too Many Requests error.
Step 3: Check the job status
Request to check the job status
GET https://api.bcda.cms.gov/api/v1/jobs/42
Request Headers
Authorization: Bearer {access_token}
Accept: application/fhir+json
cURL Command to check the job status
curl -X GET 'https://api.bcda.cms.gov/api/v1/jobs/42' \
-H "accept: application/fhir+json" \
-H "Authorization: Bearer {access_token}"
Response Example: Completed Job
{
"transactionTime": "2019-12-09T20:44:01.705398Z",
"request": "https://api.bcda.cms.gov/api/v1/Group/runout/$export",
"requiresAccessToken": true,
"output": [
{
"type": "ExplanationOfBenefit",
"url": "https://api.bcda.cms.gov/data/42/afd22dfa-c239-4063-8882-eb2712f9f638.ndjson"
},
{
"type": "Coverage",
"url": "https://api.bcda.cms.gov/data/42/f76a0b76-48ed-4033-aad9-d3eec37e7e83.ndjson"
},
{
"type": "Patient",
"url": "https://api.bcda.cms.gov/data/42/f92dcf16-63a2-448e-a12a-3bf677f966ed.ndjson"
}
],
"error": [],
"JobID": 42
}
Response Headers: Incomplete Job
X-Progress: In Progress
Check the Job Status Explanation
This operation will check on the status of a job and return its progress if it has not finished. Notice that the GET request is simply the URL found in the Content-Location header from the previous step (starting a job) within the response section.
Within the response, a `202 Accepted` indicates that the job is processing. The response headers will include the X-Progress header. The X-Progress header value will include text indicating the job's status in BCDA's workflow and an estimated progress percentage. For example, `X-Progress: In Progress, 80%.`
The status will change from `202 Accepted` to `200 OK` when the export job is complete and the data is ready to be downloaded.
Claims data can be found at the URLs within the output field. The claims returned in the job will be filtered to have a serviceDate of 12/31/2020 or before. The number 42 in the data file URLs is the same job ID from the Content-Location header URL in the previous step. If some of the data cannot be exported due to errors, details of the errors can be found at the URLs in the error field. The errors are provided in an NDJSON file as FHIR OperationOutcome resources.
Step 4: Download the data
Request to download the data
GET https://api.bcda.cms.gov/data/42/afd22dfa-c239-4063-8882-eb2712f9f638.ndjson
Request Headers
Authorization: Bearer {access_token}
Accept-Encoding: gzip
cURL Command to download the data
curl -X GET 'https://api.bcda.cms.gov/data/42/afd22dfa-c239-4063-8882-eb2712f9f638.ndjson' \
-H "Accept-Encoding: gzip" \
-H "Authorization: Bearer {access_token}"
Response Example
Response Headers
Content-Encoding: gzip
Downloading the Data Explanation
This operation will allow you to obtain the exported data. Notice that the request contains the output URL for a job that is complete (200 OK status).
The "Accept-Encoding: gzip" header is optional, but will return a significantly smaller (40X smaller) file with a faster download speed. You will need to uncompress the file after downloading if you supply this header. When downloading multiple files, you can further speed up the process by downloading multiple files concurrently. The claims returned in the job will be filtered to have a serviceDate of 12/31/2020 or before.
The response will be the requested data as FHIR resources in NDJSON format. Each file related to a different resource type will appear separately and labeled as to which resource type it contains. Examples of data from each Resource Type are available in the guide to working with BCDA data.
Requesting Data
To obtain all the available data (up to 7 years) for all of your beneficiaries, you can make a request to either the /Patient or /Group endpoint. You may want to do this as a first call, as a way to check for BCDA files against CCLF, or to create a database.
BCDA data will be updated weekly, so you will be able to make requests and expect to retrieve new data on a weekly basis.
List of Requests
You can make a few different unfiltered requests for data:
- Request all three Resource Types at once
- Request any two Resource Types
- Request a single Resource Type
Steps
Each request will follow the same four step process:
- Obtain an access token
- Start a job to acquire data
- Check the job status
- Download the data
Request All Three Resource Types
Step 1: Obtain an Access Token
See Authentication and Authorization above.
Step 2: Start a job to acquire data
Requests to start a job
GET /api/v1/Patient/$export
GET /api/v1/Patient/$export?_type=ExplanationOfBenefit,Patient
GET /api/v1/Patient/$export?_type=Patient
Request Headers
Authorization: Bearer {access_token}
Accept: application/fhir+json
Prefer: respond-async
cURL Commands to start a job
-
curl -X GET 'https://api.bcda.cms.gov/api/v1/Patient/$export' \ -H "accept: application/fhir+json" \ -H "Prefer: respond-async" \ -H "Authorization: Bearer {access_token}"
-
curl -X GET 'https://api.bcda.cms.gov/api/v1/Patient/$export?_type=ExplanationOfBenefit,Patient' \ -H "accept: application/fhir+json" \ -H "Prefer: respond-async" \ -H "Authorization: Bearer {access_token}"
-
curl -X GET 'https://api.bcda.cms.gov/api/v1/Patient/$export?_type=Patient' \ -H "accept: application/fhir+json" \ -H "Prefer: respond-async" \ -H "Authorization: Bearer {access_token}"
Response Example: Successful Request
202 Accepted
Response Example: Too Many Requests
429 Too Many Requests
Response Headers
Content-Location: https://api.bcda.cms.gov/api/v1/jobs/42
Start a Job Explanation
This operation will start a data export job. We have provided three example requests and three example cURL statements to start a job for:
- All three resource types
- Any two resource types (we use EOB and Patient as an example)
- Any single resource type (we use Patient as an example)
For all three resource types, a GET request is made to the /Patient endpoint without the _type query parameter. For one or two resource types, the desired resources are set in the _type query parameter. Notice that, for multiple resource types, they must be separated by commas.
Your access token is required and set as a header. Accept and Prefer headers are also required. The dollar sign ('$') before the word "export" in the URL indicates that the endpoint is an action rather than a resource. The format is defined by the FHIR Bulk Data Export spec.
If the request was successful, a 202 Accepted response code will be returned and the response will include a Content-Location header. The value of this header indicates the location to check for job status and outcome. In the example header below, the number 42 in the URL represents the ID of the export job.
If you're already requesting data from one endpoint and try to request data from that endpoint again while the first request is processing, you'll receive a 429 Too Many Requests error.
Step 3: Check the job status
Request to check the job status
GET https://api.bcda.cms.gov/api/v1/jobs/42
Request Headers
Authorization: Bearer {access_token}
Accept: application/fhir+json
cURL Command to check the job status
curl -X GET 'https://api.bcda.cms.gov/api/v1/jobs/42' \
-H "accept: application/fhir+json" \
-H "Authorization: Bearer {access_token}"
Response Example: Completed Job
{
"transactionTime": "2019-12-09T20:44:01.705398Z",
"request": "https://api.bcda.cms.gov/api/v1/Patient/$export",
"requiresAccessToken": true,
"output": [
{
"type": "ExplanationOfBenefit",
"url": "https://api.bcda.cms.gov/data/42/afd22dfa-c239-4063-8882-eb2712f9f638.ndjson"
},
{
"type": "Coverage",
"url": "https://api.bcda.cms.gov/data/42/f76a0b76-48ed-4033-aad9-d3eec37e7e83.ndjson"
},
{
"type": "Patient",
"url": "https://api.bcda.cms.gov/data/42/f92dcf16-63a2-448e-a12a-3bf677f966ed.ndjson"
}
],
"error": [],
"JobID": 42
}
Response Headers: Incomplete Job
X-Progress: In Progress
Check the Job Status Explanation
This operation will check on the status of a job and return its progress if it has not finished. Notice that the GET request is simply the URL found in the Content-Location header. The Content Location header is found from the previous step (starting a job) within the response section.
Within the response, a 202 Accepted indicates that the job is processing. The response headers will include the X-Progress header. The X-Progress header value will include text indicating the job's status in BCDA's workflow and an estimated progress percentage. For example, X-Progress: In Progress, 80%.
The status will change from 202 Accepted to 200 OK when the export job is complete and the data is ready to be downloaded.
Claims data can be found at the URLs within the output field. The number 42 in the data file URLs is the same job ID from the Content-Location header URL in the previous step. If some of the data cannot be exported due to errors, details of the errors can be found at the URLs in the error field. The errors are provided in an NDJSON file as FHIR OperationOutcome resources.
Step 4: Download the data
Request to download the data
GET https://api.bcda.cms.gov/data/42/afd22dfa-c239-4063-8882-eb2712f9f638.ndjson
Request Headers
Authorization: Bearer {access_token}
Accept-Encoding: gzip
cURL Command to download the data
curl -X GET 'https://api.bcda.cms.gov/data/42/afd22dfa-c239-4063-8882-eb2712f9f638.ndjson' \
-H "Accept-Encoding: gzip" \
-H "Authorization: Bearer {access_token}"
Response Example
Response Headers
Content-Encoding: gzip
Downloading the Data Explanation
This operation will allow you to obtain the exported data. Notice that the request contains the output URL for a job that is complete (200 OK status).
The "Accept-Encoding: gzip" header is optional, but will return a significantly smaller (40X smaller) file with a faster download speed. You will need to uncompress the file after downloading if you supply this header. When downloading multiple files, you can further speed up the process by downloading multiple files concurrently.
The response will be the requested data as FHIR resources in NDJSON format. Each file related to a different resource type will appear separately and labeled as to which resource type it contains. Examples of data from each Resource Type are available in the guide to working with BCDA data.
Requesting Filtered Data
You may want to obtain filtered data for all of your beneficiaries or for a subset of your beneficiaries in order to reduce file size and download time. You can make a request using the _since parameter to either the /Patient or /Group endpoints, but be wary that you understand the difference regarding newly added beneficiaries. You may want to do this as a repeating call or as a way to check for new data.
List of Requests
You can make a few different filtered requests for data:
- Request the most recent data for all beneficiaries: Use _since within the /Patient endpoint
- Request the most recent data for all beneficiaries AND historical data for newly added beneficiaries: Use _since within the /Group endpoint
Steps
Each request will follow the same four step process as an unfiltered request:
- Obtain an access token
- Start a job to acquire data (you will input the _since parameter here)
- Check the job status
- Download the data
The only difference appears in the request of Step 2: Start a job to acquire data. We show examples of this step below.
Format dates and times by the FHIR standard
Dates and times submitted in _since must be listed in the FHIR instant format (YYYY-MM-DDThh:mm:sss+zz:zz).
- Sample Date: February 20, 2020 12:00 PM EST
- instant Format: YYYY-MM-DDThh:mm:sss+zz:zz
- Formatted Sample: 2020-02-20T12:00:00.000-05:00
For more information consult FHIR Datatypes page.
Requesting using _since with the /Patient endpoint
Step 1: Obtain an Access Token
See Authentication and Authorization above.
Step 2: Start a job
Request to start a job using the _since parameter within the /Patient endpoint
GET /api/v1/Patient/$export?_type=Patient&_since=2020-02-13T08:00:00.000-05:00
Request Headers
Authorization: Bearer {access_token}
Accept: application/fhir+json
Prefer: respond-async
cURL Command using the _since parameter within the /Patient endpoint
curl -X GET 'https://api.bcda.cms.gov/api/v1/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 {access_token}"
Response Example: Successful Request
202 Accepted
Response Example: Too Many Requests
429 Too Many Requests
Response Headers
Content-Location: https://api.bcda.cms.gov/api/v1/jobs/42
Start a Job using _since within the /Patient endpoint Explanation
This operation will start a job for data for all beneficiaries since the selected date: February 13, 2020. Notice that we are seeking data from the /Patient endpoint. This request would behave differently if it was made from the /Group endpoint. In the example, we request the Patient resource type. The steps and format would work similarly for other resource types.
You must provide a _since date in the FHIR format. An access token as well as Accept and Prefer headers are required. The dollar sign ($) before the word "export" in the URL indicates that the endpoint is an action rather than a resource. The format is defined by the FHIR Bulk Data Export spec.
If the request was successful, a 202 Accepted response code will be returned and the response will include a Content-Location header. The value of this header indicates the location to check for job status and outcome. In the example header below, the number 48 in the URL represents the ID of the export job.
Step 3: Check the job status
See Step 3: Check the job status in the Request Data section above.
Step 4: Download the data
See Step 4: Download the data in the Request Data section above.
Requesting using _since with the /Group endpoint
Step 1: Obtain an Access Token
See Authentication and Authorization above.
Step 2: Start a job
Request to Start a job using the _since parameter within the /Group endpoint
GET /api/v1/Group/all/$export?_type=Patient&_since=2020-02-13T08:00:00.000-05:00
Request Headers
Authorization: Bearer {access_token}
Accept: application/fhir+json
Prefer: respond-async
cURL Command using the _since parameter within the /Group endpoint
curl -X GET 'https://api.bcda.cms.gov/api/v1/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 {access_token}"
Response Example: Successful Request
202 Accepted
Response Example: Too Many Requests
429 Too Many Requests
Response Headers
Content-Location: https://api.bcda.cms.gov/api/v1/jobs/42
Start a Job using _since within the /Group endpoint Explanation
This operation will start a job for filtered data for existing beneficiaries since 8PM EST on February 13th, 2020 and all 7 years of historical data for beneficiaries assigned to your organization in the last month. In the example, we request the Patient resource type. The steps and format would work similarly for other resource types.
You must provide the groupID of "all" as well as a _since date in the FHIR format. An access token as well as Accept and Prefer headers are required. The dollar sign ($) before the word "export" in the URL indicates that the endpoint is an action rather than a resource. The format is defined by the FHIR Bulk Data Export spec.
If the request was successful, a 202 Accepted response code will be returned and the response will include a Content-Location header. The value of this header indicates the location to check for job status and outcome. In the example header below, the number 48 in the URL represents the ID of the export job.
Step 3: Check the job status
See Step 3: Check the job status in the Request Data section above.
Step 4: Download the data
See Step 4: Download the data in the Request Data section above.