openapi: 3.1.0
info:
  title: UnitedHealthcare Interoperability Claims Eligibility 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: Eligibility
  description: Real-time eligibility and benefit verification
paths:
  /eligibility/v1/real-time:
    post:
      operationId: checkEligibility
      summary: UnitedHealthcare Real-Time Eligibility Check
      description: Perform a real-time pre-service eligibility and benefit verification for a UnitedHealthcare member. Returns coverage details, deductibles, copays, and benefit limits for a specific service type and date of service.
      tags:
      - Eligibility
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: return 'ACTIVE';
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EligibilityRequest'
            x-microcks-default: "{\n  \"memberId\": \"123456789\",\n  \"dateOfBirth\": \"1980-01-15\",\n  \"serviceType\": \"30\",\n  \"dateOfService\": \"2026-05-03\",\n  \"npi\": \"1234567890\"\n}\n"
      responses:
        '200':
          description: Eligibility verification result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EligibilityResponse'
        '400':
          description: Bad request - invalid input
        '401':
          description: Unauthorized - invalid or missing token
        '404':
          description: Member not found
        '429':
          description: Too many requests
  /eligibility/v1/patient-benefit-check:
    post:
      operationId: checkPatientBenefit
      summary: UnitedHealthcare Real Patient Benefit Check
      description: Check specific patient benefit details for a given service including covered benefits, cost-sharing information, network status, and utilization management requirements.
      tags:
      - Eligibility
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: return 'COVERED';
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BenefitCheckRequest'
            x-microcks-default: "{\n  \"memberId\": \"123456789\",\n  \"dateOfBirth\": \"1980-01-15\",\n  \"serviceCode\": \"99213\",\n  \"dateOfService\": \"2026-05-03\",\n  \"npi\": \"1234567890\",\n  \"providerTaxId\": \"12-3456789\"\n}\n"
      responses:
        '200':
          description: Benefit check result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenefitCheckResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Member not found
        '429':
          description: Too many requests
components:
  schemas:
    BenefitCheckResponse:
      type: object
      description: Patient benefit check response
      properties:
        coveredBenefit:
          type: boolean
          description: Whether the service is a covered benefit
        authorizationRequired:
          type: boolean
          description: Whether prior authorization is required
        referralRequired:
          type: boolean
          description: Whether a referral is required
        estimatedPatientResponsibility:
          type: number
          format: float
          description: Estimated patient cost responsibility
        estimatedPlanPayment:
          type: number
          format: float
          description: Estimated plan payment amount
        costSharingDetails:
          type: object
          description: Detailed cost-sharing breakdown
          properties:
            copay:
              type: number
              format: float
            coinsurance:
              type: number
              format: float
            deductibleApplies:
              type: boolean
    EligibilityResponse:
      type: object
      description: Real-time eligibility verification response
      properties:
        memberId:
          type: string
          description: UnitedHealthcare member ID
        memberName:
          type: string
          description: Member full name
        coverageStatus:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
          - TERMED
          description: Current coverage status
        planName:
          type: string
          description: Insurance plan name
        groupNumber:
          type: string
          description: Group number
        effectiveDate:
          type: string
          format: date
          description: Coverage effective date
        terminationDate:
          type: string
          format: date
          description: Coverage termination date
        deductible:
          type: number
          format: float
          description: Annual deductible amount
        deductibleMet:
          type: number
          format: float
          description: Year-to-date deductible amount met
        outOfPocketMax:
          type: number
          format: float
          description: Annual out-of-pocket maximum
        outOfPocketMet:
          type: number
          format: float
          description: Year-to-date out-of-pocket amount met
        copay:
          type: number
          format: float
          description: Copay amount for the service type
        coinsurance:
          type: number
          format: float
          description: Coinsurance percentage (0-100)
        networkStatus:
          type: string
          enum:
          - IN_NETWORK
          - OUT_OF_NETWORK
          - UNKNOWN
          description: Provider network participation status
    BenefitCheckRequest:
      type: object
      description: Request for patient-specific benefit check
      required:
      - memberId
      - dateOfBirth
      - serviceCode
      - dateOfService
      properties:
        memberId:
          type: string
          description: UnitedHealthcare member ID
        dateOfBirth:
          type: string
          format: date
          description: Member date of birth
        serviceCode:
          type: string
          description: CPT/HCPCS service code
        dateOfService:
          type: string
          format: date
          description: Date of service
        npi:
          type: string
          description: Rendering provider NPI
        providerTaxId:
          type: string
          description: Provider tax ID
        placeOfService:
          type: string
          description: Place of service code
    EligibilityRequest:
      type: object
      description: Request parameters for real-time eligibility verification
      required:
      - memberId
      - dateOfBirth
      - serviceType
      - dateOfService
      properties:
        memberId:
          type: string
          description: UnitedHealthcare member ID
        dateOfBirth:
          type: string
          format: date
          description: Member date of birth (YYYY-MM-DD)
        serviceType:
          type: string
          description: Service type code (X12 270/271 service type codes)
        dateOfService:
          type: string
          format: date
          description: Requested date of service
        npi:
          type: string
          description: Rendering provider NPI
        groupNumber:
          type: string
          description: Insurance group number
  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