openapi: 3.1.0
info:
  title: UnitedHealthcare Interoperability Claims Formulary API
  description: The UnitedHealthcare Interoperability APIs provide FHIR R4-compliant access to patient health data in accordance with CMS Interoperability and Patient Access final rule (CMS-9115-F). Includes Patient Access API for member health records and claims history, and Provider Directory API for network provider information. These APIs enable patients and authorized third parties to access health data using standard FHIR resources.
  version: '1.0'
  contact:
    name: UnitedHealthcare Interoperability
    url: https://www.uhc.com/legal/interoperability-apis
  license:
    name: UnitedHealthcare API Terms of Use
    url: https://www.uhc.com/legal/interoperability-apis
servers:
- url: https://api.uhc.com/fhir/R4
  description: Production FHIR R4 Endpoint
security:
- bearerAuth: []
tags:
- name: Formulary
  description: Drug formulary and coverage information
paths:
  /MedicationKnowledge:
    get:
      operationId: listFormulary
      summary: UnitedHealthcare List Formulary Medications
      description: Retrieve drug formulary information from UnitedHealthcare's FHIR R4 Formulary API including drug coverage tiers, prior authorization requirements, quantity limits, and step therapy requirements.
      tags:
      - Formulary
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: return 'DEFAULT';
      parameters:
      - name: code
        in: query
        required: false
        description: RxNorm drug code
        schema:
          type: string
      - name: drug-name
        in: query
        required: false
        description: Drug name search string
        schema:
          type: string
      - name: tier
        in: query
        required: false
        description: Formulary tier filter
        schema:
          type: string
      - name: _count
        in: query
        required: false
        description: Maximum number of results
        schema:
          type: integer
          default: 20
          maximum: 100
      responses:
        '200':
          description: FHIR Bundle of MedicationKnowledge resources
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/FHIRBundle'
        '401':
          description: Unauthorized
        '429':
          description: Too many requests
components:
  schemas:
    FHIRBundle:
      type: object
      description: FHIR R4 Bundle resource containing a collection of FHIR resources
      properties:
        resourceType:
          type: string
          enum:
          - Bundle
          description: FHIR resource type
        id:
          type: string
          description: Bundle ID
        type:
          type: string
          enum:
          - searchset
          - collection
          - document
          description: Bundle type
        total:
          type: integer
          description: Total number of matching resources
        link:
          type: array
          description: Navigation links (self, next, previous)
          items:
            type: object
            properties:
              relation:
                type: string
              url:
                type: string
        entry:
          type: array
          description: Bundle entries containing FHIR resources
          items:
            type: object
            properties:
              fullUrl:
                type: string
              resource:
                type: object
              search:
                type: object
                properties:
                  mode:
                    type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token for FHIR API access
externalDocs:
  description: UnitedHealthcare Interoperability APIs Documentation
  url: https://www.uhc.com/legal/interoperability-apis