Skip to main content

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you've safely connected to the .gov website. Share sensitive information only on official, secure websites.

Support

Please cover or label Personally Identifiable Information (PII) as "REDACTED" in the Google Group or email communication.

We're here to help

You can contact us by joining the Google Group or email bcapi@cms.hhs.gov to ask questions and get help. When troubleshooting API requests, please include:

  • whether this is a sandbox or production API request
  • your organization's 5 character entity ID or sandbox data set
  • the API request that's resulting in the problem
  • any response and additional messaging from the API
Join the Google Group

Frequently asked questions

About the API

Terminated and discontinued organizations lose access to the API, including runouts data, the same day their participation in the model ends.

CCLF files are automatically available monthly using 12 flat files, and can be downloaded weekly upon request. BCDA updates adjudicated claims weekly using 3 NDJSON files and partially adjudicated claims data daily using 2 additional files.

Additionally, BCDA is an API that uses the Bulk Fast Healthcare Interoperability Resources (FHIR) format, as required by CMS. Learn more about the differences.

BCDA v1 (STU3) and v2 (R4) differ primarily in their FHIR specification. Version 1 is based on the Blue Button 2.0 Implementation Guide, while version 2 is based on the CARIN Blue Button Implementation Guide.

There are minor differences in the mapping and values of certain data elements. Review the full summary of changes.

Compliance and restrictions

Completely cover or label Personally Identifiable Information (PII) and Protected Health Information (PHI) as “REDACTED” in emails, screenshots, and documents. Ensure any masks are 100% opaque and in a format that supports layers.

Examples of PII and PHI:

  • Medicare Beneficiary Identifier (MBI)
  • Taxpayer Identification Number (TIN)
  • National Provider Identifier (NPI)
  • Social Security Number (SSN)
  • API keys or access credentials (e.g., client ID and secret)
  • authorization or bearer tokens

PII and PHI are often found in API requests or response payloads referenced in:

  • the text of your Google Group posts or emails
  • files attached to your Google Group posts or emails (e.g., XMLs, JSONs)
  • screenshots attached to your Google Group posts or emails

Example of a redacted response:

{
    "taxpayerIdentificationNumber": "REDACTED",
    "nationalProviderIdentifier": "REDACTED"
}

Use caution with 3rd party web-based clients. By sharing your credentials, you may be allowing them to make REST calls on your behalf. This is a serious data privacy and security risk. We recommend using secure REST client tools.

Claims processing timeline

It typically takes 2-4 days after submission to receive partially adjudicated claims data and up to 14 days for adjudicated claims data. Even after adjudication, claims may go through additional processing. BCDA provides the latest updates available for each claim. See a timeline of the claims data process.

According to Section 6404 of the Affordable Care Act, Medicare Fee-for-Service claims must be submitted within 12 months (1 calendar year) of the date of service. Learn about claims submission and approval time frames.

Adjudicated claims data is loaded from the Chronic Conditions Data Warehouse (CCW). Partially adjudicated claims data is loaded from the Fiscal Intermediary Standard System (FISS) and Multi-Carrier System (MCS).

Adjudicated claims data (ExplanationOfBenefit, Patient, Coverage) is updated weekly and partially adjudicated claims data (Claim, ClaimResponse) is updated daily.

You can export data as often as you like, depending on your needs and how often the data is refreshed. We don't recommend exporting data more than once a week for adjudicated claims and once a day for partially adjudicated claims. Use the _since parameter when running jobs to avoid downloading duplicate data.

Troubleshooting

BCDA requires that all production requests come from a registered IP address. Make sure the IP addresses you're using to request data have been added to the Allow List in your model-specific system. Visit Production Access for more details.

A status code of 429 indicates “Too Many Requests.” Wait until the period of time specified in the header has passed before making more requests.

This makes sure your client can adapt without manual intervention, even if the rate-limiting parameters change. Learn more about the 429 status code.

Looking for U.S. government information and services?
Visit USA.gov