openapi: 3.1.0
info:
  title: UnitedHealthcare Interoperability 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
externalDocs:
  description: UnitedHealthcare Interoperability APIs Documentation
  url: https://www.uhc.com/legal/interoperability-apis
servers:
  - url: https://api.uhc.com/fhir/R4
    description: Production FHIR R4 Endpoint
tags:
  - name: Patient Access
    description: FHIR R4 Patient Access API for member health data
  - name: Provider Directory
    description: FHIR R4 Provider Directory API for network information
  - name: Formulary
    description: Drug formulary and coverage information
security:
  - bearerAuth: []
paths:
  /Patient/{id}:
    get:
      operationId: getPatient
      summary: UnitedHealthcare Get Patient Demographics
      description: >-
        Retrieve FHIR R4 Patient resource for a UnitedHealthcare member including
        demographic information, identifiers, and contact details as required by
        the CMS Patient Access rule.
      tags:
        - Patient Access
      x-microcks-operation:
        dispatcher: URI_PARTS
        dispatcherRules: id
      parameters:
        - name: id
          in: path
          required: true
          description: FHIR Patient resource ID (member ID)
          schema:
            type: string
      responses:
        '200':
          description: FHIR Patient resource
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/FHIRPatient'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Patient not found
        '429':
          description: Too many requests
  /ExplanationOfBenefit:
    get:
      operationId: listExplanationOfBenefit
      summary: UnitedHealthcare List Explanation of Benefits
      description: >-
        Retrieve FHIR R4 ExplanationOfBenefit resources for a member, providing
        claims data including services rendered, amounts billed, allowed amounts,
        and payment details as required by CMS interoperability rules.
      tags:
        - Patient Access
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: "return 'DEFAULT';"
      parameters:
        - name: patient
          in: query
          required: true
          description: Patient resource ID to retrieve EOBs for
          schema:
            type: string
        - name: _lastUpdated
          in: query
          required: false
          description: Filter by last updated date (FHIR date parameter)
          schema:
            type: string
        - name: type
          in: query
          required: false
          description: Filter by claim type (professional, institutional, pharmacy)
          schema:
            type: string
        - name: _count
          in: query
          required: false
          description: Maximum number of results to return
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: FHIR Bundle of ExplanationOfBenefit resources
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/FHIRBundle'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '429':
          description: Too many requests
  /Coverage:
    get:
      operationId: listCoverage
      summary: UnitedHealthcare List Coverage
      description: >-
        Retrieve FHIR R4 Coverage resources for a member including current and
        historical insurance coverage details, plan information, and benefit periods.
      tags:
        - Patient Access
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: "return 'DEFAULT';"
      parameters:
        - name: patient
          in: query
          required: true
          description: Patient resource ID
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Coverage status filter (active, cancelled, draft)
          schema:
            type: string
            enum:
              - active
              - cancelled
              - draft
              - entered-in-error
      responses:
        '200':
          description: FHIR Bundle of Coverage resources
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/FHIRBundle'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Too many requests
  /Practitioner:
    get:
      operationId: listPractitioners
      summary: UnitedHealthcare List Practitioners in Directory
      description: >-
        Search the UnitedHealthcare FHIR R4 Provider Directory for practitioners
        (individual providers) by name, specialty, location, or network participation.
        Implements the Da Vinci PDex Plan Net IG.
      tags:
        - Provider Directory
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: "return 'DEFAULT';"
      parameters:
        - name: name
          in: query
          required: false
          description: Provider name search string
          schema:
            type: string
        - name: specialty
          in: query
          required: false
          description: NUCC taxonomy code for specialty
          schema:
            type: string
        - name: address-state
          in: query
          required: false
          description: State code for location 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 Practitioner resources
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/FHIRBundle'
        '401':
          description: Unauthorized
        '429':
          description: Too many requests
  /Organization:
    get:
      operationId: listOrganizations
      summary: UnitedHealthcare List Organizations in Directory
      description: >-
        Search the UnitedHealthcare FHIR R4 Provider Directory for healthcare
        organizations including hospitals, clinics, and group practices by name,
        type, or location. Implements the Da Vinci PDex Plan Net IG.
      tags:
        - Provider Directory
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: "return 'DEFAULT';"
      parameters:
        - name: name
          in: query
          required: false
          description: Organization name search string
          schema:
            type: string
        - name: type
          in: query
          required: false
          description: Organization type code
          schema:
            type: string
        - name: address-state
          in: query
          required: false
          description: State code for location 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 Organization resources
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/FHIRBundle'
        '401':
          description: Unauthorized
        '429':
          description: Too many requests
  /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:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token for FHIR API access
  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
    FHIRPatient:
      type: object
      description: FHIR R4 Patient resource representing a UnitedHealthcare member
      properties:
        resourceType:
          type: string
          enum:
            - Patient
          description: FHIR resource type
        id:
          type: string
          description: Patient resource ID
        identifier:
          type: array
          description: Patient identifiers (member ID, etc.)
          items:
            type: object
            properties:
              system:
                type: string
              value:
                type: string
        name:
          type: array
          description: Patient names
          items:
            type: object
            properties:
              use:
                type: string
              family:
                type: string
              given:
                type: array
                items:
                  type: string
        birthDate:
          type: string
          format: date
          description: Patient date of birth
        gender:
          type: string
          enum:
            - male
            - female
            - other
            - unknown
          description: Administrative gender
        address:
          type: array
          description: Patient addresses
          items:
            type: object
            properties:
              line:
                type: array
                items:
                  type: string
              city:
                type: string
              state:
                type: string
              postalCode:
                type: string
        telecom:
          type: array
          description: Contact details (phone, email)
          items:
            type: object
            properties:
              system:
                type: string
              value:
                type: string
              use:
                type: string