openapi: 3.0.3
info:
  title: CMS Blue Button 2.0 Coverage Patient 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: Patient
  description: Beneficiary demographic and administrative data.
paths:
  /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'
components:
  schemas:
    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
    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
  responses:
    Unauthorized:
      description: Missing, expired, or invalid OAuth 2.0 access token.
    NotFound:
      description: No resource exists with the supplied id for this beneficiary.
  parameters:
    startIndex:
      name: startIndex
      in: query
      description: Zero-based index of the first record to return for pagination.
      schema:
        type: integer
    count:
      name: _count
      in: query
      description: Number of records per page for pagination.
      schema:
        type: integer
    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
    resourceId:
      name: id
      in: path
      required: true
      description: The FHIR logical id of the resource.
      schema:
        type: string
  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.