Skip to main content
Understanding the Data
Resources for Working with BCDA Data

Version 2 of the Beneficiary Claims Data API (BCDA V2) is now available as of Summer 2021. If you are interested in learning more about how BCDA is changing in this new version of BCDA endpoints, please navigate to the BCDA Version 2 (V2) Data section for more information.


The goal of the Beneficiary Claims Data API (BCDA) is to provide Accountable Care Organizations with the same claims data as they receive via Claim and Claim Line Feed files (CCLFs). The data delivered to you via BCDA should be the same information as the CCLFs, however this data is now delivered in a new format.

BCDA follows the bulk FHIR specification, and provides the same data as the CCLFs using three FHIR resources: Explanation of Benefit (EOB), Patient, and Coverage. This means that your claims data will be delivered through three resource types rather than 12 CCLF files.

  • The Explanation of Benefit resource type provides the same information you’ve previously received in CCLF files 1-7. The EOB files contain 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.
  • The Patient 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.
  • The Coverage resource type provides information about the beneficiaries’ insurance coverage, including information about dual coverage.

BCDA Data Security and Quality

CMS provides Accountable Care Organizations (ACOs) with beneficiary identifiable claims data for preliminarily prospectively and prospectively assigned beneficiaries and other beneficiaries who receive primary care services from an ACO. CMS reminds ACOs that there are limitations to using claims data–whether through CCLF or BCDA–to replicate or validate your ACO’s assigned beneficiaries and expenditure/utilization calculations. CMS provides ACOs with beneficiary-identifiable claims data for the purposes of:

  • Redesigning care processes and coordination of care for ACOs beneficiary populations
  • Enabling practitioners in an ACO to better coordinate and target care strategies toward individual beneficiaries
  • Evaluating the performance of its ACO participants or its ACO providers/suppliers
  • Conducting quality assessment and improvement activities
  • Conducting population-based activities relating to improved health

For the appropriate beneficiaries, the data provided to the ACO through BCDA includes claims for all services covered by Part A (Hospital Insurance) and Part B (Supplemental Medical Insurance) that were provided and processed during the prior month. Claims data also include prescriptions covered by a Part D Prescription Drug Program in which the beneficiary is enrolled. ACOs will be able to retrieve both the CCLF and BCDA claims data concurrently for the foreseeable future; we encourage our users to use both the CCLF and BCDA data sources to compare and contrast the data that is being delivered to your ACO. BCDA Engineers have designed the API to deliver the same claims data as is contained in the CCLFs.

Substance Abuse Codes Not Included

BCDA excludes all claims with substance abuse codes (as required by the Confidentiality of Alcohol and Drug Abuse Patient Records Regulations, 42 CFR Part 2).

BCDA Version 2 (V2) Data

Version 2 of the Beneficiary Claims Data API (BCDA V2) is now available as of Summer 2021. To support industry alignment, BCDA V2 conforms to the FHIR R4 specification and follows the CARIN Implementation Guide. Below is a high level summary of data differences to expect between BCDA V1 (which supports FHIR version STU3) and BCDA V2 (which supports FHIR R4), focusing on the three primary resources provided in the API: ExplanationOfBenefit, Patient and Coverage. In general, the differences for each resources can be grouped into two categories: 1.) differences due to changes in the FHIR specification between STU3 and R4 and 2.) differences due to following a different implementation guide. For more information on specific API-related changes in BCDA V2, please visit the Getting Started Page.

Specification Based Changes

Explanation Of Benefit

The following table summarizes changes to the EOB resource due to changes between versions 3 (STU3) and 4 (R4) of the FHIR specification.

For details, see the FHIR Explanation of Benefit resource page, and select the "R3 Diff" tab under section 13.10.3 "Resource Content"

Change Type Description Examples
Consolidated/Removed Elements Some elements were consolidated and/or removed. For instance, in STU3 there were two elements (Eob.Organization and Eob.Provider) that could represent the party responsible for the claim. In R4, this has been consolidated into one element (Eob.provider)
  • Eob.provider
  • Eob.hospitalization
Added Constraints Fifteen fields were changed from optional to mandatory. Changing the optionality in this context generally has no impact on users consuming this data. A few other minor constraints were added or modified (such as valueset bindings and reference targets)
  • Eob.use
  • Eob.patient
  • Eob.referral
  • Eob.outcome
