Ttebra_soap_apiAsync Tebra SOAP 2.1
SOAP 2.1
Resources

Encounters

Read encounter details, resolve everything needed to create an encounter, and format SOAP notes into Tebra's unstructured notes field.

Resource
client.encounters
SOAP operations
GetEncounterDetails, CreateEncounter, UpdateEncounterStatus
Flat method
get_encounter_details
Helpers
resolve_context, format_soap_note, build_service_line

Methods

client.encounters.get_details#

read
async get_details(encounter_id, *, practice_id=None, practice_name=None, fields=None) -> list[dict]

Query encounter details using GetEncounterDetails. The practice block is optional and is only sent when an identifier is supplied.

Parameters
ParameterTypeDescription
encounter_idrequiredint | strEncounter ID.
practice_idint | str | NonePractice ID (sent as a string).
practice_namestr | NonePractice name.
fieldsIterable[str] | Mapping[str, bool] | NoneField selector.
Returnslist[dict[str, Any]]

client.encounters.get#

read
async get(encounter_id, *, practice_id=None, practice_name=None, fields=None) -> dict | None

Fetch the first encounter detail record, or None when nothing matches.

Returnsdict[str, Any] | None

client.encounters.resolve_context#

read
async resolve_context(*, patient_name, service_date, practice_id=None, practice_name=None) -> dict

Read-only helper that resolves a practice, matching patient, case, service location, rendering provider, and appointment for a service date. It runs the appointment and patient lookups concurrently with asyncio.gather and performs fallback location/provider lookups only when needed. Raises TebraNotFoundError when no patient matches.

Parameters
ParameterTypeDescription
patient_namerequiredstrFull patient name, for example "Test Patient" or "Patient, Test".
service_daterequiredstr | date | datetimeService date used to match the appointment.
practice_idint | str | NonePractice ID; resolved to name.
practice_namestr | NonePractice name.
Returnsdict with service_start_date, practice, patient, case, rendering_provider, service_location, appointment, plus matched_patient_raw and matched_appointment_raw.
Example
context = await client.encounters.resolve_context(
    practice_name="Becki Lentz Physical Therapy, Inc",
    patient_name="Test Patient",
    service_date="2026-04-16",
)
print(context["patient"]["PatientID"])
print(context["service_location"]["LocationName"])

client.encounters.create#

write
async create(encounter=None, *, practice=None, patient=None, rendering_provider=None, service_location=None, service_lines=None, service_start_date=None, case=None, post_date=None, appointment=None, medical_office_notes=None, business_office_notes=None, encounter_status=None) -> dict

Create an encounter using CreateEncounter. Pass either a raw encounter dict or the structured keyword arguments. Service lines are normalized and validated by build_service_line. Blocked when read_only=True.

Parameters
ParameterTypeDescription
encounterMapping[str, Any] | NoneRaw WSDL Encounter payload. When given, other structured arguments are ignored.
practiceMapping[str, Any] | NonePractice block. Required in structured mode.
patientMapping[str, Any] | NonePatient block. Required in structured mode.
rendering_providerMapping[str, Any] | NoneRendering provider block. Required in structured mode.
service_locationMapping[str, Any] | NoneService location block. Required in structured mode.
service_linesSequence[Mapping] | NoneOne or more charge lines. Required in structured mode.
service_start_datestr | date | datetime | NoneEncounter service start date. Required in structured mode.
caseMapping[str, Any] | NoneOptional case block.
post_datestr | date | datetime | NonePosting date. Defaults to today.
appointmentMapping[str, Any] | NoneOptional appointment block.
medical_office_notesstr | NoneUnstructured medical office notes; use format_soap_note to build SOAP text.
business_office_notesstr | NoneBusiness office notes.
encounter_statusstr | NoneEncounter status.
Returnsdict[str, Any] (the SOAP response)
In structured mode, all six of practice, patient, rendering_provider, service_location, service_lines, and service_start_date are required. Otherwise a ValueError is raised.

client.encounters.update_status#

write
async update_status(encounter_id, status, *, practice_id=None, practice_name=None) -> dict

Update an encounter's status using UpdateEncounterStatus. Blocked when read_only=True.

Parameters
ParameterTypeDescription
encounter_idrequiredintEncounter ID.
statusrequiredstrNew encounter status.
practice_idint | str | NonePractice ID (sent as a string).
practice_namestr | NonePractice name.
Returnsdict[str, Any]

Module helpers

Import these from tebra_soap_api or tebra_soap_api.encounters.

format_soap_note#

helper
format_soap_note(*, subjective='', objective='', assessment='', plan='') -> str

Format structured SOAP sections into Tebra's unstructured MedicalOfficeNotes text. Empty sections are skipped and sections are separated by blank lines.

Returnsstr
Example
from tebra_soap_api import format_soap_note

notes = format_soap_note(
    subjective="Patient reports reduced knee pain.",
    objective="Range of motion improved.",
    assessment="Progressing well.",
    plan="Continue current plan for 4 weeks.",
)

build_service_line#

helper
build_service_line(line, *, default_service_start_date=None) -> dict

Normalize and validate a single ServiceLineReq for CreateEncounter. Accepts PascalCase or snake_case keys. Requires a service start date, procedure code, diagnosis code 1, and units; raises ValueError otherwise.

Returnsdict[str, Any] with normalized dates, codes, modifiers, units, charges, and notes.
Example
from tebra_soap_api import build_service_line

line = build_service_line(
    {
        "procedure_code": "97110",
        "diagnosis_code_1": "M25.561",
        "units": 2,
        "unit_charge": 45.0,
        "minutes": 30,
    },
    default_service_start_date="2026-04-16",
)

resolve_context return shape

KeyContents
service_start_dateNormalized YYYY-MM-DD service date.
practicePracticeID, PracticeName.
patientPatientID, name parts (None-free).
caseCaseID, CaseName, CasePayerScenario.
rendering_providerProviderID when resolved.
service_locationLocationID, LocationName.
appointmentAppointmentID when a matching appointment was found, else None.
matched_patient_rawThe full matched patient record.
matched_appointment_rawThe full matched appointment record or None.

End-to-end example

from tebra_soap_api import TebraClient, format_soap_note

async with TebraClient(read_only=True) as client:
    ctx = await client.encounters.resolve_context(
        practice_name="Becki Lentz Physical Therapy, Inc",
        patient_name="Test Patient",
        service_date="2026-04-16",
    )

    notes = format_soap_note(
        subjective="Patient reports improvement.",
        objective="Observed improved range of motion.",
        assessment="Responding to treatment.",
        plan="Continue plan of care.",
    )

    # In a writable client:
    # encounter = await client.encounters.create(
    #     practice=ctx["practice"],
    #     patient=ctx["patient"],
    #     rendering_provider=ctx["rendering_provider"],
    #     service_location=ctx["service_location"],
    #     service_start_date=ctx["service_start_date"],
    #     case=ctx["case"],
    #     appointment=ctx["appointment"],
    #     service_lines=[
    #         {
    #             "ProcedureCode": "97110",
    #             "DiagnosisCode1": "M25.561",
    #             "Units": 2,
    #             "Minutes": 30,
    #         }
    #     ],
    #     medical_office_notes=notes,
    # )

Related