openapi: 3.0.3
info:
  title: Kareo Integration SOAP API
  description: >-
    The Kareo Integration SOAP API provides a web services interface for
    integrating third-party applications with Kareo practice management data.
    This OpenAPI description is derived from the publicly accessible WSDL at
    https://webservice.kareo.com/services/soap/2.1/KareoServices.svc?wsdl.
    The underlying service is SOAP/XML-based; this document describes the
    logical operations and data shapes for reference and tooling purposes.
    Authentication requires a CustomerKey, Username, and Password issued by a
    Kareo System Administrator. Kareo is now part of Tebra.
  version: "2.1"
  contact:
    name: Kareo / Tebra Support
    url: https://helpme.tebra.com/01_Kareo_PM/12_API_and_Integration
  termsOfService: https://www.tebra.com/api-terms-of-use/
  x-api-type: SOAP
  x-wsdl-url: https://webservice.kareo.com/services/soap/2.1/KareoServices.svc?wsdl
externalDocs:
  description: Kareo API and Integration Documentation
  url: https://helpme.tebra.com/01_Kareo_PM/12_API_and_Integration
servers:
  - url: https://webservice.kareo.com/services/soap/2.1
    description: Kareo SOAP Web Service (production)
tags:
  - name: Patients
    description: Patient demographic and record management
  - name: Appointments
    description: Appointment scheduling and management
  - name: Encounters
    description: Clinical encounter and document management
  - name: Billing
    description: Charges, payments, and transactions
  - name: Providers
    description: Provider and practice administration
  - name: Administrative
    description: Vendor registration, throttles, and configuration
