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#
readasync 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.
| Parameter | Type | Description |
|---|---|---|
encounter_idrequired | int | str | Encounter ID. |
practice_id | int | str | None | Practice ID (sent as a string). |
practice_name | str | None | Practice name. |
fields | Iterable[str] | Mapping[str, bool] | None | Field selector. |
list[dict[str, Any]]client.encounters.get#
readasync get(encounter_id, *, practice_id=None, practice_name=None, fields=None) -> dict | NoneFetch the first encounter detail record, or None when nothing matches.
dict[str, Any] | Noneclient.encounters.resolve_context#
readasync resolve_context(*, patient_name, service_date, practice_id=None, practice_name=None) -> dictRead-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.
| Parameter | Type | Description |
|---|---|---|
patient_namerequired | str | Full patient name, for example "Test Patient" or "Patient, Test". |
service_daterequired | str | date | datetime | Service date used to match the appointment. |
practice_id | int | str | None | Practice ID; resolved to name. |
practice_name | str | None | Practice name. |
dict with service_start_date, practice, patient, case, rendering_provider, service_location, appointment, plus matched_patient_raw and matched_appointment_raw.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#
writeasync 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) -> dictCreate 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.
| Parameter | Type | Description |
|---|---|---|
encounter | Mapping[str, Any] | None | Raw WSDL Encounter payload. When given, other structured arguments are ignored. |
practice | Mapping[str, Any] | None | Practice block. Required in structured mode. |
patient | Mapping[str, Any] | None | Patient block. Required in structured mode. |
rendering_provider | Mapping[str, Any] | None | Rendering provider block. Required in structured mode. |
service_location | Mapping[str, Any] | None | Service location block. Required in structured mode. |
service_lines | Sequence[Mapping] | None | One or more charge lines. Required in structured mode. |
service_start_date | str | date | datetime | None | Encounter service start date. Required in structured mode. |
case | Mapping[str, Any] | None | Optional case block. |
post_date | str | date | datetime | None | Posting date. Defaults to today. |
appointment | Mapping[str, Any] | None | Optional appointment block. |
medical_office_notes | str | None | Unstructured medical office notes; use format_soap_note to build SOAP text. |
business_office_notes | str | None | Business office notes. |
encounter_status | str | None | Encounter status. |
dict[str, Any] (the SOAP response)practice, patient, rendering_provider, service_location, service_lines, and service_start_date are required. Otherwise a ValueError is raised.client.encounters.update_status#
writeasync update_status(encounter_id, status, *, practice_id=None, practice_name=None) -> dictUpdate an encounter's status using UpdateEncounterStatus. Blocked when read_only=True.
| Parameter | Type | Description |
|---|---|---|
encounter_idrequired | int | Encounter ID. |
statusrequired | str | New encounter status. |
practice_id | int | str | None | Practice ID (sent as a string). |
practice_name | str | None | Practice name. |
dict[str, Any]Module helpers
Import these from tebra_soap_api or tebra_soap_api.encounters.
format_soap_note#
helperformat_soap_note(*, subjective='', objective='', assessment='', plan='') -> strFormat structured SOAP sections into Tebra's unstructured MedicalOfficeNotes text. Empty sections are skipped and sections are separated by blank lines.
strfrom 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#
helperbuild_service_line(line, *, default_service_start_date=None) -> dictNormalize 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.
dict[str, Any] with normalized dates, codes, modifiers, units, charges, and notes.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
| Key | Contents |
|---|---|
service_start_date | Normalized YYYY-MM-DD service date. |
practice | PracticeID, PracticeName. |
patient | PatientID, name parts (None-free). |
case | CaseID, CaseName, CasePayerScenario. |
rendering_provider | ProviderID when resolved. |
service_location | LocationID, LocationName. |
appointment | AppointmentID when a matching appointment was found, else None. |
matched_patient_raw | The full matched patient record. |
matched_appointment_raw | The 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,
# )