Ttebra_soap_apiAsync Tebra SOAP 2.1
SOAP 2.1
Documentation
Python · Async · SOAP 2.1

tebra_soap_api

A fast, modular async wrapper around the Tebra (Kareo) SOAP 2.1 Web Services API. Clean domain resources, typed errors, per-endpoint throttling, and built-in handling for Tebra’s WCF quirks.

asyncio + httpx Typed exceptions Read-only guard Auto throttling PyPI 0.1.1
Start read-only Use TebraClient(read_only=True) while exploring. Every mutating operation is rejected locally with TebraReadOnlyError before a network request is made.

Install

The package is published on PyPI and supports Python 3.10+. Its runtime dependencies (zeep, httpx, platformdirs, requests) are installed automatically.

pip install tebra_soap_api

Package page: pypi.org/project/tebra_soap_api · latest version 0.1.1

Quick start

With the package installed, open a client with an async context manager.

import asyncio
from tebra_soap_api import TebraClient


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

        appointments, charges, patient = await asyncio.gather(
            client.get_appointments(
                practice_id=7,
                start_date="2026-04-01",
                end_date="2026-04-16",
            ),
            client.get_charges(
                practice_id=7,
                from_service_date="2026-01-01",
                to_service_date="2026-04-16",
            ),
            client.get_patient(patient_id=119246),
        )

        for appointment in appointments:
            print(appointment["ID"], appointment.get("StartDate"))


asyncio.run(main())

Credentials resolve from explicit arguments, then TEBRA_* environment variables, then a local .env file. See Configuration.

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

Two ways to call

Flat convenience methods

Call common reads directly on the client. These are thin, typed wrappers over the domain resources.

client.get_practices()
client.get_appointments(...)
client.get_charges(...)

Modular resources

Use a domain namespace for the full operation surface, including writes and helpers.

client.practices.list()
client.patients.iter_all(...)
client.encounters.resolve_context(...)

What the wrapper handles for you

BehaviorWhat happens
Empty FieldsSends Fields: {} when fields=None so endpoints such as GetPractices return all fields instead of failing with Tebra’s server-side NullReferenceException.
Practice ID resolutionResolves and caches practice_id → PracticeName for endpoints whose WSDL filters only accept a practice name (GetAppointments, GetCharges, GetTransactions).
60-day charge windowingSplits GetCharges service-date ranges longer than 60 days into contiguous windows and deduplicates rows by charge ID.
Ghost recordsStrips placeholder rows such as [{"ID": None, ...}] that Tebra returns for empty result sets.
Rate limiting & retrySpaces back-to-back calls to the same endpoint (GetAllPatients 2500 ms, GetPatients 1000 ms, GetTransactions 1000 ms, others 250 ms) while distinct endpoints run concurrently; retries malformed throttle XML.
WCF quirksDispatches UpdatePatient via UpdatePatientReq, calls GetCustomerIdFromKey without a request header, and defaults Active=True / CustomerSpecific=False on GetProcedureCodes.

Explore the API

Each domain has its own page with every method, parameter table, return shape, and runnable example.

Reference map