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.

How to Migrate to v3 New

Migration overview

This guide helps you migrate from BCDA v1/v2 to v3. Key changes include:

  • New endpoint URL structure
  • Unified ExplanationOfBenefit resource for all claims
  • Updated extension and code system URLs
  • Different resource IDs requiring new matching strategies

Learn how BCDA v3 supports better outcomes in our introduction to v3.

Changes to BCDA in v3

If you are currently using BCDA v1 or BCDA v2, there are changes to the API and FHIR Resources you need to be aware of in v3:

  • There is a new v3 endpoint: https://api.bcda.cms.gov/api/v3/
  • Partially adjudicated claims1 will be represented as ExplanationOfBenefit (EOB) FHIR resources in v3, instead of Claim/ClaimResponse in v2
  • There will be new Extension and Code System URLs to reference
  • Resource IDs are different between versions

1Medical claims that have been submitted but not fully processed and paid by Medicare.

v3 Data Dictionary

Download the BCDA v3 Data Dictionary to learn about:

  • Updated information on resource type and claim field names
  • Updated mappings between CCLF and BCDA data
  • New data available in v3

Requesting data from new v3 endpoints

Point your app to v3 instead of v2

BCDA v3 will be located at the same domain as v1 and v2. However, it will have new endpoints for metadata requests and the Group and Patient $export operations. BCDA v3 will still support the Bulk Data FHIR Implementation Guide. If you are currently connected to BCDA v1 or v2 endpoints, you can migrate to BCDA v3 by making the following changes.

Point your app to v3 instead of v2 to connect to the new endpoint, complete the steps to export the data, check the job status, read the JSON manifest, and download the files.

  • v2 Patient $export operation: 
GET /api/v2/Group/all/$export
  • v3 Patient $export operation: 
GET /api/v3/Group/all/$export

The /auth and /data URLs will remain the same between versions. You won’t need to make any changes to how you request a token or download files.

Changes to claims representation

In BCDA v3, claims data are still returned in FHIR R4 format, but there are changes to the Patient, Coverage, and ExplanationOfBenefit resources. These changes include:

Refer to the v3 Data Dictionary for a list of v3 supported data elements.

Changes to partially adjudicated claims

BCDA v2 represents fully adjudicated claims by the ExplanationOfBenefit FHIR resource and partially adjudicated claims by the Claim and ClaimResponse resources.

BCDA v3 represents all claims (fully and partially adjudicated) with the ExplanationOfBenefit resource.

  • v2 - Claim/ClaimResponse resource
  • v3 - ExplanationOfBenefit resource

This change in v3 lets you compare claims at different stages in the adjudication process without mapping between resource types.

Exporting claims based on adjudication status with v3

If you make requests for Claim and/or ClaimResponse resources using the _type parameter in v2, you’ll need to update those requests in v3.

How it works in v2

In BCDA v2 you exported claims based on adjudication status using the _type parameter, and passing the appropriate resource types (Claim, ClaimResponse for partially adjudicated claims and ExplanationOfBenefit for fully adjudicated claims) as the parameter value:

  • v2 $export for only partially adjudicated claims:
GET /api/v2/Patient/$export?_type=Claim,ClaimResponse
  • v2 $export for only fully adjudicated claims:
GET /api/v2/Patient/$export?_type=ExplanationOfBenefit

In v2, BCDA differentiates “partially adjudicated” from “fully adjudicated” claims based on the data source rather than the claim status. BCDA’s partially adjudicated data (Claim and ClaimResponse resources) are populated with data from the Medicare Shared Systems which often includes data for claims that had been fully processed and paid.

How it works in v3

We’ve extended the API with the _typeFilter parameter to filter export data more granularly. Because all claims in v3 are represented by the same resource type (ExplanationOfBenefit), use this parameter to specify the System-Type _tag, recreating your v2 filtering logic.

Remember when using the _typeFilter parameter:

  1. The _typeFilter parameter value must be URL-encoded
  2. The _tag subquery parameter requires a token in the form system|code
