Skip to main content

tebra_soap_api — Async Tebra (Kareo) SOAP 2.1 Python Wrapper

A fast, lightweight, modular async wrapper around the Tebra (Kareo) SOAP 2.1 Web Services API, built on zeep.AsyncClient and httpx.AsyncClient.

Disclaimer: This is an unofficial, community-built Python module. It is not affiliated with, endorsed by, or sponsored by Tebra. Tebra and Kareo are trademarks or registered trademarks of their respective owners. This project simply provides a Python wrapper around the publicly available Tebra SOAP 2.1 API; all product names and trademarks belong to their respective owners, and no copyright infringement is intended.

Installation

pip install tebra_soap_api

Documentation

Full API guide: open docs/index.html in a browser (or use the docs/ folder in the repository). It is a static, mobile-responsive site with a page per module, complete method reference, and runnable examples — no server or build step required.

Key Features

  • Async & Concurrent: Uses pooled HTTP/1.1 keep-alive connections (httpx.AsyncClient), off-loop WSDL compilation (asyncio.to_thread), persistent file + in-memory WSDL caching, and per-endpoint rate limiters so distinct endpoints (GetPractices, GetAppointments, GetCharges, GetPatients, etc.) execute concurrently via asyncio.gather.
  • Two Clean Ways to Call:
    • Top-level convenience methods directly on TebraClient: get_practices(), get_patient(), get_patients(), get_appointments(), get_charges(), get_providers(), get_service_locations(), get_payments(), get_transactions(), get_procedure_codes(), get_encounter_details().
    • Modular resource namespaces: client.practices, client.patients, client.appointments, client.charges, client.encounters, client.providers, client.locations, client.procedure_codes, client.payments, client.documents, client.system.
  • Built-in Tebra SOAP 2.1 Fixes:
    • Automatically sends empty Fields: {} when fields=None to avoid Tebra's server-side NullReferenceException on GetPractices and other Get* endpoints.
    • Automatically strips placeholder/ghost records (ID=None) returned by Tebra on empty result sets.
    • Automatically resolves practice_id -> PracticeName (with in-memory caching) on endpoints like GetAppointments, GetCharges, and GetTransactions where Tebra's WSDL only accepts PracticeName.
    • Respects Tebra's per-endpoint throttle windows (GetAllPatients=2500ms, GetPatients=1000ms, GetTransactions=1000ms, others 250ms) and retries transient throttle XML errors.
    • Supports read_only=True (TEBRA_READ_ONLY=true) to strictly block all 15+ mutating SOAP operations before any network request is made.

Configuration

Provide credentials explicitly, via environment variables, or via a .env file:

export TEBRA_USER="user@example.com"
export TEBRA_PASSWORD="your-password"
export TEBRA_CUSTOMER_KEY="your-customer-key"
export TEBRA_READ_ONLY="true"   # optional safety guard

Quick Start

import asyncio
from tebra_soap_api import TebraClient


async def main() -> None:
    async with TebraClient(read_only=True) as client:
        # 1. List practices
        practices = await client.get_practices()

        # 2. Fetch appointments, charges, providers, and locations concurrently
        appointments, charges, providers, locations = await asyncio.gather(
            client.get_appointments(
                practice_id=7,
                start_date="2026-04-01",
                end_date="2026-04-15",
            ),
            client.get_charges(
                practice_id=7,
                from_service_date="2026-04-01",
                to_service_date="2026-04-15",
            ),
            client.get_providers(practice_id=7, active_only=True),
            client.get_service_locations(practice_id=7),
        )

        # 3. Search patients or fetch a single patient by ID
        matches = await client.get_patients(
            practice_id=7,
            first_name="Test",
            last_name="Patient",
        )
        patient = await client.get_patient(patient_id=119246)

        # 4. Stream all patients in a practice via cursor pagination
        async for p in client.iter_all_patients(practice_id=7, batch_size=250):
            print(p["ID"], p["PatientFullName"])


asyncio.run(main())

Package Layout

tebra_soap_api/
├── __init__.py          # Public exports
├── client.py            # TebraClient (core dispatcher + top-level convenience methods)
├── config.py            # TebraConfig, env/.env loader, WRITE_OPERATIONS, throttle defaults
├── exceptions.py        # Typed exception hierarchy (TebraError, TebraReadOnlyError, etc.)
├── transport.py         # FileWsdlCache, async WSDL loader, TebraAsyncTransport, EndpointThrottler
├── utils.py             # Zeep serialization, ghost-record filtering, date/field normalizers
└── resources/           # Modular domain resources
    ├── base.py          # BaseResource
    ├── practices.py     # PracticesResource (GetPractices, practice ID/name resolution)
    ├── patients.py      # PatientsResource (GetPatient, GetPatients, GetAllPatients, Create/Update)
    ├── appointments.py  # AppointmentsResource (GetAppointments, GetAppointment, Reasons, CRUD)
    ├── charges.py       # ChargesResource (GetCharges)
    ├── encounters.py    # EncountersResource (GetEncounterDetails, resolve_context, Create/UpdateStatus)
    ├── providers.py     # ProvidersResource (GetProviders, Provider/Resource Schedules & TimeOffs)
    ├── locations.py     # ServiceLocationsResource (GetServiceLocations)
    ├── procedure_codes.py # ProcedureCodesResource (GetProcedureCodes)
    ├── payments.py      # PaymentsResource (GetPayments, GetTransactions, CreatePayment)
    ├── documents.py     # DocumentsResource (CreateDocument, DeleteDocument)
    └── system.py        # SystemResource (GetThrottles, GetCustomerIdFromKey, ExternalVendors)

Metadata

Release files for tebra_soap_api 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tebra_soap_api 0.1.0
File Size Uploaded Provenance Actions
tebra_soap_api-0.1.0.tar.gz 70.3 kB Without provenance Details for tebra_soap_api-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tebra_soap_api 0.1.0
File Interpreter ABI Platform Actions
tebra_soap_api-0.1.0-py3-none-any.whl Python 3 none any Details for tebra_soap_api-0.1.0-py3-none-any.whl

Total release size: 108.8 kB

Release files / tebra_soap_api-0.1.0.tar.gz

Download URL tebra_soap_api-0.1.0.tar.gz
Size 70.3 kB
Tags Source
SHA-256 checksum
How to use checksums
c580176a016f72323d2c3638d2be733a82ba509698d1e34da90bd94c1fa1b46f
BLAKE2b-256 checksum
How to use checksums
c20244ba2959c854068b04deea0bdbefa41d9730d20e4fe53e04c9f375e95ace
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / tebra_soap_api-0.1.0-py3-none-any.whl

Download URL tebra_soap_api-0.1.0-py3-none-any.whl
Size 38.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
82cd823ede3be6a63490b035f1ad6eaddde4057ec118d9c9dd1565d6a11f9af6
BLAKE2b-256 checksum
How to use checksums
f1f51d6b83799699945425406ffb1c02d889c0c5a84d2c99c005979fd0661b19
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for tebra_soap_api 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page