paths:
  /KareoServices.svc/CreatePatient:
    post:
      operationId: createPatient
      summary: Create a new patient record
      description: >-
        Creates a new patient record in Kareo practice management. Returns the
        newly created patient identifier. Requires CustomerKey authentication.
      tags:
        - Patients
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/CreatePatientRequest'
      responses:
        '200':
          description: Patient created successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/CreatePatientResponse'
        '401':
          description: Authentication failed - invalid CustomerKey, username, or password
        '400':
          description: Bad request - invalid patient data
  /KareoServices.svc/UpdatePatient:
    post:
      operationId: updatePatient
      summary: Update an existing patient record
      description: >-
        Updates demographic and contact information for an existing patient
        record identified by PatientId or PatientExternalId.
      tags:
        - Patients
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/UpdatePatientRequest'
      responses:
        '200':
          description: Patient updated successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/UpdatePatientResponse'
        '401':
          description: Authentication failed
        '404':
          description: Patient not found
  /KareoServices.svc/GetPatient:
    post:
      operationId: getPatient
      summary: Retrieve a single patient record
      description: >-
        Retrieves a single patient record by PatientId or PatientExternalId.
      tags:
        - Patients
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/GetPatientRequest'
      responses:
        '200':
          description: Patient record retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetPatientResponse'
        '401':
          description: Authentication failed
        '404':
          description: Patient not found
  /KareoServices.svc/GetPatients:
    post:
      operationId: getPatients
      summary: Retrieve multiple patient records with filters
      description: >-
        Retrieves a filtered list of patient records. Supports filtering by
        LastModifiedDate range and other criteria.
      tags:
        - Patients
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/GetPatientsRequest'
      responses:
        '200':
          description: Patient list retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetPatientsResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/GetAllPatients:
    post:
      operationId: getAllPatients
      summary: Retrieve all patient records for a practice
      description: >-
        Retrieves all patient records for the authenticated practice. Use with
        caution on large datasets; consider GetPatients with date filters.
      tags:
        - Patients
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/GetAllPatientsRequest'
      responses:
        '200':
          description: All patients retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetPatientsResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/UpdatePatientsExternalID:
    post:
      operationId: updatePatientsExternalID
      summary: Update external identifier for patients
      description: >-
        Bulk updates the external identifier field for one or more patient
        records, enabling synchronization with external systems.
      tags:
        - Patients
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/UpdatePatientsExternalIDRequest'
      responses:
        '200':
          description: External IDs updated successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/UpdatePatientsExternalIDResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/CreateAppointment:
    post:
      operationId: createAppointment
      summary: Create a new appointment
      description: >-
        Schedules a new appointment for a patient with a specified provider at
        a service location. Returns the appointment identifier.
      tags:
        - Appointments
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/CreateAppointmentRequest'
      responses:
        '200':
          description: Appointment created successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/CreateAppointmentResponse'
        '401':
          description: Authentication failed
        '409':
          description: Scheduling conflict
  /KareoServices.svc/UpdateAppointment:
    post:
      operationId: updateAppointment
      summary: Update an existing appointment
      description: >-
        Updates the details of an existing appointment including date, time,
        provider, or service location.
      tags:
        - Appointments
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/UpdateAppointmentRequest'
      responses:
        '200':
          description: Appointment updated
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/UpdateAppointmentResponse'
        '401':
          description: Authentication failed
        '404':
          description: Appointment not found
  /KareoServices.svc/DeleteAppointment:
    post:
      operationId: deleteAppointment
      summary: Delete an appointment
      description: Cancels and removes an appointment record by appointment identifier.
      tags:
        - Appointments
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/DeleteAppointmentRequest'
      responses:
        '200':
          description: Appointment deleted
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/DeleteAppointmentResponse'
        '401':
          description: Authentication failed
        '404':
          description: Appointment not found
  /KareoServices.svc/UpdateAppointmentStatus:
    post:
      operationId: updateAppointmentStatus
      summary: Update appointment status
      description: >-
        Updates the status of an appointment (e.g., Confirmed, Cancelled,
        No-Show, Checked-In).
      tags:
        - Appointments
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/UpdateAppointmentStatusRequest'
      responses:
        '200':
          description: Appointment status updated
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/UpdateAppointmentStatusResponse'
        '401':
          description: Authentication failed
        '404':
          description: Appointment not found
  /KareoServices.svc/GetAppointment:
    post:
      operationId: getAppointment
      summary: Retrieve a single appointment
      description: Retrieves a single appointment record by appointment identifier.
      tags:
        - Appointments
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/GetAppointmentRequest'
      responses:
        '200':
          description: Appointment retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetAppointmentResponse'
        '401':
          description: Authentication failed
        '404':
          description: Appointment not found
  /KareoServices.svc/GetAppointments:
    post:
      operationId: getAppointments
      summary: Retrieve appointments with filters
      description: >-
        Retrieves a filtered list of appointments. Supports filtering by date
        range, provider, patient, and status. Recommended polling interval is
        5-15 minutes for integrations.
      tags:
        - Appointments
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/GetAppointmentsRequest'
      responses:
        '200':
          description: Appointments retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetAppointmentsResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/CreateAppointmentReason:
    post:
      operationId: createAppointmentReason
      summary: Create an appointment reason/type
      description: Creates a new appointment reason code for use in scheduling.
      tags:
        - Appointments
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/CreateAppointmentReasonRequest'
      responses:
        '200':
          description: Appointment reason created
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/CreateAppointmentReasonResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/GetAppointmentReasons:
    post:
      operationId: getAppointmentReasons
      summary: Retrieve appointment reasons
      description: Retrieves the list of configured appointment reason codes for the practice.
      tags:
        - Appointments
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/GetAppointmentReasonsRequest'
      responses:
        '200':
          description: Appointment reasons retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetAppointmentReasonsResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/CreateEncounter:
    post:
      operationId: createEncounter
      summary: Create a clinical encounter
      description: >-
        Creates a new clinical encounter record linking a patient visit to
        diagnoses, procedures, and billing codes.
      tags:
        - Encounters
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/CreateEncounterRequest'
      responses:
        '200':
          description: Encounter created
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/CreateEncounterResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/UpdateEncounterStatus:
    post:
      operationId: updateEncounterStatus
      summary: Update encounter status
      description: >-
        Updates the workflow status of an encounter (e.g., Draft, Submitted,
        Approved).
      tags:
        - Encounters
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/UpdateEncounterStatusRequest'
      responses:
        '200':
          description: Encounter status updated
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/UpdateEncounterStatusResponse'
        '401':
          description: Authentication failed
        '404':
          description: Encounter not found
  /KareoServices.svc/GetEncounterDetails:
    post:
      operationId: getEncounterDetails
      summary: Retrieve encounter details
      description: >-
        Retrieves detailed information about a clinical encounter including
        diagnoses, procedures, and associated billing data.
      tags:
        - Encounters
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/GetEncounterDetailsRequest'
      responses:
        '200':
          description: Encounter details retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetEncounterDetailsResponse'
        '401':
          description: Authentication failed
        '404':
          description: Encounter not found
  /KareoServices.svc/UpdatePrimaryPatientCase:
    post:
      operationId: updatePrimaryPatientCase
      summary: Update the primary case for a patient
      description: >-
        Updates the primary insurance case and billing information associated
        with a patient's account.
      tags:
        - Encounters
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/UpdatePrimaryPatientCaseRequest'
      responses:
        '200':
          description: Patient case updated
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/UpdatePrimaryPatientCaseResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/CreateDocument:
    post:
      operationId: createDocument
      summary: Create a clinical document
      description: >-
        Attaches or creates a document record in the Kareo EHR associated with
        a patient or encounter.
      tags:
        - Encounters
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/CreateDocumentRequest'
      responses:
        '200':
          description: Document created
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/CreateDocumentResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/DeleteDocument:
    post:
      operationId: deleteDocument
      summary: Delete a clinical document
      description: Removes a document record from a patient or encounter in the Kareo EHR.
      tags:
        - Encounters
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/DeleteDocumentRequest'
      responses:
        '200':
          description: Document deleted
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/DeleteDocumentResponse'
        '401':
          description: Authentication failed
        '404':
          description: Document not found
  /KareoServices.svc/CreatePayment:
    post:
      operationId: createPayment
      summary: Post a payment
      description: >-
        Posts a patient or insurance payment to a patient account or specific
        charge in Kareo.
      tags:
        - Billing
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
      responses:
        '200':
          description: Payment posted
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/CreatePaymentResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/GetPayments:
    post:
      operationId: getPayments
      summary: Retrieve payment records
      description: >-
        Retrieves payment records with optional date range and patient filters.
      tags:
        - Billing
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/GetPaymentsRequest'
      responses:
        '200':
          description: Payments retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetPaymentsResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/GetCharges:
    post:
      operationId: getCharges
      summary: Retrieve charge records
      description: >-
        Retrieves medical charge records (CPT/procedure codes billed) with
        optional filtering by date range and patient.
      tags:
        - Billing
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/GetChargesRequest'
      responses:
        '200':
          description: Charges retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetChargesResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/GetTransactions:
    post:
      operationId: getTransactions
      summary: Retrieve financial transactions
      description: >-
        Retrieves financial transaction records for the practice, including
        charges, payments, and adjustments.
      tags:
        - Billing
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/GetTransactionsRequest'
      responses:
        '200':
          description: Transactions retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetTransactionsResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/GetProviders:
    post:
      operationId: getProviders
      summary: Retrieve provider records
      description: >-
        Retrieves the list of healthcare providers configured in the practice.
      tags:
        - Providers
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/GetProvidersRequest'
      responses:
        '200':
          description: Providers retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetProvidersResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/GetPractices:
    post:
      operationId: getPractices
      summary: Retrieve practice records
      description: >-
        Retrieves practice information for the authenticated account, including
        name, address, and NPI.
      tags:
        - Providers
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/GetPracticesRequest'
      responses:
        '200':
          description: Practices retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetPracticesResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/GetServiceLocations:
    post:
      operationId: getServiceLocations
      summary: Retrieve service locations
      description: >-
        Retrieves the list of service locations (offices, facilities) configured
        for the practice.
      tags:
        - Providers
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/GetServiceLocationsRequest'
      responses:
        '200':
          description: Service locations retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetServiceLocationsResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/GetProcedureCodes:
    post:
      operationId: getProcedureCodes
      summary: Retrieve procedure codes
      description: >-
        Retrieves the CPT/procedure code list configured for the practice for
        use in encounter and charge creation.
      tags:
        - Providers
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/GetProcedureCodesRequest'
      responses:
        '200':
          description: Procedure codes retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetProcedureCodesResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/RegisterExternalVendor:
    post:
      operationId: registerExternalVendor
      summary: Register an external vendor integration
      description: >-
        Registers a third-party vendor or integration application with the
        Kareo platform to receive a CustomerKey for API access.
      tags:
        - Administrative
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/RegisterExternalVendorRequest'
      responses:
        '200':
          description: External vendor registered
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/RegisterExternalVendorResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/GetExternalVendors:
    post:
      operationId: getExternalVendors
      summary: Retrieve registered external vendors
      description: >-
        Retrieves the list of external vendor integrations registered with
        the practice.
      tags:
        - Administrative
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/GetExternalVendorsRequest'
      responses:
        '200':
          description: External vendors retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetExternalVendorsResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/GetThrottles:
    post:
      operationId: getThrottles
      summary: Retrieve API throttle limits
      description: >-
        Returns the current API request throttle limits and usage for the
        authenticated practice to support rate-limit-aware integrations.
      tags:
        - Administrative
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/GetThrottlesRequest'
      responses:
        '200':
          description: Throttle limits retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetThrottlesResponse'
        '401':
          description: Authentication failed
  /KareoServices.svc/GetCustomerIdFromKey:
    post:
      operationId: getCustomerIdFromKey
      summary: Resolve customer identifier from CustomerKey
      description: >-
        Resolves the internal customer/practice identifier corresponding to a
        given CustomerKey credential.
      tags:
        - Administrative
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/GetCustomerIdFromKeyRequest'
      responses:
        '200':
          description: Customer ID retrieved
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetCustomerIdFromKeyResponse'
        '401':
          description: Authentication failed
