Skip to main content
Beneficiary Claims Data API
Beneficiary Claims Data API

Advanced Sandbox User Guide

A technical guide to getting set up in BCDA and retrieving data from the API.

User Guide

The Beneficiary Claims Data API (BCDA) enables Accountable Care Organizations (ACOs) to retrieve claims data for their Medicare beneficiaries. This includes 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.

This guide serves as a starting point for users to begin working with the API. Comprehensive Swagger documentation about all BCDA endpoints is also available.

Note: if this documentation is a little too in-depth, you may want to start with our guide to getting started for an overview of APIs and a gentler walk-through.

Authentication and Authorization

The Beneficiary Claims Data API is currently accessible as an open sandbox environment, which returns sample NDJSON files with synthetic beneficiary data. You can use the generic credentials below to view our implementation of the API and learn the shape of the data before working with production files that include PII and PHI. There is no beneficiary PII or PHI in the files you can access via the sandbox.

We have provided five sets of synthetic credentials for use in the sandbox, corresponding to various amounts of synthetic beneficiaries. 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.

Client ID:
3841c594-a8c0-41e5-98cc-38bb45360d3c
Client Secret:
f9780d323588f1cdfc3e63e95a8cbdcdd47602ff48a537b51dc5d7834bf466416a716bd4508e904a

Client ID:
d5f83f74-6c55-4f1e-9d16-0022688171ba
Client Secret:
01c23cf3f31f82a5c2dcef5136a8eaa32959158351f4e28aaec5fc6550cb2a5b5d112c5b8aacc434

Client ID:
8c75a6f6-02b9-4a47-96c1-0bd6efd4b5e3
Client Secret:
e1c920141c4aca6b8f726fa8aa0f7b55e095fd1ea3368a5f24b3636fdc907f113d6677977c7259dd

Client ID:
f268a8c6-8a29-4d2b-8b92-263dc775750d
Client Secret:
78ed083ad8e49475f36d04153649012b92c363a538ac97beaf0f7900403989581fc35324baa31e36

Client ID:
6152afb4-c555-46e4-93de-fa16a441d643
Client Secret:
1ace5a0e9fdf0c3d713e8c029269eacd024732ccd59e2cf283374e0f8dc93b34429d71b77e55b9a2

To get a token that can be used with protected endpoints, POST the credentials you’ve selected using Basic Authentication to https://sandbox.bcda.cms.gov/auth/token.

Authentication Walkthrough

Request

POST /auth/token

Headers

  • Accept: application/json
  • Authorization: <Encoded Basic authentication>

cURL commands

You can choose one of two cURL commands to use.

Option 1, which requires base-64 encoding be performed on your clientId and secret

With this option, 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 the following cURL command, we have concatenated the base64 encoding of the ‘Client ID : Secret’ as the argument to the -H flag.

Example:

curl -d '' -X POST "https://sandbox.bcda.cms.gov/auth/token" -H "accept: application/json" -H "authorization: Basic Mzg0MWM1OTQtYThjMC00MWU1LTk4Y2MtMzhiYjQ1MzYwZDNjOm\
Y5NzgwZDMyMzU4OGYxY2RmYzNlNjNlOTVhOGNiZGNkZDQ3NjAy\
ZmY0OGE1MzdiNTFkYzVkNzgzNGJmNDY2NDE2YTcxNmJkNDUwOGU5MDRh"

Option 2, which takes advantage of cURL’s ability to base-64 encode your clientId and secret

With this option, 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.

Example:

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

Response

You will receive a 200 OK response and an access token if your credentials were accepted.

{
  “access_token”: “eyJhbGciOiJSUzUxMiIsInR5c ....”,
  ”token_type”:“bearer”
}

Token string abbreviated for readability.

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.

Environment

The examples below include cURL commands, but may be followed using any tool that can make HTTP GET requests with headers, such as Postman.

Examples

Generate Client Code