GET /api/v3/Patient/$export
  ?_type=
    ExplanationOfBenefit
  &_typeFilter=
    ExplanationOfBenefit%3F_tag%3Dhttps%3A%2F%2Fbluebutton.cms.gov%2Ffhir%2FCodeSystem%2FSystem-Type%7CSharedSystem

If you received ExplanationOfBenefit, Claim, and ClaimResponse resources in v2, you received all claims.

In v3, specify all System-Type codes:

  • SharedSystem
  • NationalClaimsHistory
  • DDPS
GET /api/v3/Patient/$export?_type=ExplanationOfBenefit&_typeFilter=ExplanationOfBenefit%3F_tag%3Dhttps%3A%2F%2Fbluebutton.cms.gov%2Ffhir%2FCodeSystem%2FSystem-Type%7CSharedSystem%2Chttps%3A%2F%2Fbluebutton.cms.gov%2Ffhir%2FCodeSystem%2FSystem-Type%7CNationalClaimsHistory%2Chttps%3A%2F%2Fbluebutton.cms.gov%2Ffhir%2FCodeSystem%2FSystem-Type%7CDDPS

If you used the _type parameter for _type=Claim,ClaimResponse in v2 requests, you received SharedSystem claims only.

In v3, specify the SharedSystem System-Type code:

GET /api/v3/Patient/$export?_type=ExplanationOfBenefit&_typeFilter=ExplanationOfBenefit%3F_tag%3Dhttps%3A%2F%2Fbluebutton.cms.gov%2Ffhir%2FCodeSystem%2FSystem-Type%7CSharedSystem%2Chttps%3A%2F%2Fbluebutton.cms.gov%2Ffhir%2FCodeSystem%2FSystem-Type%7CNationalClaimsHistory%2Chttps%3A%2F%2Fbluebutton.cms.gov%2Ffhir%2FCodeSystem%2FSystem-Type%7CDDPS

If you used the _type parameter for _type=ExplanationOfBenefit for v2 requests, you received NationalClaimsHistory claims and DDPS claims.

In v3, specify the NationalClaimsHistory and DDPS System-Type codes:

GET /api/v3/Patient/$export?_type=ExplanationOfBenefit&_typeFilter=ExplanationOfBenefit%3F_tag%3Dhttps%3A%2F%2Fbluebutton.cms.gov%2Ffhir%2FCodeSystem%2FSystem-Type%7CSharedSystem%2Chttps%3A%2F%2Fbluebutton.cms.gov%2Ffhir%2FCodeSystem%2FSystem-Type%7CNationalClaimsHistory%2Chttps%3A%2F%2Fbluebutton.cms.gov%2Ffhir%2FCodeSystem%2FSystem-Type%7CDDPS
Omitting _typeFilter

In v3, if you make a request without using the _typeFilter parameter to filter by System-Type, BCDA will return only NationalClaimsHistory and DDPS claims.

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

New extension and code system URLs

BCDA v3 uses the StructureDefinition and CodeSystem FHIR resources. This is the standard way to represent code system URLs. It makes it easier to access the metadata. You can access the metadata for each Extension and CodeSystem by hitting the URL. This will return a StructureDefinition or CodeSystem FHIR resource.

URLs changing between v2 and v3

Make the following changes to migrate to v3 if you’ve mapped any bluebutton extension or code system URLs:

Changes to Extension URLs

Changes to Extension URLs between v2 and v3
v2 URL 
https://bluebutton.cms.gov/resources/variables/nch_near_line_rec_ident_cd/
v3 URL 
https://bluebutton.cms.gov/fhir/StructureDefinition/CLM-NRLN-RIC-CD

Changes to CodeSystem URLs

Changes to CodeSystem URLs between v2 and v3
v2 URL 
https://bluebutton.cms.gov/resources/variables/nch_near_line_rec_ident_cd/
v3 URL 
https://bluebutton.cms.gov/fhir/CodeSystem/CLM-NRLN-RIC-CD

If your BCDA client is using any of the v2 URLs, you’ll need to update your code to look for the v3 version.

Different resource IDs between versions

Do not use FHIR IDs to match resources between versions.