New Elements Approximately 35 new elements were added to the EOB resource. About 65% of these new elements are child elements of the .addItem property which is not supplied by the BCDA api. Of the remaining 35%, very few, if any, of these elements are populated by BCDA.
  • Eob.priority
  • Eob.preAuthRef
  • Eob.diagnosis.onAdmission
  • Eob.formCode
Renamed Elements A handful of elements were renamed. For users converting from V1 (STU3) to V2 (R4), it is likely that existing parsing/handling logic must be adjusted.
  • Eob.information → Eob.SupportingInfo
  • Eob.careTeamLinkId → Eob.careTeamSequence
  • Eob.diagnosisLinkId → Eob.diagnosisSequence
  • Eob.service → Eob.productOrService


The following table summarizes changes to the Patient resource due to changes between versions 3 (STU3) and 4 (R4) of the FHIR specification. The Patient resource is normative, with a maturity level of 5. In other words, because this resource has been in a mature state for quite some time, the amount of change to this resource in R4 is minimal.

For details, see the FHIR Patient resource page, and select the "R3 Diff" tab under section 8.1.2 "Resource Content"

Change Type Description Examples
Consolidated/Removed Elements Only one element was removed (Patient.animal) which has no effect on the BCDA api.
  • Patient.animal
Constraints A handful of fields are bound to different valuesets. Other minor changes to default value and reference target.
  • Patient.gender
  • Patient.generalPractitioner


The following table summarizes changes to the Coverage resource due to changes between versions 3 (STU3) and 4 (R4) of the FHIR specification.

For details, see the FHIR Coverage resource page, and select the "R3 Diff" tab under section 13.10.3 "Resource Content"

Change Type Description Examples
New Elements Six new elements were added to the Coverage resource. Most of the new elements relate to costToBeneficiary and will not be supplied in BCDA.
  • Coverage.costToBeneficiary
  • Coverage.costToBeneficiary.type
Consolidated/Removed Elements The Coverage.grouping element was removed. The equivalent element in R4 is Coverage.class. This element is provided in the API, so any user converting from V1 to V2 will be required to make minor changes to their parsing/handling logic.
  • Coverage.grouping
Added Constraints A few changes to make certain elements mandatory. Generally this has little or no impact to any users consuming this data.
  • Coverage.beneficiary
  • Coverage.payor

Implementation Guide Based Changes

Whereas version 1 of the API was based on the Blue Button 2.0 Implementation Guide, version 2 is based on the CARIN CDPDE Implementation Guide. Subsequently, there will be minor changes to the mapping and values of certain data elements based on conformance to the CARIN IG. For instance, slicing/discriminator rules can be different, and some valuesets will be bound to CARIN or HL7 valusets instead of BlueButton. As an example, Patient.identifier.type in V2 is bound to As another example, Eob.Type is bound to and the associated value will be one of the codes in that valueset.

The BCDA Data Dictionary will provide specifics on things like mappings, discriminators, valueset bindings and extensions.

BCDA Data Dictionary

The CCLF to BCDA Data Dictionary is provided to BCDA users to facilitate their data mapping process.

The Data Dictionary was last updated in January 2022.

Because BCDA delivers data in the FHIR format, data field names will be different from previous data fields delivered through CCLFs. In this spreadsheet, BCDA has provided a crosswalk between all CCLF data fields and their new locations within BCDA Claims files. The Data Dictionary also provides supplementary context for each of the CCLF/BCDA data fields, including:

  • Claim Field Names and Descriptions
  • Data Type
  • Format

Some data fields have not yet been mapped from CCLFs to BCDA.

The Beneficiary FHIR Data Server (BFD) API team is working hard to map all of the CCLF fields in the near future. The fields that have not been mapped yet are shaded in grey. Other fields will also not be mapped to BCDA. Additional information for unmapped fields can be found in the notes column of the BCDA Data Dictionary.

Sample BCDA Files

In order to aid in users' understanding of BCDA file data and structure, BCDA provides sample Explanation of Benefit, Patient, and Coverage FHIR resource files to download. These files contain synthetic data, but the structure and contents of the files are similar to the actual files you will be pulling and downloading from the BCDA production environment. These files contain data for only 100 synthetic beneficiaries. Please visit the Getting Started page for a more in-depth look at the synthetic data options available to you through the BCDA Sandbox environment.

  1. Explanation of Benefit
  2. Patient
  3. Coverage