Skip to main content
Building Your Application
Using BCDA in Production

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.

Authorization and Authentication

To complete any other operations with the API, you will need to be authorized. All SSP ACOs are currently eligible for authorization through the ACO-MS system.

Obtain your BCDA Credentials

In production, the Beneficiary Claims Data API protects its endpoints with OAuth2 access tokens.

Your credentials are protected data.

Please treat your credentials like protected data: store them safely and securely.

SSP-ACOs Gain Access to BCDA through ACO-MS

Representatives of Shared Savings Program 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.

Obtain your Access Token

Currently, access tokens expire after twenty minutes. To illustrate this cycle, we’ll use the published open sandbox credentials for Extra-Small ACOs. 

Example Client ID (Extra-Small ACOs):
3841c594-a8c0-41e5-98cc-38bb45360d3c

Example Client Secret (Extra-Small ACOs):
F9780d323588f1cdfc3e63e95a8cbdcdd47602ff48a537b51dc5d7834bf466416a716bd4508e904a

These credentials do not work in production.

The sample credentials above will not work in the production environment. For production data, follow along using the credentials your ACO was issued.

Submit your credentials to receive an Access Token

You will need to submit the Client ID and the Client Secret issued to your organization using a POST request. You will receive an Access Token that allows access to the API for 20 minutes before expiring.

Access Token Request 

POST /auth/token

Access Token cURL Command

cURL Option 1: This cURL command requires separate base-64 encryption. We have concatenated the base64 encoding of the ‘Client ID : Secret’ as the argument to the -H flag. 

curl -d '' -X POST 'https://api.bcda.cms.gov/auth/token' \
	-H "accept: application/json" \
	-H "authorization: Basic Mzg0MWM1OTQtYThjMC00MWU1Tk4Y2MtMzhiYjQ1MzYwZDNjOmY5NzgwZDMyMzU4OGYxY2RmYzNlNjNlOTVhOGNiZGNkZDQ3NjAyZmY0OGE1MzdiNTFkYzVkNzgzNGJmNDY2NDE2YTcxNmJkNDUwOGU5MDRh"

cURL Option 2: This cURL command innately encrypts your credentials with base-64 encryption 

curl -d '' -X POST 'https://api.bcda.cms.gov/auth/token' \
	--user 3841c594-a8c0-41e5-98cc-38bb45360d3c:f9780d323588f1cdfc3e63e95a8cbdcdd47602ff48a537b51dc5d7834bf466416a716bd4508e904a \
	-H "accept: application/json"

Access Token Response Example

The token string below has been abbreviated for readability. 

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

Access Token Response Headers

access_token: The full text string will serve as your access token. token_type: A fixed value as “bearer”.

Access Token Explanation

In cURL Option 1, you must base-64 encode the clientId and secret. Once that is performed, the encoded credentials can be passed to cURL as a header with the form: authorization: Basic [base64-encoded clientId:secret]

In cURL Option 2, the user can take advantage of cURL’s built-in ability to base-64 encode the clientId and secret, and request and receive their token in a single step. If your operation succeeds, you will receive a 202 response with your access token as a header. You will receive a 401 Unauthorized response if your credentials are invalid or if your token has expired. No additional information is returned with a 401 response. When you receive a 401 response for a token you were just using successfully, you should request a new access token as outlined above.

Set your Access Token as a Bearer Token

In all of your requests, set your access token as the Bearer token. The Bearer token is included in the header of any requests as follows: 

Authorization: Bearer {access_token}

Notice that the word “Bearer” must be included with a capital B and followed by a space.

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:

  1. Request all three Resource Types at once
  2. Request any two Resource Types
  3. Request a single Resource Type

Steps

Each request will follow the same four step process:

  1. Obtain an access token
  2. Start a job to acquire data
  3. Check the job status
  4. Download the data

Request All Three Resource Types

The examples below are for the /Patient endpoint.

We have provided a few examples below in which we show retrieving only certain resource types from the /Patient endpoint. The request and cURL statements can be altered to retrieve any combination of resource types and resource types from the /Group endpoint as needed.

Step 1: Obtain an Access Token

See Authentication and Authorization above.

Step 2: Start a job to acquire data

Requests to start a job

  1. GET /api/v1/Patient/$export
  2. GET /api/v1/Patient/$export?_type=ExplanationOfBenefit,Patient
  3. 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

  1. 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}"
  2. 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}"
  3. 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:

  1. All three resource types
  2. Any two resource types (we use EOB and Patient as an example)
  3. 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

  1. Explanation of Benefit
  2. Patient
  3. Coverage

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).

Files expire after 24 hours.

You will need to download the data file within 24 hours of starting the request to a specific endpoint. Otherwise, the files will expire and you will need to restart the job.

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.

Cancelling a Job

Step 1: Obtain an Access Token

See Authentication and Authorization above.

Step 2: Send a Request to Cancel a Job

Request to Cancel a Job

DELETE /api/v1/jobs/{jobId}

Request Headers

Authorization: Bearer {access_token}

Cancel a Job Explanation

This operation will send a request to cancel any active job. You may want to do this for very long-running jobs or to preserve resources.

If the request is successful, the active job will be terminated and a 202 response will be returned.

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 may also want to target specific data, such as your runouts data.

To reduce file size, use the _since parameter with 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.

To obtain claims runout data, use the 'runout' parameter with the /Group endpoint, which returns data for beneficiaries who were attributed to your ACO the previous year but not the current year. These claims will have a service date no later than December 31 of the previous year.

Before using _since, download all of your data.

Before using _since for the first time, we recommend that you run an unfiltered request (without using _since) to all resource types on the /Patient or /Group endpoints in order to retrieve all historical data for your ACO's associated beneficiaries. You only need to do this once.

On subsequent calls you can begin retrieving incremental claims data for your beneficiaries using _since. We suggest using the transactionTime from your last bulk data request as the _since date.

List of Requests

You can make a few different filtered requests for data:

  1. Request the most recent data for all beneficiaries: Use _since within the /Patient endpoint
  2. Request the most recent data for all beneficiaries AND historical data for newly added beneficiaries: Use _since within the /Group endpoint
  3. Request runouts data: Use 'runout' within the /Group endpoint

Steps

Each request will follow the same four step process as an unfiltered request:

  1. Obtain an access token
  2. Start a job to acquire data (you will input the _since parameter here)
  3. Check the job status
  4. 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.

When using _since, 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.

Be wary of requesting data from before 02-12-2020

Due to limitations in the Beneficiary FHIR Data (BFD) Server, data from before 02-12-2020 is marked with the arbitrary lastUpdated date of 01-01-2020. If you input dates between 01-01-2020 and 02-11-2020 in the _since parameter, you will receive all historical data for your beneficiaries. Data loads from 02-12-2020 onwards have been marked with accurate dates.

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.

Attribution data is only updated once per month.

While most claims data is updated on a weekly cadence (and we encourage you to retrieve your ACO's claims data weekly), ACO attribution is only updated one time per month, so you will only be able to retrieve historical claims data for newly attributed beneficiaries once per month. Additional calls will only yield duplicative data for these newly attributed beneficiaries.

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.

Request runouts data 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

  1. GET /api/v1/Group/runout/$export
  2. GET /api/v1/Group/runout/$export?_type=ExplanationOfBenefit,Patient
  3. 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

  1. 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}"
  2. 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}"
  3. 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 Headers

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

Start a Job using 'runout' with /Group 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:

  1. All three resource types
  2. Any two resource types (we use EOB and Patient as an example)
  3. 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'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

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.