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.1

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.1
File Size Uploaded Provenance Actions
tebra_soap_api-0.1.1.tar.gz 70.5 kB Without provenance Details for tebra_soap_api-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 108.9 kB

Release files / tebra_soap_api-0.1.1.tar.gz

Download URL tebra_soap_api-0.1.1.tar.gz
Size 70.5 kB
Tags Source
SHA-256 checksum
How to use checksums
ee20c4ee50995bc64f8236202e129bea5c448335db2b247f6043168ca30c0520
BLAKE2b-256 checksum
How to use checksums
2c3d0213b255e62e5f6837e7b60443b626522bd1e96e46b2fb82421e4ebdc5c9
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.1-py3-none-any.whl

Download URL tebra_soap_api-0.1.1-py3-none-any.whl
Size 38.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
770f3f5dcd2ab4fef38759b44d8df84a229be818cd878ce93610b16faf0433f2
BLAKE2b-256 checksum
How to use checksums
6ae56b188c115fd12dcc4c4a93135b2ff1d1f3f2533b49dfa56ba86e4f7dfacb
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.1

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