Ttebra_soap_apiAsync Tebra SOAP 2.1
SOAP 2.1
Getting started

TebraClient

TebraClient is an async context manager that owns the WSDL document, the pooled HTTP transport, and the per-endpoint throttler. It exposes the domain resources plus a set of flat convenience methods.

Lifecycle

TebraClient#

read
TebraClient(config=None, *, user=None, password=None, customer_key=None, wsdl=None, timeout=30.0, wsdl_timeout=60.0, cache_wsdl=True, cache_ttl=86400, cache_dir=None, respect_throttles=True, throttle_buffer_ms=40.0, max_retries=2, read_only=None, verify_ssl=True, client_version=None, dotenv_path=None, zeep_client=None)

Creates the client and mounts every resource namespace: practices, patients, appointments, charges, encounters, providers, locations, procedure_codes, payments, documents, and system. Network work starts only when you call connect() or enter the async context manager.

Parameters
ParameterTypeDescription
configTebraConfig | NoneA pre-built config. When omitted, the remaining keyword arguments are passed to TebraConfig.resolve.
userstr | NoneTebra API user.
passwordstr | NoneTebra API password.
customer_keystr | NoneTebra CustomerKey.
wsdlstr | NoneWSDL URL override.
timeoutfloatOperation timeout. Default 30.0.
wsdl_timeoutfloatWSDL timeout. Default 60.0.
cache_wsdlboolEnable disk WSDL cache. Default True.
cache_ttlintCache lifetime in seconds. Default 86400.
cache_dirPath | str | NoneCustom WSDL cache directory.
respect_throttlesboolEnable per-endpoint spacing. Default True.
throttle_buffer_msfloatBuffer added to throttle intervals. Default 40.0.
max_retriesintRetries for retryable reads. Default 2.
read_onlybool | NoneBlock mutating operations. Defaults to TEBRA_READ_ONLY / .env, else False.
verify_sslboolVerify TLS certificates. Default True.
client_versionstr | NoneOptional SOAP ClientVersion.
dotenv_pathPath | str | NoneSpecific .env path.
zeep_clientAny | NoneInject a pre-built Zeep async client (advanced/testing). When supplied, the client does not own its lifecycle.
Example
from tebra_soap_api import TebraClient

client = TebraClient(
    read_only=True,
    timeout=45.0,
    max_retries=3,
)

await client.connect()#

read
async connect() -> TebraClient

Loads the cached WSDL schema (compiling off the event loop) and opens the pooled async HTTP transport. Idempotent and protected by an async lock. Returns the same client.

ReturnsTebraClient

await client.close()#

read
async close() -> None

Closes the underlying HTTP connection pool and releases an owned Zeep client. Safe to call more than once.

ReturnsNone

async with TebraClient(...)#

read
async __aenter__() -> TebraClient

Connects and returns the client; __aexit__ closes the transport. This is the recommended pattern so connections are always released.

Example
async with TebraClient(read_only=True) as client:
    practices = await client.get_practices()

client.is_connected#

read
is_connected -> bool

Property indicating whether a Zeep client is currently bound. It becomes True after connect() and False after close() for an owned client.

Returnsbool

Raw dispatcher

await client.call#

read
async call(operation, payload=None, *, raw=False, check_errors=True, **kwargs) -> Any

Executes any Tebra SOAP 2.1 operation with authentication injection, write protection, per-endpoint throttling, retries, and structured error handling. Prefer the typed resource methods; use this for operations without a wrapper.

Parameters
ParameterTypeDescription
operationrequiredstrExact SOAP operation name, for example GetPractices.
payloadMapping | NoneBody fields placed directly into the SOAP request.
rawboolReturn the raw Zeep response instead of plain dict/list data. Default False.
check_errorsboolInspect SecurityResponse and ErrorResponse and raise typed errors. Default True.
**kwargsAnyMerged into the request body alongside payload.
Returnsdict / list for normal calls; the raw Zeep object when raw=True.
Automatic quirksGetCustomerIdFromKey is sent without a RequestHeader; UpdatePatient is dispatched with UpdatePatientReq instead of request. The dispatcher applies both quirks automatically.
Example
practices = await client.call(
    "GetPractices",
    {"Filter": {}, "Fields": {"ID": True, "PracticeName": True}},
)

Flat convenience methods

These methods delegate to resources and cover the common read paths. Anything not listed here (writes, schedules, documents, external vendors) is available through the resource namespaces.

Flat methodDelegates toSOAP operation
get_practicespractices.listGetPractices
get_practicepractices.getGetPractices
get_patientpatients.getGetPatient
get_patients / search_patientspatients.listGetPatients
iter_all_patientspatients.iter_allGetAllPatients
get_all_patientspatients.list_allGetAllPatients
get_appointmentsappointments.listGetAppointments
get_appointmentappointments.getGetAppointment
get_appointment_reasonsappointments.list_reasonsGetAppointmentReasons
get_chargescharges.listGetCharges
get_procedure_codesprocedure_codes.listGetProcedureCodes
get_encounter_detailsencounters.get_detailsGetEncounterDetails
get_providersproviders.listGetProviders
get_provider_schedulesproviders.get_schedulesGetProviderSchedules
get_service_locationslocations.listGetServiceLocations
get_paymentspayments.listGetPayments
get_transactionspayments.list_transactionsGetTransactions
get_throttlessystem.get_throttlesGetThrottles
get_customer_idsystem.get_customer_idGetCustomerIdFromKey

Common signatures

await client.get_practices#

read
async get_practices(*, practice_id=None, practice_name=None, active=None, fields=None, **kwargs) -> list[dict]

List practices. Alias: list_practices. See PracticesResource.list for all filter options.

Returnslist[dict[str, Any]]

await client.get_patients#

read
async get_patients(*, practice_id=None, practice_name=None, first_name=None, last_name=None, full_name=None, dob=None, fields=None, **kwargs) -> list[dict]

Search patients. Alias: search_patients. Uses GetPatients; see PatientsResource.list for the full filter surface.

Returnslist[dict[str, Any]]

await client.get_appointments#

read
async get_appointments(*, practice_name=None, practice_id=None, start_date=None, end_date=None, patient_id=None, patient_full_name=None, fields=None, **kwargs) -> list[dict]

Query appointments. practice_id is resolved to PracticeName; date-only bounds expand to UTC day boundaries.

Returnslist[dict[str, Any]]

await client.get_charges#

read
async get_charges(*, practice_name=None, practice_id=None, patient_name=None, from_service_date=None, to_service_date=None, fields=None, **kwargs) -> list[dict]

Query charges. Ranges longer than 60 days are split automatically. Set auto_chunk_days=None through the resource method to disable.

Returnslist[dict[str, Any]]

Concurrency

Different endpoints have independent locks, so asyncio.gather runs them in parallel. Back-to-back calls to the same endpoint are spaced to respect Tebra’s throttle windows.

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),
)

Extending with a custom resource

Subclass BaseResource when you need an operation that is not wrapped yet. It holds a reference to the client and offers protected helpers: _call(operation, **payload) for a raw SOAP call, _query_list(...) to extract a clean list from an ArrayOf* response, and _clean_single(...) to clean a single record while dropping ghost rows.

from tebra_soap_api.resources import BaseResource


class MyResource(BaseResource):
    async def recent_practices(self) -> list[dict]:
        return await self._query_list(
            "GetPractices",
            outer_key="Practices",
            inner_key="PracticeData",
            filter_data={"Active": "True"},
            fields=["ID", "PracticeName"],
        )


client.my_resource = MyResource(client)

BaseResource is exported from tebra_soap_api.resources.

Resource accessors