Ttebra_soap_apiAsync Tebra SOAP 2.1
SOAP 2.1
Getting started

Configuration

Credentials and client behavior live in a single dataclass, TebraConfig. The client accepts it directly or builds one from keyword arguments.

Resolution order

Explicit argumentsValues passed to TebraClient(...) or TebraConfig.resolve(...) win.
Environment variablesThen TEBRA_USER, TEBRA_PASSWORD, TEBRA_CUSTOMER_KEY, TEBRA_WSDL, and TEBRA_READ_ONLY.
Local .envFinally a .env file in the working directory (or dotenv_path). Parsing is side-effect free — os.environ is never changed.
DefaultsBuilt-in defaults apply to everything else.

Environment variables

VariableMaps toNotes
TEBRA_USERuserRequired unless passed explicitly.
TEBRA_PASSWORDpasswordRequired unless passed explicitly.
TEBRA_CUSTOMER_KEYcustomer_keyRequired unless passed explicitly.
TEBRA_WSDLwsdlOptional WSDL override.
TEBRA_READ_ONLYread_onlyTruthy values: 1, true, yes, on.
Example .env
TEBRA_USER=user@example.com
TEBRA_PASSWORD=your-password
TEBRA_CUSTOMER_KEY=your-customer-key
TEBRA_READ_ONLY=true

TebraConfig fields

ParameterTypeDescription
userrequiredstrTebra API user name or email.
passwordrequiredstrTebra API password. Hidden from repr().
customer_keyrequiredstrTebra CustomerKey. Hidden from repr().
wsdlstrWSDL URL. Defaults to DEFAULT_WSDL (the Tebra 2.1 single-WSDL endpoint).
timeoutfloatPer-operation HTTP timeout in seconds. Default 30.0.
wsdl_timeoutfloatWSDL download/compile timeout in seconds. Default 60.0.
cache_wsdlboolEnable the disk WSDL cache. Default True.
cache_ttlintWSDL cache lifetime in seconds before refresh. Default 86400 (1 day).
cache_dirPath | NoneCustom WSDL cache directory. Defaults to the platform user cache directory.
respect_throttlesboolEnforce per-endpoint minimum spacing. Default True.
throttle_buffer_msfloatSafety buffer added to every throttle interval. Default 40.0.
max_retriesintRetries for retryable reads (throttle XML, transient transport). Default 2.
read_onlyboolBlock every operation listed in WRITE_OPERATIONS. Default False.
verify_sslboolVerify TLS certificates. Default True.
client_versionstr | NoneOptional ClientVersion sent in the SOAP request header.
Credential storagepassword and customer_key are held in memory in TebraConfig and are never written to disk by the library. They are declared with repr=False, so printing the config or logging a traceback cannot leak them.
Logging and patient dataThe library never logs SOAP request or response bodies, even at DEBUG. It does not configure logging or write log files. The .env reader is one-way: the library reads local values but never writes them, and it does not mutate os.environ. Add .env to .gitignore and avoid dumping exception payload fields to shared logs.

TebraConfig.resolve

TebraConfig.resolve#

read
TebraConfig.resolve(*, 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) -> TebraConfig

Classmethod that builds a configuration from explicit values, environment variables, and an optional .env file. Raises TebraConfigError when a required credential is missing.

Parameters
ParameterTypeDescription
userstr | NoneExplicit credential; falls back to TEBRA_USER or .env.
passwordstr | NoneExplicit credential; falls back to TEBRA_PASSWORD or .env.
customer_keystr | NoneExplicit key; falls back to TEBRA_CUSTOMER_KEY or .env.
wsdlstr | NoneExplicit WSDL URL; falls back to TEBRA_WSDL, then DEFAULT_WSDL.
read_onlybool | NoneExplicit guard; when omitted reads TEBRA_READ_ONLY / .env.
dotenv_pathPath | str | NoneOptional path to a specific .env file. Does not mutate os.environ.
…—All other TebraConfig fields are accepted with the same defaults.
ReturnsTebraConfig
Example
from tebra_soap_api import TebraConfig

config = TebraConfig.resolve(read_only=True, dotenv_path=".env.staging")
print(config.user)
print(config)  # password and customer_key are redacted

build_request_header

TebraConfig.build_request_header#

read
TebraConfig.build_request_header() -> dict[str, str]

Builds the standard SOAP request header from user, password, and customer_key. Adds ClientVersion only when client_version is set. Most callers never need this; the client injects the header automatically.

Returnsdict[str, str]
Example
header = config.build_request_header()
# {"User": "...", "Password": "...", "CustomerKey": "..."}

Constants

DEFAULT_WSDL#

The default Tebra 2.1 single-WSDL endpoint: https://webservice.kareo.com/services/soap/2.1/KareoServices.svc?singleWsdl.

DEFAULT_ENDPOINT_THROTTLE_MS#

Baseline per-endpoint spacing used before a live GetThrottles call updates the client.

EndpointMilliseconds
GetAllPatients2500
GetThrottles5000
GetPatients1000
GetTransactions1000
GetExternalVendors1000
GetEligibilityStatus1000
Any other endpoint250 (fallback)

WRITE_OPERATIONS#

A frozenset of every mutating SOAP operation. When read_only=True, the client raises TebraReadOnlyError for any of these before dispatching.

CreateAppointment, CreateAppointmentReason, CreateDocument, CreateEncounter, CreatePatient, CreatePayment, CreateUnappliedPayment, DeleteAppointment, DeleteDocument, RegisterExternalVendor, SendHL7Message, UpdateAppointment, UpdateAppointmentStatus, UpdateEncounterStatus, UpdatePatient, UpdatePatientsExternalID, UpdatePrimaryPatientCase.

Read more