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.
TebraClient(read_only=True) while exploring. Every mutating operation is rejected locally with TebraReadOnlyError before a network request is made.
Quick start
Install the package next to its dependencies (zeep, httpx, platformdirs), then 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.
Modular resources
Use a domain namespace for the full operation surface, including writes and helpers.
What the wrapper handles for you
| Behavior | What happens |
|---|---|
Empty Fields | Sends Fields: {} when fields=None so endpoints such as GetPractices return all fields instead of failing with Tebra’s server-side NullReferenceException. |
| Practice ID resolution | Resolves and caches practice_id → PracticeName for endpoints whose WSDL filters only accept a practice name (GetAppointments, GetCharges, GetTransactions). |
| 60-day charge windowing | Splits GetCharges service-date ranges longer than 60 days into contiguous windows and deduplicates rows by charge ID. |
| Ghost records | Strips placeholder rows such as [{"ID": None, ...}] that Tebra returns for empty result sets. |
| Rate limiting & retry | Spaces 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 quirks | Dispatches 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.
Practices
List practices and resolve practice IDs into exact names.
Patients
Fetch, search, cursor-page, create, and update patients.
Appointments
Query appointments and reasons, or manage bookings.
Charges
Query charges with automatic 60-day windowing.
Encounters
Encounter details, context resolution, and SOAP notes.
Providers
Providers, schedules, time-offs, and resource calendars.
Service locations
List the service locations configured for a practice.
Procedure codes
CPT/HCPCS and practice-specific procedure codes.
Payments
Payments, ledger transactions, and payment posting.
Documents
Upload and delete patient documents.
System
Live throttles, customer ID, and external vendors.
Reference map
TebraClient
Constructor, lifecycle, raw dispatcher, and every flat convenience method.
Configuration
TebraConfig, environment variables, .env loading, and write-operation guard.
Exceptions
Typed error hierarchy with the attributes each error exposes.
Transport & throttling
WSDL caching, pooled async transport, and per-endpoint rate limiting.
Utilities
Serialization, field selectors, ghost-record filtering, date formatting, and window splitting.
Encounter helpers
resolve_context, format_soap_note, and build_service_line.