API Documentation

The Blue Button API enables software developers to build trusted applications, services, and research programs that benefit Medicare enrollees. As a standards-based API, Blue Button provides claims data for more than 64 million people with Medicare.

Blue Button uses Fast Healthcare Interoperability Resources (FHIR) to share claims data. You can use a variety of tools or client software programs to access the sandbox and production environments.

Getting started

Learn about the Blue Button API
Learn about technical requirements, development environments, and, our process for providing access to enrollee data.
Create a sandbox account
Using sandbox credentials, develop and test your Blue Button application using the synthetic data provided.
Visit the Sandbox
Get production access
Follow the steps on the Production Access page to get access to live data in our production environment.

Technical Specifications and Standards

The Blue Button API is a RESTful API, based on the HL7 FHIR standard and the CARIN Consumer Directed Payer Data Exchange Implementation Guide. It supplies data in JSON format, and uses the OAuth 2.0 protocol for authorization.

Versions

We currently support two Blue Button API versions:

Version 2

Blue Button Version 2 (v2) is based on FHIR release (R4) and the CARIN CDPDE Implementation Guide (Carin for Blue Button) and was released in July 2021. To learn about migrating to Blue Button v2, go to Migrating to v2 FAQ

Version 1

Version 1 (v1) is the original Blue Button API, based on FHIR release 3 (STU3). Development on v1 is limited to bug fixes and basic maintenance. If you’re developing a new app, use v2.

Environments

We currently maintain production and sandbox environments for developing with the Blue Button API.

Sandbox

Develop your application using our sandbox environment. It provides access to synthetic Medicare enrollee data and includes all the same endpoints, resource types, and parameters as production. You can complete all of the same operations in the sandbox as in the production environment.

It’s helpful to know that:

Sandbox credentials will not work in production.
While we strive to provide a synthetic data set relevant to most use cases, our synthetic data set is not as comprehensive as production data.

To get started in the developer sandbox, create an account.

Production

Once your development is nearing completion, get access to live data in our production environment by following the instructions in our production access user guide. After you complete the requirements in the production access guide and your app is approved, we’ll give you credentials for the production environment.

Access to Medicare enrollee data

Scope of access

Applications receive permission to access Medicare enrollee data on a per-user basis. Access to claims data for each individual enrollee begins after they grant access to an application via the Blue Button API’s authorization flow.

Medicare enrollees may always opt to omit personal data such as name, date of birth, race, and sex when granting access to claims data. An enrollee’s choice during the Blue Button authorization flow determines the scope of access an application will have to their data.

Duration of access

The length of time that an application can continue to pull new claims data from Medicare depends on the application’s use case and category. The Blue Button API team determines your application’s access duration category during the production access process.

There are 3 categories for data access duration:

Categories for data access duration
Category	Description and Notes
10 hours	One-time use apps (Example: An app that pulls an enrollee’s data once to recommend insurance plans) These apps do not usually require separate logins or store users’ data over time. Authorization will be granted for 10 hours, without the ability to refresh the token. If an enrollee uses the app more than once outside the 10-hour window, they must reauthorize for each data pull.
13 months	Apps that pull data for the enrollee’s use on an ongoing basis (Example: A personal health aggregator app.) Authorization will be granted for 13 months. For continued access after 13 months, an app must prompt the user to reauthorize.
Research	Apps that facilitate Institutional Review Board (IRB)-approved clinical research studies Access to an enrollee’s data will never expire unless revoked by the enrollee or by the Blue Button team due to app inactivity over a period of time. Research apps will be reviewed every 2 years to ensure that they are still active. If a research app is not active at a 2-year check-in, we will contact the app team for confirmation that they still need Blue Button API access. If you have a research app, please keep us updated on changes to your contact information and watch for emails from BlueButtonAPI@cms.hhs.gov.