openapi: 3.1.0
info:
  title: UnitedHealthcare Interoperability Claims 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: Claims
  description: Claim pre-check, submission, and inquiry
paths:
  /claims/v1/pre-check:
    post:
      operationId: claimPreCheck
      summary: UnitedHealthcare Real Claim Pre-Check
      description: Validate a claim before submission to identify potential issues including missing information, coverage gaps, authorization requirements, and billing edits. Reduces claim denials and accelerates payment.
      tags:
      - Claims
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: return 'VALID';
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClaimPreCheckRequest'
            x-microcks-default: "{\n  \"memberId\": \"123456789\",\n  \"npi\": \"1234567890\",\n  \"serviceDate\": \"2026-05-03\",\n  \"diagnosisCodes\": [\"J06.9\"],\n  \"procedureCodes\": [\"99213\"],\n  \"charges\": 150.00\n}\n"
      responses:
        '200':
          description: Claim pre-check result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimPreCheckResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '422':
          description: Validation failed
        '429':
          description: Too many requests
  /claims/v1/inquiry:
    post:
      operationId: inquireClaim
      summary: UnitedHealthcare Real Claim Inquiry
      description: Retrieve the status and details of submitted claims including payment information, denial reasons, adjustment codes, and explanation of benefits data for a member or provider.
      tags:
      - Claims
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: return 'PROCESSED';
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClaimInquiryRequest'
            x-microcks-default: "{\n  \"claimNumber\": \"CLM-2026-001234\",\n  \"npi\": \"1234567890\",\n  \"memberId\": \"123456789\",\n  \"dateOfServiceFrom\": \"2026-01-01\",\n  \"dateOfServiceTo\": \"2026-05-03\"\n}\n"
      responses:
        '200':
          description: Claim inquiry result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimInquiryResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Claim not found
        '429':
          description: Too many requests
components:
  schemas:
    ClaimInquiryRequest:
      type: object
      description: Request for claim status inquiry
      properties:
        claimNumber:
          type: string
          description: UHC claim number
        npi:
          type: string
          description: Provider NPI
        memberId:
          type: string
          description: Member ID
        dateOfServiceFrom:
          type: string
          format: date
          description: Start date for service date range
        dateOfServiceTo:
          type: string
          format: date
          description: End date for service date range
    ClaimPreCheckResponse:
      type: object
      description: Claim pre-check validation result
      properties:
        validationStatus:
          type: string
          enum:
          - VALID
          - ERRORS
          - WARNINGS
          description: Overall validation status
        errors:
          type: array
          description: Validation errors that will cause denial
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
        warnings:
          type: array
          description: Validation warnings that may cause issues
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
        estimatedPayment:
          type: number
          format: float
          description: Estimated payment if claim is valid
    ClaimInquiryResponse:
      type: object
      description: Claim inquiry response
      properties:
        claimNumber:
          type: string
          description: UHC claim number
        claimStatus:
          type: string
          enum:
          - RECEIVED
          - IN_PROCESS
          - PROCESSED
          - DENIED
          - ADJUSTED
          - REVERSED
          description: Current claim status
        serviceDate:
          type: string
          format: date
          description: Date of service
        billedAmount:
          type: number
          format: float
          description: Total billed charges
        allowedAmount:
          type: number
          format: float
          description: Allowed amount
        paidAmount:
          type: number
          format: float
          description: Amount paid to provider
        patientResponsibility:
          type: number
          format: float
          description: Patient responsibility amount
        paymentDate:
          type: string
          format: date
          description: Date of payment
        checkNumber:
          type: string
          description: Payment check or EFT trace number
        denialReasonCode:
          type: string
          description: Reason code if claim was denied
        denialReasonDescription:
          type: string
          description: Description of denial reason
    ClaimPreCheckRequest:
      type: object
      description: Request for claim pre-submission validation
      required:
      - memberId
      - npi
      - serviceDate
      - diagnosisCodes
      - procedureCodes
      properties:
        memberId:
          type: string
          description: Member ID
        npi:
          type: string
          description: Billing provider NPI
        serviceDate:
          type: string
          format: date
          description: Date of service
        diagnosisCodes:
          type: array
          description: ICD-10 diagnosis codes
          items:
            type: string
        procedureCodes:
          type: array
          description: CPT/HCPCS procedure codes
          items:
            type: string
        charges:
          type: number
          format: float
          description: Total billed charges
        placeOfService:
          type: string
          description: Place of service code
  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