naftiko: 1.0.0-alpha2
info:
  label: UnitedHealth Group Health Data Interoperability
  description: Workflow capability for CMS-compliant health data interoperability using UnitedHealth Group FHIR R4 APIs. Enables
    patient portals, third-party health apps, care management platforms, and provider tools to access member health records,
    claims history, coverage details, clinical conditions, provider directory, and drug formulary data. Supports CMS-9115-F
    Patient Access rule and Da Vinci implementation guides for payer data exchange.
  tags:
  - UnitedHealth Group
  - Optum
  - FHIR
  - Health Data Interoperability
  - CMS Patient Access
  - Da Vinci
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    UH_FHIR_TOKEN: UH_FHIR_TOKEN
capability:
  consumes:
  - type: http
    namespace: uh-fhir
    baseUri: https://api.uhc.com/fhir/R4
    description: UnitedHealth Group FHIR R4 Interoperability API.
    authentication:
      type: bearer
      token: '{{UH_FHIR_TOKEN}}'
    resources:
    - name: patient
      path: /Patient/{id}
      description: FHIR Patient resource.
      operations:
      - name: get-patient
        method: GET
        description: Retrieve FHIR Patient demographics for a member.
        inputParameters:
        - name: id
          in: path
          type: string
          required: true
          description: Patient resource ID.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: explanation-of-benefit
      path: /ExplanationOfBenefit
      description: FHIR ExplanationOfBenefit resources.
      operations:
      - name: list-eobs
        method: GET
        description: List claims as ExplanationOfBenefit for a patient.
        inputParameters:
        - name: patient
          in: query
          type: string
          required: true
          description: Patient ID.
        - name: type
          in: query
          type: string
          required: false
          description: Claim type filter.
        - name: _lastUpdated
          in: query
          type: string
          required: false
          description: Date filter.
        - name: _count
          in: query
          type: string
          required: false
          description: Max results.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: coverage
      path: /Coverage
      description: FHIR Coverage resources.
      operations:
      - name: list-coverage
        method: GET
        description: List insurance coverage for a patient.
        inputParameters:
        - name: patient
          in: query
          type: string
          required: true
          description: Patient ID.
        - name: status
          in: query
          type: string
          required: false
          description: Coverage status.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: condition
      path: /Condition
      description: FHIR Condition resources.
      operations:
      - name: list-conditions
        method: GET
        description: List health conditions for a patient.
        inputParameters:
        - name: patient
          in: query
          type: string
          required: true
          description: Patient ID.
        - name: clinical-status
          in: query
          type: string
          required: false
          description: Clinical status filter.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: practitioner
      path: /Practitioner
      description: FHIR Practitioner provider directory.
      operations:
      - name: list-practitioners
        method: GET
        description: Search provider directory for practitioners.
        inputParameters:
        - name: name
          in: query
          type: string
          required: false
          description: Provider name.
        - name: identifier
          in: query
          type: string
          required: false
          description: NPI.
        - name: specialty
          in: query
          type: string
          required: false
          description: Specialty code.
        - name: address-state
          in: query
          type: string
          required: false
          description: State filter.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: formulary
      path: /MedicationKnowledge
      description: FHIR Drug Formulary.
      operations:
      - name: list-formulary
        method: GET
        description: Search drug formulary coverage.
        inputParameters:
        - name: code
          in: query
          type: string
          required: false
          description: RxNorm drug code.
        - name: drug-name
          in: query
          type: string
          required: false
          description: Drug name.
        - name: tier
          in: query
          type: string
          required: false
          description: Formulary tier.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: uh-interoperability-api
    description: Unified REST API for UnitedHealth Group FHIR interoperability.
    resources:
    - path: /v1/members/{id}
      name: member
      description: Member demographics.
      operations:
      - method: GET
        name: get-member
        description: Get member FHIR Patient resource.
        call: uh-fhir.get-patient
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/members/{id}/claims
      name: claims
      description: Member claims history.
      operations:
      - method: GET
        name: list-member-claims
        description: List member claims as EOBs.
        call: uh-fhir.list-eobs
        with:
          patient: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/members/{id}/coverage
      name: coverage
      description: Member coverage.
      operations:
      - method: GET
        name: get-member-coverage
        description: Get member coverage details.
        call: uh-fhir.list-coverage
        with:
          patient: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/members/{id}/conditions
      name: conditions
      description: Member conditions.
      operations:
      - method: GET
        name: list-member-conditions
        description: List member conditions.
        call: uh-fhir.list-conditions
        with:
          patient: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/providers
      name: providers
      description: Provider directory.
      operations:
      - method: GET
        name: search-providers
        description: Search provider directory.
        call: uh-fhir.list-practitioners
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/formulary
      name: formulary
      description: Drug formulary.
      operations:
      - method: GET
        name: search-formulary
        description: Search drug formulary.
        call: uh-fhir.list-formulary
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: uh-interoperability-mcp
    transport: http
    description: MCP server for AI-assisted UnitedHealth Group FHIR data access.
    tools:
    - name: get-member-health-record
      description: Retrieve a UnitedHealth Group member's FHIR Patient record with demographics and identifiers.
      hints:
        readOnly: true
        openWorld: false
      call: uh-fhir.get-patient
      outputParameters:
      - type: object
        mapping: $.
    - name: get-member-claims-history
      description: Retrieve a member's complete claims history as FHIR ExplanationOfBenefit resources including services,
        diagnoses, and payment details.
      hints:
        readOnly: true
        openWorld: false
      call: uh-fhir.list-eobs
      with:
        patient: tools.memberId
        type: tools.claimType
        _lastUpdated: tools.since
      outputParameters:
      - type: object
        mapping: $.
    - name: get-insurance-coverage
      description: Get a member's UnitedHealth Group insurance coverage including plan name, group number, and benefit period.
      hints:
        readOnly: true
        openWorld: false
      call: uh-fhir.list-coverage
      with:
        patient: tools.memberId
        status: tools.status
      outputParameters:
      - type: object
        mapping: $.
    - name: get-member-conditions
      description: Retrieve a member's health conditions and diagnoses from UnitedHealth Group clinical records and claims
        data.
      hints:
        readOnly: true
        openWorld: false
      call: uh-fhir.list-conditions
      with:
        patient: tools.memberId
        clinical-status: tools.clinicalStatus
      outputParameters:
      - type: object
        mapping: $.
    - name: find-in-network-provider
      description: Search the UnitedHealth Group provider directory for in-network physicians, specialists, and organizations
        by name, NPI, specialty, or state.
      hints:
        readOnly: true
        openWorld: true
      call: uh-fhir.list-practitioners
      with:
        name: tools.providerName
        identifier: tools.npi
        specialty: tools.specialty
        address-state: tools.state
      outputParameters:
      - type: object
        mapping: $.
    - name: check-drug-formulary
      description: Check UnitedHealth Group drug formulary coverage tier, prior authorization requirements, and quantity limits
        for a medication.
      hints:
        readOnly: true
        openWorld: true
      call: uh-fhir.list-formulary
      with:
        code: tools.rxnormCode
        drug-name: tools.drugName
      outputParameters:
      - type: object
        mapping: $.