To match beneficiaries, use MBI and demographics data. To match claims, use the claim control number.

In BCDA v3, the FHIR ID (Patient.id, ExplanationOfBenefit.id, Coverage.id) for a given resource will not match the v2 FHIR resource ID.

Example:

If you receive the Patient resource from BCDA v3, do not look up an existing patient by expecting the v2 Patient.id to equal the v3 Patient.id value. These values will not match. They are a different set of identifiers. However, the range of v2 and v3 Patient IDs does overlap, so there are some IDs that represent a v2 Patient and v3 Patient. This would not mean they represent the same beneficiary in real life.  

Instead of matching on Patient.id, use the relevant CMS identifier (MBI), along with additional supporting resource info (patient demographics like name, date of birth, etc.). Similarly, ExplanationOfBenefit.id and Coverage.id will not match between v2 and v3. 

Matching beneficiaries between v2 and v3

Because the v2 and v3 Patient IDs will not match, in order to match a v3 patient to a patient you already have in your database, the best way is to use the MBI and demographics. The MBI and demographics should match between versions of BCDA. 

To find the MBI in the FHIR Patient resource, look at the Patient.identifier element for an identifier where the identifier.system is http://hl7.org/fhir/sid/us-mbi. The identifier.value will be the MBI.

Example v3 Patient.identifier element:

{
  "identifier": [
    {
      "type": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
            "code": "MB"
          }
        ]
      },
      "system": "http://hl7.org/fhir/sid/us-mbi",
      "value": "1S00E00AA08",
      "period": {
        "start": "2018-01-24T00:00:00+00:00"
      }
    }
  ]
}

It is always good practice to have some kind of validation based on patient demographics, like supplementing the MBI exact match with some subset of name, date of birth, and gender matching.

Once you have matched an existing Patient, or created a new one, it is ok to store the BCDA v3 Patient.id. It is possible for two different MBIs to reference the same beneficiary, and therefore the same BCDA v3 Patient. If that happens, you will see multiple instances of Patient.identifier where the system is http://hl7.org/fhir/sid/us-mbi. This is rare, but you should be prepared for it to happen.

Example of v3 Patient.identifier with two MBIs:

{
  "identifier": [
    {
      "type": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
            "code": "MB"
          }
        ]
      },
      "system": "http://hl7.org/fhir/sid/us-mbi",
      "value": "1S00E00AA08",
      "period": {
        "start": "2022-04-05T00:00:00+00:00",
        "end": "2022-04-12T00:00:00+00:00"
      }
    },
    {
      "type": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
            "code": "MB"
          }
        ]
      },
      "system": "http://hl7.org/fhir/sid/us-mbi",
      "value": "1S00E00AE22",
      "period": {
        "start": "2022-04-12T00:00:00+00:00"
      }
    }
  ]
}

Matching claims between v2 and v3

Because the v3 ExplanationOfBenefit FHIR ID will not match the v2 ExplanationOfBenefit or Claim/ClaimResponse FHIR IDs, in order to match a v3 claim to a claim you already have in your database, the best way is to use the claim control number.

Because each version of a claim will have a unique claim ID, you should avoid using the unique claim ID to track a claim across versions, or even within a version across the adjudication journey. Instead, use the claim control number. It is the identifier where the identifier.system equals https://bluebutton.cms.gov/identifiers/CLM-CNTL-NUM.

Example ExplanationOfBenefit.identifier element:

{
  "identifier": [
    {
      "type": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/us/carin-bb/CodeSystem/C4BBIdentifierType",
            "code": "uc",
            "display": "Unique Claim ID"
          }
        ]
      },
      "value": "-9422919134190"
    },
    {
      "system": "https://bluebutton.cms.gov/identifiers/CLM-CNTL-NUM",
      "value": "05968201612271KJS"
    }
  ]
}

FHIRPath for claim identifier:

ExplanationOfBenefit.identifier.where(system = 'https://bluebutton.cms.gov/identifiers/CLM-CNTL-NUM').value

cms.gov

official website of the U.S. Department of Health and Human Services and the Centers for Medicare & Medicaid Services.

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