Skip to main content

tebra_soap_api — Async Tebra (Kareo) SOAP 2.1 Python Wrapper

A fast, lightweight, modular async wrapper around the Tebra (Kareo) SOAP 2.1 Web Services API, built on zeep.AsyncClient and httpx.AsyncClient.

Disclaimer: This is an unofficial, community-built Python module. It is not affiliated with, endorsed by, or sponsored by Tebra. Tebra and Kareo are trademarks or registered trademarks of their respective owners. This project simply provides a Python wrapper around the publicly available Tebra SOAP 2.1 API; all product names and trademarks belong to their respective owners, and no copyright infringement is intended.

Installation

pip install tebra_soap_api

Documentation

Full API guide: open docs/index.html in a browser (or use the docs/ folder in the repository). It is a static, mobile-responsive site with a page per module, complete method reference, and runnable examples — no server or build step required.

Key Features

  • Async & Concurrent: Uses pooled HTTP/1.1 keep-alive connections (httpx.AsyncClient), off-loop WSDL compilation (asyncio.to_thread), persistent file + in-memory WSDL caching, and per-endpoint rate limiters so distinct endpoints (GetPractices, GetAppointments, GetCharges, GetPatients, etc.) execute concurrently via asyncio.gather.
  • Two Clean Ways to Call:
    • Top-level convenience methods directly on TebraClient: get_practices(), get_patient(), get_patients(), get_appointments(), get_charges(), get_providers(), get_service_locations(), get_payments(), get_transactions(), get_procedure_codes(), get_encounter_details().
    • Modular resource namespaces: client.practices, client.patients, client.appointments, client.charges, client.encounters, client.providers, client.locations, client.procedure_codes, client.payments, client.documents, client.system.
  • Built-in Tebra SOAP 2.1 Fixes:
    • Automatically sends empty Fields: {} when fields=None to avoid Tebra's server-side NullReferenceException on GetPractices and other Get* endpoints.
    • Automatically strips placeholder/ghost records (ID=None) returned by Tebra on empty result sets.
    • Automatically resolves practice_id -> PracticeName (with in-memory caching) on endpoints like GetAppointments, GetCharges, and GetTransactions where Tebra's WSDL only accepts PracticeName.
    • Respects Tebra's per-endpoint throttle windows (GetAllPatients=2500ms, GetPatients=1000ms, GetTransactions=1000ms, others 250ms) and retries transient throttle XML errors.
    • Supports read_only=True (TEBRA_READ_ONLY=true) to strictly block all 15+ mutating SOAP operations before any network request is made.

Configuration

Provide credentials explicitly, via environment variables, or via a .env file:

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

Tebra SOAP payloads contain patient details, so this library does not log request or response bodies by default:

  • The custom TebraAsyncTransport overrides Zeep's transport, which otherwise logs the full SOAP envelope and response at DEBUG. This library logs only the endpoint, HTTP status, and payload byte size. Even if your application sets the root logger to DEBUG, patient data is not written by the transport.
  • The library does not configure Python logging, install handlers, or write log files. Logging destinations and levels remain under your application's control.
  • Credentials are held in memory in TebraConfig for the lifetime of the client and are never written to disk by the library. password and customer_key use repr=False, so they are redacted from repr(config) and normal tracebacks.
  • Credential resolution order is explicit arguments, then TEBRA_USER / TEBRA_PASSWORD / TEBRA_CUSTOMER_KEY environment variables, then a local .env file. The .env parser is read-only and does not mutate os.environ; the library never creates or updates .env. Keep real .env files out of version control.
  • The WSDL disk cache stores only public WSDL/XSD documents. It never contains credentials or patient data.
  • Typed exceptions intentionally expose diagnostic fields (raw_response, security_response, stack_trace, detail) that may contain server-side data. Log str(exc) for routine error reporting, and avoid dumping exception __dict__ or full response objects to shared logs.

Quick Start

import asyncio
from tebra_soap_api import TebraClient


async def main() -> None:
    async with TebraClient(read_only=True) as client:
        # 1. List practices
        practices = await client.get_practices()

        # 2. Fetch appointments, charges, providers, and locations concurrently
        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),
        )

        # 3. Search patients or fetch a single patient by ID
        matches = await client.get_patients(
            practice_id=7,
            first_name="Test",
            last_name="Patient",
        )
        patient = await client.get_patient(patient_id=119246)

        # 4. Stream all patients in a practice via cursor pagination
        async for p in client.iter_all_patients(practice_id=7, batch_size=250):
            print(p["ID"], p["PatientFullName"])


asyncio.run(main())

Package Layout

tebra_soap_api/
├── __init__.py          # Public exports
├── client.py            # TebraClient (core dispatcher + top-level convenience methods)
├── config.py            # TebraConfig, env/.env loader, WRITE_OPERATIONS, throttle defaults
├── exceptions.py        # Typed exception hierarchy (TebraError, TebraReadOnlyError, etc.)
├── transport.py         # FileWsdlCache, async WSDL loader, TebraAsyncTransport, EndpointThrottler
├── utils.py             # Zeep serialization, ghost-record filtering, date/field normalizers
└── resources/           # Modular domain resources
    ├── base.py          # BaseResource
    ├── practices.py     # PracticesResource (GetPractices, practice ID/name resolution)
    ├── patients.py      # PatientsResource (GetPatient, GetPatients, GetAllPatients, Create/Update)
    ├── appointments.py  # AppointmentsResource (GetAppointments, GetAppointment, Reasons, CRUD)
    ├── charges.py       # ChargesResource (GetCharges)
    ├── encounters.py    # EncountersResource (GetEncounterDetails, resolve_context, Create/UpdateStatus)
    ├── providers.py     # ProvidersResource (GetProviders, Provider/Resource Schedules & TimeOffs)
    ├── locations.py     # ServiceLocationsResource (GetServiceLocations)
    ├── procedure_codes.py # ProcedureCodesResource (GetProcedureCodes)
    ├── payments.py      # PaymentsResource (GetPayments, GetTransactions, CreatePayment)
    ├── documents.py     # DocumentsResource (CreateDocument, DeleteDocument)
    └── system.py        # SystemResource (GetThrottles, GetCustomerIdFromKey, ExternalVendors)

Metadata

Release files for tebra_soap_api 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tebra_soap_api 0.1.2
File Size Uploaded Provenance Actions
tebra_soap_api-0.1.2.tar.gz 73.3 kB Without provenance Details for tebra_soap_api-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tebra_soap_api 0.1.2
File Interpreter ABI Platform Actions
tebra_soap_api-0.1.2-py3-none-any.whl Python 3 none any Details for tebra_soap_api-0.1.2-py3-none-any.whl

Total release size: 112.9 kB

Release files / tebra_soap_api-0.1.2.tar.gz

Download URL tebra_soap_api-0.1.2.tar.gz
Size 73.3 kB
Tags Source
SHA-256 checksum
How to use checksums
1fcd44359bac40abb112032bbf76a44d0d3a470a27154fda980aaa81d7b9ceeb
BLAKE2b-256 checksum
How to use checksums
57639e37133d378d566b8285e87eeea186e29f67f92f507dda1415faf36f755b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / tebra_soap_api-0.1.2-py3-none-any.whl

Download URL tebra_soap_api-0.1.2-py3-none-any.whl
Size 39.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
26c5085243c932bcd39ab56a6d551a442560daa8710f01e52b83c7eca0765872
BLAKE2b-256 checksum
How to use checksums
7b174bc69ea17866a73b48d732fc71ecb06009f1a49e3bb6290b69af801b85db
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for tebra_soap_api 0.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page