v3 FAQ

Getting Started

What are the benefits of v3?

Improved claims data timeliness
- Eliminates the 1-4 week data lag that was present in v1/v2
- Allows Medicare enrollees to review claims in as little as one day after a claim is filed
- Allows for faster detection of billing issues and fraud
Digital Medicare card
- Provides all the necessary data elements for enrollee-facing applications to render digital Medicare cards, including Medicare Advantage plan details and prescription coverage information.
- Provides transparency into Medicare coverage for enrollees and reduces administrative barriers for those seeking to understand their insurance.
Transparent, granular data sharing options
- Updated, streamlined consent screen with user-friendly explanations of what data is being shared
- Medicare enrollees can choose to withhold substance use disorder claims data when connecting to applications
Improved FHIR Compliance and enhanced interoperability
- Implements SMART App Launch v2.2 with granular consent at the resource level, corrects improper extension/CodeSystem representations, and provides FHIRPath navigation for easier data extraction

What documentation exists for v3?

There are a few key reference resources that will be helpful for the transition to and understanding of v3:

Migrating from v1/v2 to v3

Is v3 backward compatible?

Blue Button v3 is backward compatible at the API level; replace /v2/ or /v1/ with /v3/ in your requests to call v3 of the API. Your existing v1/v2 tokens will continue to work with v3 in most scenarios. Take a look at the migration guide section FHIR IDs in v2 and v3 for specific details about how tokens work across versions.

The biggest change for applications migrating from v1/v2 to v3 is that Patient resource IDs will not match across versions, but you can map them via MBI, which will remain the same. We recommend testing in the sandbox before migrating your production application.

How does a v2 identifier map to a v3 identifier?

The Medicare Beneficiary Identifier (MBI) is consistent between v2 and v3 Patient resources; however, other identifiers and the Patient resource ID are different between v2 and v3. When obtaining an access token from a grant code or a refresh token, the proper v2 or v3 Patient resource ID will be in the patient field of the resulting JSON, depending on whether the v2 endpoint https://sandbox.bluebutton.cms.gov/v2/o/token/ or the v3 endpoint https://sandbox.bluebutton.cms.gov/v3/o/token/ is used.

In rare cases, for example, if fraud is reported on an enrollee’s account, a new identifier may be issued. When this happens, the latest token will contain the correct identifier, and Patient responses using that token will include a link to the previous identifier.

In what scenarios will tokens not work across v1/v2 and v3?

Note that going forward, a Blue Button a user will only ever have one active token per Blue Button application at a time. If a user goes through a Blue Button auth flow while they already have an existing token (e.g., going through the v3 auth flow when they already went through v2), a successful auth will delete the old v2 token. This prevents an app from using a token that doesn’t reflect their most recent privacy preferences.

Additionally, any v3 token that does not include substance use data (enrollee left the box unchecked on the consent screen) and is used to query EOB for v2 instead of v3 will result in an error. This is because we want to continue respecting the enrollee’s most recent privacy preferences, and we don’t support substance use data filtering on v2.

Claims Data & Adjudication

What is Shared Systems data, and how can I use it in my application?

Shared Systems data (FISS, MCS, VMS) gives your application access to Part A/B claims within days of submission, rather than waiting weeks for full adjudication. This is useful for applications that want to alert users sooner to recent care events, such as a hospital discharge. These claims are tagged SharedSystem and will update as they move through processing.

How often is the Coverage and enrollment data updated in v3?

Blue Button gets coverage data from the Common Medicare Environment (CME). CMS designated the CME database as the single authoritative source for Medicare enrollment and demographic data. The Integrated Data Repository (IDR) adds CME data nightly, completing processing around 3 AM ET.

The IDR data is available via Blue Button v3 immediately after the new data loads. This data load happens 6 days a week (Sun-Friday). This means that the Blue Button API will have updated enrollment information the day after a change, except on Saturday, by ~4 AM ET.

Which claim types are available in a partially adjudicated format?

Only Part A/B claims processed through the Shared Systems (FISS for institutional claims, MCS for professional claims, and VMS for DME claims) are available in a partially adjudicated form. Part D (prescription drug) claims, sourced from the Drug Data Processing System (DDPS), are only available once fully adjudicated. Part D has no partially adjudicated data.

How can I determine the adjudication status of a claim?

Check the ExplanationOfBenefit.outcome field (complete or partial) or filter by tag to see a claim’s source system. Only Part A/B claims from Shared Systems can return partial; Part D claims are always fully adjudicated. For filtering syntax and tag values, see metadata filtering.

The Blue Button API offers a full set of scopes that apps can request, such as claims data, patient demographics, and coverage information. Here’s how the process works:

Your app requests scopes. How you do this depends on your app’s status:
1. New applications: You’ll discuss which scopes make sense for your use case during the demo and approval process.
2. Current applications: Fill out this form to identify the scopes you need. The Blue Button team will follow up with any questions.
The Blue Button team reviews and approves your request. The team makes the final determination of which scopes your app can request.
Based on the approved scopes and the scopes included in the request to the authorize endpoint, Blue Button builds the consent screen that enrollees see, showing only the data categories relevant to that request.

If a claim has multiple in-flight (not yet fully adjudicated) versions, do you return a deduplicated result?

Yes, we return only the latest single version of an in-flight claim per source (see the migration guide’s metadata filtering section for more details on supported sources). We return only the latest version of an in-flight claim per source. Older, superseded versions won’t appear. However, deduplication does not happen across sources: once a claim finishes adjudication, you can receive two EOB resources for it, one from Shared Systems and one from the National Claims History (NCH), for instance, rather than the Shared Systems version disappearing.

Working with the API

Do you support the `_lastUpdated` search parameter?

Yes, _lastUpdated is supported according to the FHIR spec.

How does pagination work in v3? Is it different from v1/v2?

For v3 ExplanationOfBenefit search calls, the offset parameter will be used to paginate through an enrollee’s claims data, rather than the startIndex parameter. In v3 ExplanationOfBenefit search calls, the API returns 10 records by default. You can return more than 10 by passing in a count parameter (the value must be between 1 and 50). So, if an enrollee has 20 claims in v3, you could retrieve the first 10 without passing any parameters, and you could then retrieve the remaining 10 by passing offset=10. To get all claims data you can get in a single call, pass count=50 . Further details are available in the Blue Button Swagger resource.

On the permission screen, will optional fields only appear when requested?

The optional field (alcohol and substance use data) depends on the scopes requested. The substance use data sharing checkbox will only appear if the EOB scope is requested.

What is the alcohol and substance use data and where does it come from?

Alcohol and substance use data is a subset of the claims data. Certain claims are categorized based on a defined list tied to 42 CFR Part 2, a federal rule protecting the confidentiality of substance use disorder treatment records. In v3, these claims are withheld unless the enrollee opts to share them with a third-party application.

Optional alcohol and substance use data will not be shared by default; however, a user can select the checkbox on the permission form during the authorization flow to elect to share that data if they wish.