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 provide an example response from the API.

BCDA V2 conforms to the FHIR R4 specification and follows the CARIN Implementation Guide for industry alignment. BCDA will support all functionality for both V1 and V2 of the API for the foreseeable future; however, upgrading to BCDA’s V2 API ensures your product is aligned with the latest industry standards. For more information on BCDA V2, please visit the CMS V2 API FAQ Documentation. For more information on how BCDA data will change in BCDA V2, please visit the BCDA Understanding the Data page.

How will BCDA V2 change the way I interact with the BCDA API?

BCDA V2 supports the same functionality as V1 API endpoints in both the Sandbox and Production API environments. If you wish to transition your implementation to utilize BCDA V2 endpoints instead of V1, replace ‘v1’ in API call URLs with ‘v2’. Here is an example:

curl -X GET 'https://api.bcda.cms.gov/api/v2/Group/all/$export' \
-H "accept: application/fhir+json" \
-H "Prefer: respond-async" \
-H "Authorization: Bearer {access_token}" \
-v

curl -X GET 'https://api.bcda.cms.gov/api/v1/Group/all/$export' \
-H "accept: application/fhir+json" \
-H "Prefer: respond-async" \
-H "Authorization: Bearer {access_token}" \
-v

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 Examples

Metadata Request

GET /api/v2/metadata

Metadata cURL Command

curl https://api.bcda.cms.gov/api/v2/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 release version and the FHIR version of the BCDA API that is currently active and other useful information.

To complete any other operations with the API, you will need to be authorized.

All model entities – Accountable Care Organizations (ACO), Direct Contracting Entities (DCE), Kidney Care Entities (KCE), and Kidney Care First (KCF) Entities – are eligible for authorization through their model-specific system.

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/v2/Group/all/$export

2. GET /api/v2/Group/all/$export?_type=ExplanationOfBenefit,Patient

3. GET /api/v2/Group/all/$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/v2/Group/all/$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/v2/Group/all/$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/v2/Group/all/$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/v2/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/v2/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/v2/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/v2/Group/all/$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).

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.