openapi: 3.0.3
info:
  title: CMS Blue Button 2.0 API
  description: |
    The CMS Blue Button 2.0 API is a developer-friendly, OAuth 2.0-enabled HL7 FHIR R4 API
    that delivers Medicare Part A, B, and D claims data for 60+ million Medicare beneficiaries
    to applications, services, and research programs after the beneficiary grants consent.
  version: '2.0'
  contact:
    name: CMS Blue Button Developer Help
    url: https://bluebutton.cms.gov/developers/
    email: bluebuttonapi@cms.hhs.gov
  license:
    name: Public Domain (U.S. Government Work)
    url: https://www.usa.gov/government-works
servers:
- url: https://api.bluebutton.cms.gov/v2/fhir
  description: Production FHIR R4 endpoint
- url: https://sandbox.bluebutton.cms.gov/v2/fhir
  description: Sandbox FHIR R4 endpoint
security:
- OAuth2: [read]
paths:
  /metadata:
    get:
      summary: Get FHIR Capability Statement
      operationId: getCapabilityStatement
      tags: [Metadata]
      security: []
      responses:
        '200':
          description: FHIR CapabilityStatement
          content:
            application/fhir+json:
              schema: { $ref: '#/components/schemas/CapabilityStatement' }
  /Patient:
    get:
      summary: Search Patient Resources
      operationId: searchPatient
      description: Returns the Patient resource for the currently authorized beneficiary.
      tags: [Patient]
      parameters:
      - { name: _id, in: query, schema: { type: string } }
      - { name: _format, in: query, schema: { type: string, enum: [application/fhir+json, application/fhir+xml] } }
      responses:
        '200':
          description: Bundle of Patient resources
          content:
            application/fhir+json:
              schema: { $ref: '#/components/schemas/Bundle' }
  /Patient/{id}:
    get:
      summary: Read Patient by ID
      operationId: readPatient
      tags: [Patient]
      parameters:
      - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Patient resource
          content:
            application/fhir+json:
              schema: { $ref: '#/components/schemas/Patient' }
  /Coverage:
    get:
      summary: Search Coverage Resources
      operationId: searchCoverage
      tags: [Coverage]
      parameters:
      - { name: beneficiary, in: query, schema: { type: string } }
      - { name: _format, in: query, schema: { type: string } }
      responses:
        '200':
          description: Bundle of Coverage resources
          content:
            application/fhir+json:
              schema: { $ref: '#/components/schemas/Bundle' }
  /Coverage/{id}:
    get:
      summary: Read Coverage by ID
      operationId: readCoverage
      tags: [Coverage]
      parameters:
      - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Coverage resource
          content:
            application/fhir+json:
              schema: { $ref: '#/components/schemas/Coverage' }
  /ExplanationOfBenefit:
    get:
      summary: Search Explanation Of Benefit Resources
      operationId: searchExplanationOfBenefit
      description: Returns Medicare claims as FHIR ExplanationOfBenefit resources for the authorized beneficiary.
      tags: [ExplanationOfBenefit]
      parameters:
      - { name: patient, in: query, schema: { type: string } }
      - { name: type, in: query, schema: { type: string, description: 'Claim type: carrier, dme, hha, hospice, inpatient, outpatient, pde, snf' } }
      - { name: service-date, in: query, schema: { type: string, description: 'FHIR date or date range' } }
      - { name: _lastUpdated, in: query, schema: { type: string } }
      - { name: startIndex, in: query, schema: { type: integer } }
      - { name: _count, in: query, schema: { type: integer, maximum: 50 } }
      responses:
        '200':
          description: Bundle of ExplanationOfBenefit resources
          content:
            application/fhir+json:
              schema: { $ref: '#/components/schemas/Bundle' }
  /ExplanationOfBenefit/{id}:
    get:
      summary: Read Explanation Of Benefit by ID
      operationId: readExplanationOfBenefit
      tags: [ExplanationOfBenefit]
      parameters:
      - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: ExplanationOfBenefit resource
          content:
            application/fhir+json:
              schema: { $ref: '#/components/schemas/ExplanationOfBenefit' }
  /userinfo:
    get:
      summary: Get Beneficiary User Info
      operationId: getUserinfo
      description: OpenID Connect userinfo endpoint returning beneficiary identity claims.
      tags: [Auth]
      responses:
        '200':
          description: User info claims
          content:
            application/json:
              schema:
                type: object
                properties:
                  sub: { type: string }
                  patient: { type: string }
                  name: { type: string }
                  given_name: { type: string }
                  family_name: { type: string }
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.bluebutton.cms.gov/v2/o/authorize/
          tokenUrl: https://api.bluebutton.cms.gov/v2/o/token/
          scopes:
            patient/Patient.read: Read Patient resource
            patient/Coverage.read: Read Coverage resources
            patient/ExplanationOfBenefit.read: Read ExplanationOfBenefit resources
            profile: OpenID profile claims
  schemas:
    Bundle:
      type: object
      properties:
        resourceType: { type: string, enum: [Bundle] }
        type: { type: string }
        total: { type: integer }
        link: { type: array, items: { type: object } }
        entry:
          type: array
          items:
            type: object
            properties:
              resource: { type: object }
              fullUrl: { type: string }
    Patient:
      type: object
      properties:
        resourceType: { type: string, enum: [Patient] }
        id: { type: string }
        identifier: { type: array, items: { type: object } }
        name: { type: array, items: { type: object } }
        gender: { type: string, enum: [male, female, other, unknown] }
        birthDate: { type: string, format: date }
        address: { type: array, items: { type: object } }
    Coverage:
      type: object
      properties:
        resourceType: { type: string, enum: [Coverage] }
        id: { type: string }
        status: { type: string, enum: [active, cancelled, draft, entered-in-error] }
        type: { type: object }
        beneficiary: { type: object }
        relationship: { type: object }
        period: { type: object }
        payor: { type: array, items: { type: object } }
    ExplanationOfBenefit:
      type: object
      properties:
        resourceType: { type: string, enum: [ExplanationOfBenefit] }
        id: { type: string }
        status: { type: string }
        type: { type: object }
        use: { type: string }
        patient: { type: object }
        billablePeriod: { type: object }
        created: { type: string, format: date-time }
        insurer: { type: object }
        provider: { type: object }
        diagnosis: { type: array, items: { type: object } }
        procedure: { type: array, items: { type: object } }
        item: { type: array, items: { type: object } }
        total: { type: array, items: { type: object } }
        payment: { type: object }
    CapabilityStatement:
      type: object
      properties:
        resourceType: { type: string, enum: [CapabilityStatement] }
        status: { type: string }
        fhirVersion: { type: string, enum: ['4.0.1'] }
        format: { type: array, items: { type: string } }
        rest: { type: array, items: { type: object } }