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

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

Patient data, logging, and credentials

SOAP bodies are never logged by default Tebra payloads contain patient details. The bundled TebraAsyncTransport overrides Zeep’s transport, which otherwise logs complete SOAP request and response bodies at DEBUG. This library logs only the endpoint, HTTP status, and payload byte size.
  • The library does not configure Python logging, add handlers, or write log files. Levels and destinations stay under your application’s control.
  • Credentials live in memory in TebraConfig for the client lifetime and are not written to disk by the library. password and customer_key use repr=False, so they are redacted from repr(config) and normal tracebacks.
  • Resolution order is explicit arguments, then TEBRA_USER / TEBRA_PASSWORD / TEBRA_CUSTOMER_KEY, then a local .env file. The .env parser is read-only, does not mutate os.environ, and the library never creates or updates the file. Keep real .env files out of version control.
  • The WSDL disk cache stores only public WSDL/XSD documents, never credentials or patient data.
  • Typed exceptions expose diagnostic fields (raw_response, security_response, stack_trace, detail) that may contain server-side data. Prefer str(exc) for routine error logs and avoid dumping exception __dict__ or full response objects.

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