An OpenAPI v3 JSON schema file, which represents the service capabilities of the API, can be accessed from our Swagger page. This file can be used to generate client code to interact with BCDA. There are various tools that can be used to generate client code from an OpenAPI v3 JSON schema file; one of which is Swagger Editor, which can generate code in dozens of different programming languages and also produces a README describing usage of the newly generated client code.

Sample Code

BCDA provides test code written in Golang in our GitHub instance that you can use to set up your system to work with the API. Sample invocation is below:

go run bcda_client.go -host=$HOSTNAME -clientID=$CLIENT_ID -clientSecret=$CLIENT_SECRET -endpoint=Patient -resourceType=ExplanationOfBenefit

Below we break down step by step each of the actions provided in the test client.

Examples are shown as requests to the BCDA sandbox environment.

BCDA Metadata

Metadata about the Beneficiary Claims Data API is available as a FHIR CapabilityStatement resource. A token is not required to access this information.

1. Request the metadata

Request

GET /api/v1/metadata

cURL command

curl https://sandbox.bcda.cms.gov/api/v1/metadata

Response

{
  "resourceType": "CapabilityStatement",
  "status": "active",
  "date": "2019-12-09",
  "publisher": "Centers for Medicare & Medicaid Services",
  "kind": "capability",
  "instantiates": [
    "https://fhir.backend.bluebutton.hhsdevcloud.us/baseDstu3/metadata/"
  ],
  "software": {
    "name": "Beneficiary Claims Data API",
    "version": "latest",
    "releaseDate": "2019-12-09"
  },
  "implementation": {
    "url": "https://sandbox.bcda.cms.gov"
  },
  "fhirVersion": "3.0.1",
  "acceptUnknown": "extensions",
  "format": [
    "application/json",
    "application/fhir+json"
  ],
  "rest": [
    {
      "mode": "server",
      "security": {
        "cors": true,
        "service": [
          {
            "coding": [
              {
                "system": "http://hl7.org/fhir/ValueSet/restful-security-service",
                "code": "OAuth",
                "display": "OAuth"
              }
            ],
            "text": "OAuth"
          },
          {
            "coding": [
              {
                "system": "http://hl7.org/fhir/ValueSet/restful-security-service",
                "code": "SMART-on-FHIR",
                "display": "SMART-on-FHIR"
              }
            ],
            "text": "SMART-on-FHIR"
          }
        ]
      },
      "interaction": [
        {
          "code": "batch"
        },
        {
          "code": "search-system"
        }
      ],
      "operation": [
        {
          "name": "export",
          "definition": {
            "reference": "https://sandbox.bcda.cms.gov/api/v1/Patient/$export"
          }
        },
        {
          "name": "jobs",
          "definition": {
            "reference": "https://sandbox.bcda.cms.gov/api/v1/jobs/[jobId]"
          }
        },
        {
          "name": "metadata",
          "definition": {
            "reference": "https://sandbox.bcda.cms.gov/api/v1/metadata"
          }
        },
        {
          "name": "version",
          "definition": {
            "reference": "https://sandbox.bcda.cms.gov/_version"
          }
        },
        {
          "name": "data",
          "definition": {
            "reference": "https://sandbox.bcda.cms.gov/data/[jobID]/[random_UUID].ndjson"
          }
        }
      ]
    }
  ]
}

Beneficiary Data from the Patient endpoint

The FHIR Resource Types Offered through the API

  • ExplanationOfBenefit: this 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.
  • Patient: the information in this 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.
  • Coverage: the information in this 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).

The BCDA/bulk FHIR Endpoints

  • Patient Endpoint: Request ExplanationOfBenefit, Patient, and/or Coverage data for all beneficiaries. Filter data by date using the _since parameter.
  • Group Endpoint: Request ExplanationOfBenefit, Patient, and/or Coverage data for all beneficiaries. Filter data by date using the _since parameter.
    • Note: If you filter data using _since within the /Group endpoint, you will receive claims data since the date of your choice for existing beneficiaries AND you will also receive 7 years of historical data for all beneficiaries that are newly attributed to your ACO. Learn more about how to retrieve the most current beneficiary claims data for existing beneficiaries AND historical data for newly attributed beneficiaries.