components:
  schemas:
    RequestHeader:
      type: object
      required:
        - CustomerKey
        - User
        - Password
      properties:
        CustomerKey:
          type: string
          description: >-
            Unique key issued by the Kareo System Administrator identifying
            the practice integration.
          example: "ABC123XYZ"
        User:
          type: string
          description: Kareo username for authentication.
          example: "admin@mypractice.com"
        Password:
          type: string
          format: password
          description: Kareo password for authentication.
    Patient:
      type: object
      properties:
        PatientId:
          type: integer
          description: Internal Kareo patient identifier.
          example: 100234
        PatientExternalId:
          type: string
          description: External system identifier for the patient.
          example: "EXT-PT-9876"
        PatientFullName:
          type: string
          description: Full name of the patient (LastName, FirstName).
          example: "Doe, Jane"
        FirstName:
          type: string
          example: "Jane"
        LastName:
          type: string
          example: "Doe"
        DateOfBirth:
          type: string
          format: date
          description: Patient date of birth in YYYY-MM-DD format.
          example: "1985-03-15"
        Gender:
          type: string
          enum:
            - Male
            - Female
            - Unknown
        Email:
          type: string
          format: email
          example: "jane.doe@example.com"
        HomePhone:
          type: string
          example: "555-123-4567"
        MobilePhone:
          type: string
          example: "555-987-6543"
        Address:
          $ref: '#/components/schemas/Address'
        InsurancePolicyId:
          type: integer
          description: Internal identifier for the patient's insurance policy.
        InsurancePolicyExternalId:
          type: string
          description: External identifier for the patient's insurance policy.
        LastModifiedDate:
          type: string
          format: date-time
          description: Timestamp of the last modification to the record.
    Address:
      type: object
      properties:
        Address1:
          type: string
          example: "123 Main St"
        Address2:
          type: string
          example: "Suite 100"
        City:
          type: string
          example: "Los Angeles"
        State:
          type: string
          example: "CA"
        ZipCode:
          type: string
          example: "90001"
        Country:
          type: string
          example: "US"
    Appointment:
      type: object
      properties:
        AppointmentId:
          type: integer
          description: Internal Kareo appointment identifier.
        PatientId:
          type: integer
          description: Internal Kareo patient identifier.
        ProviderId:
          type: integer
          description: Internal Kareo provider identifier.
        ServiceLocationId:
          type: integer
          description: Internal Kareo service location identifier.
        StartTime:
          type: string
          format: date-time
          description: Appointment start date and time.
          example: "2026-06-15T09:00:00"
        EndTime:
          type: string
          format: date-time
          description: Appointment end date and time.
          example: "2026-06-15T09:30:00"
        AppointmentStatus:
          type: string
          enum:
            - Scheduled
            - Confirmed
            - CheckedIn
            - CheckedOut
            - Cancelled
            - NoShow
          example: "Scheduled"
        AppointmentReasonId:
          type: integer
          description: Identifier for the appointment reason/type.
        Notes:
          type: string
          description: Free-text notes for the appointment.
    Encounter:
      type: object
      properties:
        EncounterId:
          type: integer
          description: Internal Kareo encounter identifier.
        PatientId:
          type: integer
        ProviderId:
          type: integer
        AppointmentId:
          type: integer
        EncounterStatus:
          type: string
          enum:
            - Draft
            - Submitted
            - Approved
            - Voided
        DateOfService:
          type: string
          format: date
          example: "2026-06-15"
        DiagnosisCodes:
          type: array
          items:
            type: string
          description: ICD-10 diagnosis codes associated with the encounter.
          example:
            - "J06.9"
            - "Z00.00"
        ProcedureCodes:
          type: array
          items:
            type: string
          description: CPT procedure codes billed in the encounter.
          example:
            - "99213"
    Charge:
      type: object
      properties:
        ChargeId:
          type: integer
        PatientId:
          type: integer
        EncounterId:
          type: integer
        ProcedureCode:
          type: string
          example: "99213"
        Units:
          type: number
          example: 1
        ChargeAmount:
          type: number
          format: float
          example: 150.00
        DateOfService:
          type: string
          format: date
        InsuranceBalance:
          type: number
          format: float
        PatientBalance:
          type: number
          format: float
    Payment:
      type: object
      properties:
        PaymentId:
          type: integer
        PatientId:
          type: integer
        PaymentDate:
          type: string
          format: date
        PaymentAmount:
          type: number
          format: float
          example: 50.00
        PaymentType:
          type: string
          enum:
            - PatientPayment
            - InsurancePayment
            - Adjustment
        CheckNumber:
          type: string
        Notes:
          type: string
    Provider:
      type: object
      properties:
        ProviderId:
          type: integer
        FirstName:
          type: string
        LastName:
          type: string
        NPI:
          type: string
          description: National Provider Identifier (10-digit).
          example: "1234567890"
        Specialty:
          type: string
        IsActive:
          type: boolean
    ServiceLocation:
      type: object
      properties:
        ServiceLocationId:
          type: integer
        LocationName:
          type: string
          example: "Main Office"
        Address:
          $ref: '#/components/schemas/Address'
        Phone:
          type: string
        NPI:
          type: string
    Practice:
      type: object
      properties:
        PracticeId:
          type: integer
        PracticeName:
          type: string
        NPI:
          type: string
        Address:
          $ref: '#/components/schemas/Address'
        Phone:
          type: string
        TaxId:
          type: string
    ProcedureCode:
      type: object
      properties:
        ProcedureCodeId:
          type: integer
        Code:
          type: string
          example: "99213"
        Description:
          type: string
          example: "Office visit, established patient, moderate complexity"
        DefaultFee:
          type: number
          format: float
          example: 150.00
    AppointmentReason:
      type: object
      properties:
        AppointmentReasonId:
          type: integer
        ReasonName:
          type: string
          example: "Annual Physical"
        Duration:
          type: integer
          description: Default duration in minutes.
          example: 30
    ExternalVendor:
      type: object
      properties:
        VendorId:
          type: integer
        VendorName:
          type: string
        CustomerKey:
          type: string
        IsActive:
          type: boolean
    ThrottleLimit:
      type: object
      properties:
        OperationName:
          type: string
          description: Name of the API operation subject to throttling.
        RequestsPerHour:
          type: integer
          description: Maximum allowed requests per hour for this operation.
        CurrentUsage:
          type: integer
          description: Current request count in the rolling window.
    # Request/Response wrappers
    CreatePatientRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        Patient:
          $ref: '#/components/schemas/Patient'
    CreatePatientResponse:
      type: object
      properties:
        PatientId:
          type: integer
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    UpdatePatientRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        Patient:
          $ref: '#/components/schemas/Patient'
    UpdatePatientResponse:
      type: object
      properties:
        Success:
          type: boolean
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    GetPatientRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        PatientId:
          type: integer
        PatientExternalId:
          type: string
    GetPatientResponse:
      type: object
      properties:
        Patient:
          $ref: '#/components/schemas/Patient'
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    GetPatientsRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        LastModifiedStartDate:
          type: string
          format: date-time
        LastModifiedEndDate:
          type: string
          format: date-time
    GetPatientsResponse:
      type: object
      properties:
        Patients:
          type: array
          items:
            $ref: '#/components/schemas/Patient'
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    GetAllPatientsRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
    UpdatePatientsExternalIDRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        PatientExternalIdMappings:
          type: array
          items:
            type: object
            properties:
              PatientId:
                type: integer
              ExternalId:
                type: string
    UpdatePatientsExternalIDResponse:
      type: object
      properties:
        UpdatedCount:
          type: integer
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    CreateAppointmentRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        Appointment:
          $ref: '#/components/schemas/Appointment'
    CreateAppointmentResponse:
      type: object
      properties:
        AppointmentId:
          type: integer
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    UpdateAppointmentRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        Appointment:
          $ref: '#/components/schemas/Appointment'
    UpdateAppointmentResponse:
      type: object
      properties:
        Success:
          type: boolean
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    DeleteAppointmentRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        AppointmentId:
          type: integer
    DeleteAppointmentResponse:
      type: object
      properties:
        Success:
          type: boolean
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    UpdateAppointmentStatusRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        AppointmentId:
          type: integer
        AppointmentStatus:
          type: string
    UpdateAppointmentStatusResponse:
      type: object
      properties:
        Success:
          type: boolean
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    GetAppointmentRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        AppointmentId:
          type: integer
    GetAppointmentResponse:
      type: object
      properties:
        Appointment:
          $ref: '#/components/schemas/Appointment'
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    GetAppointmentsRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        StartDate:
          type: string
          format: date-time
        EndDate:
          type: string
          format: date-time
        ProviderId:
          type: integer
        PatientId:
          type: integer
        AppointmentStatus:
          type: string
    GetAppointmentsResponse:
      type: object
      properties:
        Appointments:
          type: array
          items:
            $ref: '#/components/schemas/Appointment'
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    CreateAppointmentReasonRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        AppointmentReason:
          $ref: '#/components/schemas/AppointmentReason'
    CreateAppointmentReasonResponse:
      type: object
      properties:
        AppointmentReasonId:
          type: integer
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    GetAppointmentReasonsRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
    GetAppointmentReasonsResponse:
      type: object
      properties:
        AppointmentReasons:
          type: array
          items:
            $ref: '#/components/schemas/AppointmentReason'
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    CreateEncounterRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        Encounter:
          $ref: '#/components/schemas/Encounter'
    CreateEncounterResponse:
      type: object
      properties:
        EncounterId:
          type: integer
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    UpdateEncounterStatusRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        EncounterId:
          type: integer
        EncounterStatus:
          type: string
    UpdateEncounterStatusResponse:
      type: object
      properties:
        Success:
          type: boolean
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    GetEncounterDetailsRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        EncounterId:
          type: integer
    GetEncounterDetailsResponse:
      type: object
      properties:
        Encounter:
          $ref: '#/components/schemas/Encounter'
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    UpdatePrimaryPatientCaseRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        PatientId:
          type: integer
        InsurancePolicyId:
          type: integer
        InsurancePolicyExternalId:
          type: string
    UpdatePrimaryPatientCaseResponse:
      type: object
      properties:
        Success:
          type: boolean
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    CreateDocumentRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        PatientId:
          type: integer
        EncounterId:
          type: integer
        DocumentName:
          type: string
        DocumentContent:
          type: string
          format: byte
          description: Base64-encoded document content.
        DocumentType:
          type: string
    CreateDocumentResponse:
      type: object
      properties:
        DocumentId:
          type: integer
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    DeleteDocumentRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        DocumentId:
          type: integer
    DeleteDocumentResponse:
      type: object
      properties:
        Success:
          type: boolean
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    CreatePaymentRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        Payment:
          $ref: '#/components/schemas/Payment'
    CreatePaymentResponse:
      type: object
      properties:
        PaymentId:
          type: integer
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    GetPaymentsRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        StartDate:
          type: string
          format: date-time
        EndDate:
          type: string
          format: date-time
        PatientId:
          type: integer
    GetPaymentsResponse:
      type: object
      properties:
        Payments:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    GetChargesRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        StartDate:
          type: string
          format: date-time
        EndDate:
          type: string
          format: date-time
        PatientId:
          type: integer
    GetChargesResponse:
      type: object
      properties:
        Charges:
          type: array
          items:
            $ref: '#/components/schemas/Charge'
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    GetTransactionsRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        StartDate:
          type: string
          format: date-time
        EndDate:
          type: string
          format: date-time
    GetTransactionsResponse:
      type: object
      properties:
        Transactions:
          type: array
          items:
            type: object
            properties:
              TransactionId:
                type: integer
              TransactionDate:
                type: string
                format: date
              TransactionType:
                type: string
              Amount:
                type: number
                format: float
              PatientId:
                type: integer
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    GetProvidersRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
    GetProvidersResponse:
      type: object
      properties:
        Providers:
          type: array
          items:
            $ref: '#/components/schemas/Provider'
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    GetPracticesRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
    GetPracticesResponse:
      type: object
      properties:
        Practices:
          type: array
          items:
            $ref: '#/components/schemas/Practice'
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    GetServiceLocationsRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
    GetServiceLocationsResponse:
      type: object
      properties:
        ServiceLocations:
          type: array
          items:
            $ref: '#/components/schemas/ServiceLocation'
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    GetProcedureCodesRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
    GetProcedureCodesResponse:
      type: object
      properties:
        ProcedureCodes:
          type: array
          items:
            $ref: '#/components/schemas/ProcedureCode'
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    RegisterExternalVendorRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        VendorName:
          type: string
        VendorEmail:
          type: string
          format: email
    RegisterExternalVendorResponse:
      type: object
      properties:
        VendorId:
          type: integer
        CustomerKey:
          type: string
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    GetExternalVendorsRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
    GetExternalVendorsResponse:
      type: object
      properties:
        ExternalVendors:
          type: array
          items:
            $ref: '#/components/schemas/ExternalVendor'
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    GetThrottlesRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
    GetThrottlesResponse:
      type: object
      properties:
        ThrottleLimits:
          type: array
          items:
            $ref: '#/components/schemas/ThrottleLimit'
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
    GetCustomerIdFromKeyRequest:
      type: object
      properties:
        RequestHeader:
          $ref: '#/components/schemas/RequestHeader'
        CustomerKey:
          type: string
    GetCustomerIdFromKeyResponse:
      type: object
      properties:
        CustomerId:
          type: integer
        ErrorCode:
          type: string
        ErrorMessage:
          type: string