openapi: 3.1.0
info:
  title: UnitedHealthcare Interoperability Claims Provider Directory 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: Provider Directory
  description: FHIR R4 Provider Directory API for network information
paths:
  /Practitioner:
    get:
      operationId: listPractitioners
      summary: UnitedHealthcare List Practitioners in Directory
      description: Search the UnitedHealthcare FHIR R4 Provider Directory for practitioners (individual providers) by name, specialty, location, or network participation. Implements the Da Vinci PDex Plan Net IG.
      tags:
      - Provider Directory
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: return 'DEFAULT';
      parameters:
      - name: name
        in: query
        required: false
        description: Provider name search string
        schema:
          type: string
      - name: specialty
        in: query
        required: false
        description: NUCC taxonomy code for specialty
        schema:
          type: string
      - name: address-state
        in: query
        required: false
        description: State code for location filter
        schema:
          type: string
      - name: _count
        in: query
        required: false
        description: Maximum number of results
        schema:
          type: integer
          default: 20
          maximum: 100
      responses:
        '200':
          description: FHIR Bundle of Practitioner resources
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/FHIRBundle'
        '401':
          description: Unauthorized
        '429':
          description: Too many requests
  /Organization:
    get:
      operationId: listOrganizations
      summary: UnitedHealthcare List Organizations in Directory
      description: Search the UnitedHealthcare FHIR R4 Provider Directory for healthcare organizations including hospitals, clinics, and group practices by name, type, or location. Implements the Da Vinci PDex Plan Net IG.
      tags:
      - Provider Directory
      x-microcks-operation:
        dispatcher: SCRIPT
        dispatcherRules: return 'DEFAULT';
      parameters:
      - name: name
        in: query
        required: false
        description: Organization name search string
        schema:
          type: string
      - name: type
        in: query
        required: false
        description: Organization type code
        schema:
          type: string
      - name: address-state
        in: query
        required: false
        description: State code for location filter
        schema:
          type: string
      - name: _count
        in: query
        required: false
        description: Maximum number of results
        schema:
          type: integer
          default: 20
          maximum: 100
      responses:
        '200':
          description: FHIR Bundle of Organization resources
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/FHIRBundle'
        '401':
          description: Unauthorized
        '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
  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