OAuth 2.0 authorization-code flow with mandatory PKCE (S256) that beneficiaries use to grant an app access to their Medicare data via Medicare.gov login, plus the /v2/connect/userinfo endpoint returning the authorized user's OpenID Connect profile. Access tokens last one hour; one-time-use refresh tokens are issued to approved 13-month and research application types.
openapi: 3.0.3
info:
title: CMS Blue Button 2.0 API
description: >-
Blue Button 2.0 is the Centers for Medicare & Medicaid Services (CMS)
patient-facing API that lets Medicare beneficiaries share their Parts A, B,
and D claims data with applications they authorize. The v2 API is FHIR R4
(4.0.1) and conforms to the CARIN Blue Button Implementation Guide (CARIN
Consumer Directed Payer Data Exchange, CDPDE). It exposes three FHIR
resource types - ExplanationOfBenefit (claims), Patient (demographics),
and Coverage (Part A/B/D enrollment) - plus a capability statement and an
OpenID Connect userinfo endpoint. Every request is scoped to the single
beneficiary who authorized the application through the OAuth 2.0
authorization-code flow (PKCE S256 required) on Medicare.gov. The sandbox
at sandbox.bluebutton.cms.gov mirrors production with synthetic data for
10,000 enrollees.
version: '2.0'
contact:
name: CMS Blue Button 2.0
url: https://bluebutton.cms.gov
termsOfService: https://bluebutton.cms.gov/terms/
servers:
- url: https://api.bluebutton.cms.gov/v2/fhir
description: Production (approved applications only)
- url: https://sandbox.bluebutton.cms.gov/v2/fhir
description: Sandbox (synthetic Medicare enrollee data, self-serve)
security:
- oauth2:
- patient/ExplanationOfBenefit.read
- patient/Patient.read
- patient/Coverage.read
tags:
- name: ExplanationOfBenefit
description: Medicare Parts A, B, and D claims as CARIN Blue Button EOB profiles.
- name: Patient
description: Beneficiary demographic and administrative data.
- name: Coverage
description: Medicare coverage resources, one per coverage type.
- name: Metadata
description: FHIR capability statement.
- name: UserInfo
description: OpenID Connect userinfo for the authorizing beneficiary.
paths:
/ExplanationOfBenefit:
get:
operationId: searchExplanationOfBenefit
tags:
- ExplanationOfBenefit
summary: Search a beneficiary's Medicare claims
description: >-
Returns the authorized beneficiary's Medicare Parts A, B, and D claims
as ExplanationOfBenefit resources inside a FHIR Bundle, conforming to
the CARIN Blue Button profiles.
parameters:
- name: patient
in: query
description: The FHIR logical id of the beneficiary Patient resource.
schema:
type: string
- name: type
in: query
description: >-
Claim type filter - one or more of carrier, pde, dme, hha, hospice,
inpatient, outpatient, snf.
schema:
type: string
- name: service-date
in: query
description: Filter claims by service date range using gt/lt/ge/le prefixes.
schema:
type: string
- $ref: '#/components/parameters/lastUpdated'
- name: excludeSAMHSA
in: query
description: >-
When true, excludes claims related to substance abuse and mental
health services (SAMHSA).
schema:
type: string
enum: ['true', 'false']
- name: includeTaxNumbers
in: query
description: When true, includes provider tax numbers in the response.
schema:
type: string
enum: ['true', 'false']
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/startIndex'
responses:
'200':
description: A FHIR Bundle of ExplanationOfBenefit resources.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Bundle'
'401':
$ref: '#/components/responses/Unauthorized'
/ExplanationOfBenefit/{id}:
get:
operationId: readExplanationOfBenefit
tags:
- ExplanationOfBenefit
summary: Read a single claim by id
description: Returns a single ExplanationOfBenefit resource by FHIR logical id.
parameters:
- $ref: '#/components/parameters/resourceId'
responses:
'200':
description: An ExplanationOfBenefit resource.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/ExplanationOfBenefit'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/Patient:
get:
operationId: searchPatient
tags:
- Patient
summary: Search the authorized beneficiary's Patient resource
description: >-
Returns the beneficiary's demographic and administrative record as a
Patient resource in a FHIR Bundle. Available only if the beneficiary
chose to share demographic data during authorization.
parameters:
- name: _id
in: query
description: The FHIR logical id of the Patient resource.
schema:
type: string
- name: identifier
in: query
description: >-
Search by business identifier (Medicare Beneficiary Identifier hash
system identifiers).
schema:
type: string
- $ref: '#/components/parameters/lastUpdated'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/startIndex'
responses:
'200':
description: A FHIR Bundle containing the Patient resource.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Bundle'
'401':
$ref: '#/components/responses/Unauthorized'
/Patient/{id}:
get:
operationId: readPatient
tags:
- Patient
summary: Read the beneficiary's Patient resource by id
description: Returns the Patient resource for the authorizing beneficiary.
parameters:
- $ref: '#/components/parameters/resourceId'
responses:
'200':
description: A Patient resource.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Patient'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/Coverage:
get:
operationId: searchCoverage
tags:
- Coverage
summary: Search a beneficiary's Medicare coverage
description: >-
Returns Coverage resources inside a FHIR Bundle - one Coverage resource
per coverage type (Medicare Part A, Part B, Part D).
parameters:
- name: beneficiary
in: query
description: The FHIR logical id of the beneficiary Patient resource.
schema:
type: string
- name: _profile
in: query
description: Filter the response to a specific CARIN Coverage profile.
schema:
type: string
- $ref: '#/components/parameters/lastUpdated'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/startIndex'
responses:
'200':
description: A FHIR Bundle of Coverage resources.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Bundle'
'401':
$ref: '#/components/responses/Unauthorized'
/Coverage/{id}:
get:
operationId: readCoverage
tags:
- Coverage
summary: Read a single Coverage resource by id
description: Returns a single Coverage resource by FHIR logical id.
parameters:
- $ref: '#/components/parameters/resourceId'
responses:
'200':
description: A Coverage resource.
content:
application/fhir+json:
schema:
$ref: '#/components/schemas/Coverage'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/metadata:
get:
operationId: getCapabilityStatement
tags:
- Metadata
summary: Retrieve the FHIR capability statement
description: >-
Returns the server CapabilityStatement (FHIR 4.0.1) describing the
supported resources, interactions, and search parameters. Does not
require authorization.
security: []
responses:
'200':
description: A CapabilityStatement resource.
content:
application/fhir+json:
schema:
type: object
description: FHIR CapabilityStatement resource.
/connect/userinfo:
servers:
- url: https://api.bluebutton.cms.gov/v2
description: Production (userinfo lives outside the /fhir base path)
- url: https://sandbox.bluebutton.cms.gov/v2
description: Sandbox
get:
operationId: getUserInfo
tags:
- UserInfo
summary: Retrieve the authorizing user's OpenID Connect profile
description: >-
Full path is /v2/connect/userinfo (outside the /fhir base). Returns the
authorizing beneficiary's user profile (name, family name, email) when
the openid and profile scopes were granted.
responses:
'200':
description: OpenID Connect userinfo JSON.
content:
application/json:
schema:
type: object
properties:
sub:
type: string
name:
type: string
given_name:
type: string
family_name:
type: string
email:
type: string
'401':
$ref: '#/components/responses/Unauthorized'
components:
parameters:
resourceId:
name: id
in: path
required: true
description: The FHIR logical id of the resource.
schema:
type: string
lastUpdated:
name: _lastUpdated
in: query
description: >-
Filter by the record's last_updated date using gt/lt prefixes; may be
supplied more than once to define a range.
schema:
type: string
count:
name: _count
in: query
description: Number of records per page for pagination.
schema:
type: integer
startIndex:
name: startIndex
in: query
description: Zero-based index of the first record to return for pagination.
schema:
type: integer
responses:
Unauthorized:
description: Missing, expired, or invalid OAuth 2.0 access token.
NotFound:
description: No resource exists with the supplied id for this beneficiary.
schemas:
Bundle:
type: object
description: A FHIR R4 searchset Bundle wrapping matching resources.
properties:
resourceType:
type: string
enum: [Bundle]
type:
type: string
total:
type: integer
link:
type: array
items:
type: object
properties:
relation:
type: string
url:
type: string
entry:
type: array
items:
type: object
properties:
resource:
type: object
ExplanationOfBenefit:
type: object
description: >-
FHIR R4 ExplanationOfBenefit conforming to the CARIN Blue Button
profiles - one of carrier, pde (Part D drug event), dme, hha, hospice,
inpatient, outpatient, or snf claim types.
properties:
resourceType:
type: string
enum: [ExplanationOfBenefit]
id:
type: string
type:
type: object
patient:
type: object
billablePeriod:
type: object
insurance:
type: array
items:
type: object
item:
type: array
items:
type: object
total:
type: array
items:
type: object
Patient:
type: object
description: FHIR R4 Patient resource for the authorizing Medicare beneficiary.
properties:
resourceType:
type: string
enum: [Patient]
id:
type: string
identifier:
type: array
items:
type: object
name:
type: array
items:
type: object
birthDate:
type: string
address:
type: array
items:
type: object
Coverage:
type: object
description: >-
FHIR R4 Coverage resource - one per Medicare coverage type (Part A,
Part B, Part D).
properties:
resourceType:
type: string
enum: [Coverage]
id:
type: string
status:
type: string
beneficiary:
type: object
class:
type: array
items:
type: object
securitySchemes:
oauth2:
type: oauth2
description: >-
OAuth 2.0 authorization-code flow with mandatory PKCE (S256 only).
Beneficiaries log in with their Medicare.gov credentials and choose
whether to share demographic data. Access tokens expire after 1 hour.
One-time-use refresh tokens are issued only to approved 13-month and
research application types. Sandbox uses
https://sandbox.bluebutton.cms.gov/v2/o/authorize/ and
https://sandbox.bluebutton.cms.gov/v2/o/token/.
flows:
authorizationCode:
authorizationUrl: https://api.bluebutton.cms.gov/v2/o/authorize/
tokenUrl: https://api.bluebutton.cms.gov/v2/o/token/
refreshUrl: https://api.bluebutton.cms.gov/v2/o/token/
scopes:
patient/Patient.read: Read the beneficiary's Patient demographic resource.
patient/ExplanationOfBenefit.read: Read the beneficiary's Medicare claims.
patient/Coverage.read: Read the beneficiary's Medicare coverage.
openid: OpenID Connect authentication.
profile: Access the userinfo profile endpoint.
launch/patient: Receive the patient FHIR id in the token response.