-
Notifications
You must be signed in to change notification settings - Fork 8
v3 Migration Guide
AB2D v3 documentation is subject to change during the Early Adopter Program.
Any issues or feedback on this documentation should be sent to AB2D@cms.hhs.gov.
- Migration overview
- Why migrate to v3
- v3 Data Dictionary
- Breaking changes in v3
- Major Updates
- Transition timeline
- Questions or feedback?
This guide helps you migrate from AB2D v1/v2 to version 3 (v3). AB2D v3 is currently available to Early Adopter participants. Key changes include:
-
A new v3 endpoint URL
-
Beneficiary identification using MBI instead of BENE_ID
-
Updated extension and code system URLs throughout the ExplanationOfBenefit resource
-
Different resource IDs between v2 and v3
-
A new _typeFilter parameter for filtering claims by service date
-
Automatic claims deduplication within a data source
-
A new Claim Control Number field for tracking claims across versions
AB2D v3 continues to return only the ExplanationOfBenefit (EOB) resource type with fully adjudicated Medicare Parts A and B claims data in NDJSON format. The overall API workflow - authenticate, start a job, check status, download files - remains the same.
AB2D v3 introduces meaningful improvements to the timeliness and quality of the claims data available to PDP sponsors.
Claims data in v3 is refreshed weekly on Mondays for Parts A and B, compared to the Friday weekly cadence in v1/v2. The lag between claim adjudication and availability in AB2D is reduced from up to 2 weeks to 0-7 days, enabling more timely and targeted health interventions.In v1/v2, there could be a delay of several months between the creation of an enrollee's information and its availability in AB2D. v3 largely eliminates this lag, and an enrollee's information is often available several months before Medicare coverage starts.
v3 includes a patient merge feature that reconciles beneficiaries who had multiple identifiers in v1/v2. All MBIs for a patient now direct to a single, active patient record.
v3 returns only the most recent version of a claim from a given source, reducing the volume of duplicate data your systems need to process. AB2D v1 and v2, in contrast, could return multiple EOBs for a claim due to several factors such as adjustments.
Improved FHIR conformance makes it easier to map and aggregate data with other sources, reducing manual reconciliation and improving consistency across systems.
Improved data on providers and prescribers makes care coordination easier for prescribers and care teams. Better data quality means improved health interventions in programs that catch drug interactions, reduce unnecessary medications, and lower beneficiary out-of-pocket costs.
New filtering capabilities enable smaller, more customized exports, helping you retrieve only the data you need.
These improvements support PDP sponsor use cases such as Medication Therapy Management (MTM) programs, Star Ratings measures, and fraud, waste, and abuse prevention - all of which benefit from fresher, more complete claims data.
The AB2D v3 Data Dictionary provides the complete field-by-field mapping between v2 and v3, including the v2 FHIR element path, the v3 FHIRPath expression, the change type, and whether the change is breaking.
Download the AB2D v3 Data Dictionary
The majority of the EOB resource (173 of 252 fields) is unchanged. If your integration is focused on common fields like diagnosis codes, procedure codes, payment amounts, and service dates, your migration effort may be minimal.
The table below summarizes the categories of changes across the ExplanationOfBenefit resource. The AB2D v3 Data Dictionary provides the complete field-by-field mapping.
| Change type | Count | What it means |
|---|---|---|
| New StructureDefinition/CodeSystem URL | 28 fields | The extension or code system URL has changed from the legacy bluebutton.cms.gov/resources/variables/ format to the new bluebutton.cms.gov/f |
| Element moved | 43 fields | These elements have moved |
| Element removed | 7 fields | These fields were deprecated or not in use in previous API versions. |
AB2D v3 is located at the same domain as previous versions, but uses a new endpoint path. Migrate to v3 by updating the version from v2 to v3 in your export request URL.
GET /api/v2/fhir/Patient/$export
GET /api/v3/fhir/Patient/$export
The /auth and file download URLs remain the same between versions. You do not need to change how you request a bearer token or download files.
The _since and _until parameters continue to work in v3 with the same behavior as v2.
v3 replaces the legacy URL pattern used for extensions and code systems with standard FHIR StructureDefinition and CodeSystem resources to better conform with the CARIN standards for Blue Button version 2.1.0. This is a breaking change that affects 26 fields in the EOB resource.
https://bluebutton.cms.gov/resources/variables/{variable_name}
https://bluebutton.cms.gov/fhir/StructureDefinition/{element-code}
https://bluebutton.cms.gov/fhir/CodeSystem/{element-code}
In v3, you can access the metadata for each extension and code system by requesting the URL directly. This returns a StructureDefinition or CodeSystem FHIR resource.
https://bluebutton.cms.gov/resources/variables/claim_query_cd
https://bluebutton.cms.gov/fhir/StructureDefinition/CLM-QUERY-CD
Search your codebase for references to bluebutton.cms.gov/resources/variables/ and update each URL to its v3 equivalent. The AB2D v3 Data Dictionary provides the complete mapping of v2 to v3 URLs for every affected field.
In v1/v2, AB2D used the BENE_ID as the patient FHIR ID, but in v3, BENE_ID has been deprecated. Medicare Beneficiary Identifier (MBI) should be used instead as a primary beneficiary identifier, and will match across AB2D API versions.
The MBI can be found in the same extension as v2, ExplanationOfBenefit.extension.where(url='http://hl7.org/fhir/StructureDefinition/elementdefinition-identifier').valueIdentifier.value
BENE_ID is a construct of the Chronic Conditions Warehouse (CCW). It does not exist in the Integrated Data Repository (IDR), which is the upstream data source for v3.
In v3, the FHIR ID for ExplanationOfBenefit resources (ExplanationOfBenefit.id) and Patient resources (ExplanationOfBenefit.patient) will not match the v2 FHIR resource IDs. The range of v2 and v3 IDs does overlap, so it is possible for an ID to exist in both versions without representing the same claim.
To match claims between v2 and v3, use the Claim Control Number. To match beneficiaries, use the MBI along with supporting demographic information (name, date of birth, gender).
v3 introduces the _typeFilter parameter for Bulk FHIR exports. AB2D v3 supports filtering ExplanationOfBenefit resources by service date using _typeFilter.
GET /api/v3/fhir/Patient/$export?_type=ExplanationOfBenefit&_typeFilter=ExplanationOfBenefit%3Fservice-date%3Dge2025-01-01
The _typeFilter parameter is URL-encoded. The decoded value of the filter above is:
ExplanationOfBenefit?service-date=ge2025-01-01
This returns only EOB resources where the service date is on or after January 1, 2025.
Note: _typeFilter is a new parameter in v3. The _since and _until parameters filter by the lastUpdated timestamp, while _typeFilter with service-date filters on the claim service date (ExplanationOfBenefit .billablePeriod).
v3 improves data refresh frequency for claims data available through AB2D.
| Data | v1/v2 | v3 |
|---|---|---|
| Parts A and B claims (NCH) | Weekly, on Friday (up to 2 weeks from adjudication) | Weekly, on Monday (0-7 days from adjudication) |
| Patient/enrollment data | Weekly, on Friday | 6x/week (Sunday through Friday) |
For AB2D users, the practical impact is that fully adjudicated claims will be available sooner after adjudication and with a more frequent refresh cadence for Part D and enrollment data.
More information to come.
If you have questions about migrating to v3 or encounter issues during the Early Adopter Program, contact the AB2D team at ab2d@cms.hhs.gov