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.
Secret redactionpassword and customer_key are declared with repr=False, so printing the config or logging a traceback cannot leak them.

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