Requesting Current and Historical Data for all Beneficiaries

You can make a request to the endpoints for all three Resource Types at once, one at a time, or a combination of any two together by specifying the resource type of interest (separated by commas) in the _type query parameter for both the /Patient and /Group endpoints.

In the example below, we have provided cURL statements to retrieve any combination of the three resource types from the /Patient endpoint. Relevant cURL statements can be altered to retrieve any combination of resource types from the /Group endpoint as needed.

1. Obtain an access token

See Authentication and Authorization above.

2. Initiate an export job

Request all three resource types from the /Patient endpoint.

GET /api/v1/Patient/$export

Request any two resource types from the /Patient endpoint.

GET /api/v1/Patient/$export?_type=ExplanationOfBenefit,Patient

Request a single resource type from the /Patient endpoint.

GET /api/v1/Patient/$export?_type=ExplanationOfBenefit

GET /api/v1/Patient/$export?_type=Patient

GET /api/v1/Patient/$export?_type=Coverage

To start a data export job, a GET request is made to the /Patient endpoint including the desired resource types in the _type query parameter. If you are requesting multiple resource types, they are separated by commas. 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.

Headers

  • Authorization: Bearer {token}
  • Accept: application/fhir+json
  • Prefer: respond-async

cURL command

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

Response

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.

Headers

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

3. Check the status of the export job

Request

GET https://sandbox.bcda.cms.gov/api/v1/jobs/42 Using the Content-Location header value from the Patient data export response, you can check the status of the export job. The status will change from 202 Accepted to 200 OK when the export job is complete and the data is ready to be downloaded.

Headers

  • Authorization: Bearer {token}

cURL Command

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

Responses

202 Accepted indicates that the job is processing. Headers will include X-Progress: In Progress (The X-Progress header contains text indicating the job’s status in BCDA’s workflow. When the status is In Progress, an estimated progress percentage is also included.) 200 OK indicates that the job is complete.

Below is an example of the format of the response body.

{
  "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
}

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.

4. Retrieve NDJSON output file(s)

To obtain the exported data, make a GET request to the output URLs in the job status response when the job reaches the Completed (200 OK) state. The data will be presented as separate NDJSON files of ExplanationOfBenefit, Patient, Coverage and resources.

Request

GET https://sandbox.bcda.cms.gov/data/42/afd22dfa-c239-4063-8882-eb2712f9f638.ndjson

Headers

  • Authorization: Bearer {token}

cURL command

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

Response

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.

Filtering Your Data with _since

The _since parameter grants you the ability 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. BCDA will then produce claims data from the bulk data endpoints that have been loaded since the entered date.

Note: The use of _since differs significantly between the /Patient and /Group endpoints:

If you want to request only the most recent beneficiary claims data, you can use the _since parameter with the /Patient endpoint.

If you want to receive filtered data by the date of your choice for existing beneficiaries and also 7 years of historical data for all beneficiaries that are newly attributed to your ACO in the same API call, you can use the _since parameter (in combination with the ‘all’ identifier) with the /Group endpoint.

For more information on _since, please consult the FHIR standard on query parameters.

Request Historical Data Before Using _since

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 endpoint 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. Use the transactionTime from your last bulk data request set as the _since date.

Note: 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.

Date and Timezone Formatting

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

FHIR Datatypes page.

Retrieve only the most current beneficiary claims data

The /Patient endpoint allows users to filter data by a selected _since date. The request will return data for all beneficiaries since that selected date. In the example below, we are seeking data from the /Patient endpoint for the Patient resource type since 8PM EST on February 13th, 2020. The steps and format would work similarly for other resource types.

1. Obtain an access token

See Authentication and Authorization above.

2. Initiate an export job

Request

GET /api/v1/Patient/$export?_type=Patient&_since=2020-02-13T08:00:00.000-05:00

