UnitedHealthcare Patient Access API

openapi: 3.1.0
info:
  title: UnitedHealthcare Interoperability Claims Patient Access 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: Patient Access
  description: FHIR R4 Patient Access API for member health data
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
components:
  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
  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