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:

Encoded Basic authentication:

Basic Mzg0MWM1OTQtYThjMC00MWU1LTk4Y2MtMzhiYjQ1MzYwZDNjOmY5NzgwZDMyMzU4OGYxY2RmYzNlNjNlOTVhOGNiZGNkZDQ3NjAyZmY0OGE1MzdiNTFkYzVkNzgzNGJmNDY2NDE2YTcxNmJkNDUwOGU5MDRh

Request

POST /auth/token

Headers

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

cURL command

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

Response

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

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

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

BCDA provides data via the Patient endpoint related to three Resource Types:

  • Explanation of Benefit: this Resource Type provides the same information you’ve previously received 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 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.
  • 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).

You can make a request to the Patient endpoint for all three Resource Types at once, one at a time, or a combination of any two together. This section describes a request for all three Resource Types; information about requesting one at a time follows below.

1. Obtain an access token

See Authentication and Authorization above.

2. Initiate an export job

Request

GET /api/v1/Patient/$export

To start a data export job for all three Resource Types, a GET request is made to the Patient endpoint. 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, and Coverage 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.

Examples of data from each Resource Type are available in the guide to working with BCDA data.

Requesting Beneficiary Explanation of Benefit Data only

The Explanation of Benefit file provides the same information you’ve previously received 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.

1. Obtain an access token

See Authentication and Authorization above.

2. Initiate an export job

Request

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

To start an explanation of benefit data export job, a GET request is made to the ExplanationOfBenefit endpoint. 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?_type=ExplanationOfBenefit \
-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 43 in the URL represents the ID of the export job.

Headers

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

3. Check the status of the export job

Request

GET https://sandbox.bcda.cms.gov/api/v1/jobs/43

Using the Content-Location header value from the ExplanationOfBenefit 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 -v https://sandbox.bcda.cms.gov/api/v1/jobs/43 \
-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-09T21:20:57.254518Z",
  "request": "https://sandbox.bcda.cms.gov/api/v1/Patient/$export?_type=ExplanationOfBenefit",
  "requiresAccessToken": true,
  "output": [
    {
      "type": "ExplanationOfBenefit",
      "url": "https://sandbox.bcda.cms.gov/data/43/472483a6-3aad-422c-beed-694344570548.ndjson"
    }
  ],
  "error": [],
  "JobID": 43
}

Claims data can be found at the URLs within the output field. The number 43 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 explanation of benefit 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 NDJSON files of ExplanationOfBenefit resources.

Request

GET https://sandbox.bcda.cms.gov/data/43/472483a6-3aad-422c-beed-694344570548.ndjson

Headers

  • Authorization: Bearer {token}

cURL command

curl https://sandbox.bcda.cms.gov/data/43/472483a6-3aad-422c-beed-694344570548.ndjson \
-H 'Authorization: Bearer {token}'

Response

The response will be the requested data as FHIR ExplanationOfBenefit resources in NDJSON format.

An example of one such resource is available in the guide to working with BCDA data.

Requesting Beneficiary Patient Data only

The Patient file 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.

Note the difference between the Patient endpoint and Patient resource type: the Patient endpoint can return data from any or all of the three resource types. The Patient resource type within the Patient endpoint only returns the information described above.

The process of retrieving Patient data from the Patient endpoint is very similar to exporting Explanation of Benefit data.

1. Obtain an access token

See Authentication and Authorization above.

2. Initiate an export job

Request

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

To start a Patient data export job, a GET request is made to the Patient export endpoint for the Patient resource type. 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 -v https://sandbox.bcda.cms.gov/api/v1/Patient/$export?_type=Patient" \
-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 44 in the URL represents the ID of the export job.

Headers

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

3. Check the status of the export job

Request

GET https://sandbox.bcda.cms.gov/api/v1/jobs/44

Using the Content-Location header value from the Patient resource type 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 -v https://sandbox.bcda.cms.gov/api/v1/jobs/44 \
-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-09T21:42:54.055223Z",
  "request": "https://sandbox.bcda.cms.gov/api/v1/Patient/$export?_type=Patient",
  "requiresAccessToken": true,
  "output": [
    {
      "type": "Patient",
      "url": "https://sandbox.bcda.cms.gov/data/44/4e2cd98c-4746-4138-872b-24778c000b02.ndjson"
    }
  ],
  "error": [],
  "JobID": 44
}

Patient demographic data can be found at the URLs within the output field. The number 44 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 patient 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 an NDJSON file of Patient resources.

Request

GET https://sandbox.bcda.cms.gov/data/44/4e2cd98c-4746-4138-872b-24778c000b02.ndjson

Headers

  • Authorization: Bearer {token}

cURL command

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

Response

The response will be the requested data as FHIR Patient resources in NDJSON format.

An example of one such resource is available in the guide to working with BCDA data.

Requesting Beneficiary Coverage Data Only

Coverage data 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 process of retrieving coverage data is very similar to all of the other exporting operations supported by this API.

1. Obtain an access token

See Authentication and Authorization above.

2. Initiate an export job

Request

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

To start a coverage data export job, a GET request is made to the Patient endpoint for the Coverage resource type. 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 -v https://sandbox.bcda.cms.gov/api/v1/Patient/$export?_type=Coverage \
-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 45 in the URL represents the ID of the export job.

Headers

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

3. Check the status of the export job

Request

GET https://sandbox.bcda.cms.gov/api/v1/jobs/45

Using the Content-Location header value from the Coverage 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 -v https://sandbox.bcda.cms.gov/api/v1/jobs/45 \
-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-09T21:51:58.182108Z",
  "request": "https://sandbox.bcda.cms.gov/api/v1/Patient/$export?_type=Coverage",
  "requiresAccessToken": true,
  "output": [
    {
      "type": "Coverage",
      "url": "https://sandbox.bcda.cms.gov/data/45/99dbc86f-74e5-4553-88a9-af3e718cb72b.ndjson"
    }
  ],
  "error": [],
  "JobID": 45
}

Coverage data can be found at the URLs within the output field. The number 45 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 coverage 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 an NDJSON file of Coverage resources.

Request

GET https://sandbox.bcda.cms.gov/data/45/99dbc86f-74e5-4553-88a9-af3e718cb72b.ndjson

Headers

  • Authorization: Bearer {token}

cURL command

curl https://sandbox.bcda.cms.gov/data/45/99dbc86f-74e5-4553-88a9-af3e718cb72b.ndjson \
-H 'Authorization: Bearer {token}'

Response

The response will be the requested data as FHIR Coverage resources in NDJSON format.

An example of one such resource is available in the guide to working with BCDA data.

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