openapi: 3.1.0
info:
  title: UnitedHealthcare Interoperability Claims Prior Authorization 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: Prior Authorization
  description: Prior authorization and referral actions
paths:
  /prior-auth/v1/check:
    post:
      operationId: checkPriorAuth
      summary: UnitedHealthcare Real Prior Auth Check
      description: Check if a prior authorization or referral is required for a specific service and procedure, and determine the authorization status for a UnitedHealthcare member.
      tags:
      - Prior Authorization
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: return 'NOT_REQUIRED';
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriorAuthCheckRequest'
            x-microcks-default: "{\n  \"memberId\": \"123456789\",\n  \"npi\": \"1234567890\",\n  \"serviceCode\": \"27447\",\n  \"serviceType\": \"Surgery\",\n  \"dateOfService\": \"2026-06-01\"\n}\n"
      responses:
        '200':
          description: Prior authorization requirement result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriorAuthCheckResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Member not found
        '429':
          description: Too many requests
components:
  schemas:
    PriorAuthCheckRequest:
      type: object
      description: Request to check prior authorization requirements
      required:
      - memberId
      - npi
      - serviceCode
      properties:
        memberId:
          type: string
          description: Member ID
        npi:
          type: string
          description: Provider NPI
        serviceCode:
          type: string
          description: CPT/HCPCS service code
        serviceType:
          type: string
          description: Service type description
        dateOfService:
          type: string
          format: date
          description: Planned date of service
        diagnosisCodes:
          type: array
          description: Supporting ICD-10 diagnosis codes
          items:
            type: string
        placeOfService:
          type: string
          description: Place of service code
    PriorAuthCheckResponse:
      type: object
      description: Prior authorization requirement response
      properties:
        authorizationRequired:
          type: boolean
          description: Whether prior authorization is required
        authorizationStatus:
          type: string
          enum:
          - NOT_REQUIRED
          - REQUIRED
          - APPROVED
          - PENDING
          - DENIED
          description: Authorization status
        authorizationNumber:
          type: string
          description: Authorization number if already approved
        validFromDate:
          type: string
          format: date
          description: Authorization valid from date
        validToDate:
          type: string
          format: date
          description: Authorization valid to date
        approvedUnits:
          type: integer
          description: Number of approved units/visits
        referralRequired:
          type: boolean
          description: Whether a referral is required
  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