Headers

  • Authorization: Bearer {token}
  • Accept: application/fhir+json
  • Prefer: respond-async

cURL command

curl -X GET "https://sandbox.bcda.cms.gov/api/v1/Patient/$export?_type=Patient&_since=2020-02-13T08:00:00.000-05:00
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/fhir+json' \
-H 'Prefer: respond-async'

3. Check the status of the export job

Instructions for checking the job status have been detailed in previous sections. See checking the status of the export job above.

For ease of use, we have listed the cURL commands for the operations below. The job ID (48) will be different for your job.

cURL command

curl -v https://sandbox.bcda.cms.gov/api/v1/jobs/48 \
-H 'Authorization: Bearer {token}'

4. Retrieve the NDJSON output file

Instructions for retrieving the output file have been detailed in previous sections. See retrieving NDJSON output file(s) above.

For ease of use, we have listed the cURL commands for the operation below. The job ID (48) and file name for the NDJSON file (4e2cd98c-4746-4138-872b-24778c000b02.ndjson) will be different for your job.

cURL command

curl https://sandbox.bcda.cms.gov/data/48/4e2cd98c-4746-4138-872b-24778c000b02.ndjson \
-H 'Authorization: Bearer {token}'

Retrieve the most current beneficiary claims data for existing beneficiaries AND historical data for newly attributed beneficiaries

This section outlines the steps to make a request for both incremental claims data for existing beneficiaries and 7 years of historical data for beneficiaries that are newly attributed to your ACO within one API call.

You will need to make a request to the /Group endpoint using the /Group/all identifier as well as the _since parameter. The “all” identifier designates that you would like data for “all beneficiaries associated with your ACO”. At this time, all is the only group identifier that BCDA offers.

Note: 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.

In the example below, we are seeking data from the /Group endpoint for the Patient resource type since 8PM EST on February 13th, 2020. The steps and format would work similarly for other resource types.

1. Obtain an access token

See Authentication and Authorization above.

2. Initiate an export job

Request

GET /api/v1/Group/all/$export?_type=Patient&_since=2020-02-13T08:00:00.000-05:00

To start a data export job for filtered data from existing beneficiaries since 8PM EST on February 13th, 2020 and all data for newly assigned beneficiaries that month, a GET request is made to the /Group endpoint. The groupID of “all” is provided as well as a _since date in the correct 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.

Headers

  • Authorization: Bearer {token}
  • Accept: application/fhir+json
  • Prefer: respond-asnc

cURL command

curl -X GET "https://sandbox.bcda.cms.gov/api/v1/Group/all/$export?_type=Patient&_since=2020-02-13T08:00:00.000-05:00
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/fhir+json' \
-H 'Prefer: respond-async'

Response

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.

Headers

  • Content-Location: https://sandbox.bcda.cms.gov/api/v1/jobs/48

3. Check the status of the export job

Instructions for checking the job status have been detailed in previous sections. See checking the status of the export job above.

For ease of use, we have listed the cURL commands for the operations below. The job ID (48) will be different for your job.

cURL command

curl -v https://sandbox.bcda.cms.gov/api/v1/jobs/48 \
-H 'Authorization: Bearer {token}'

4. Retrieve the NDJSON output file

Instructions for retrieving the output file have been detailed in previous sections. See retrieving NDJSON output file(s) above.

For ease of use, we have listed the cURL commands for the operation below. The job ID (48) and file name for the NDJSON file (4e2cd98c-4746-4138-872b-24778c000b02.ndjson) will be different for your job.

cURL command

curl https://sandbox.bcda.cms.gov/data/48/4e2cd98c-4746-4138-872b-24778c000b02.ndjson
-H 'Authorization: Bearer {token}'

Have questions?

The BCDA Google Group is the best place to get your questions answered by the BCDA team. In this community you can sign up for feedback session opportunities, get answers to your questions, share your feedback and ideas, and get updates on the project.

Back to top