Escape Dental API (1.0.0)

List and create appointments. Staff-only.

List supports filtering by date range (from / to), status, patient, and provider. Results are ordered by date_time ascending with a pk tiebreaker (see :class:AppointmentPagination).

Status vocabulary -- the Django state machine uses its own status slugs, distinct from any PMS-side arrival_status value carried by sync tools. The three statuses that matter for the No-show report are:

• broken -- patient did not arrive (no-show). The Status.BROKEN choice is labelled Broken/No-Show in the model. This is the value the No-show report filters on.
• cancelled -- patient cancelled ahead of time (slot could be refilled; does not count as a no-show).
• complete -- patient arrived and the visit finished normally.

For convenience, ?status=no_show is accepted as an alias for ?status=broken so the web app can keep semantic URLs.

No-show shortcut -- ?no_show_between=YYYY-MM-DD,YYYY-MM-DD expands to status=no_show plus from/to using the supplied dates. Explicit from / to / status query params still win if passed alongside, so the shortcut is purely additive.

No-show annotations -- when the resolved status is broken / no_show, each row is additionally annotated with:

• patient_no_show_count -- lifetime count of broken appointments for the patient scoped to this practice (ignores other practices).
• patient_phone -- patient's best reach-out number (phone_mobile preferred, then phone_home, then phone_work).
• patient_outstanding_balance -- the patient's current aged receivables snapshot (Patient.balance_current).
• cancel_reason -- the appointment's cancellation_reason if set.

These fields are null on rows that are not no-shows, keeping the payload lean for normal schedule queries.

List and create appointments. Staff-only.

List supports filtering by date range (from / to), status, patient, and provider. Results are ordered by date_time ascending with a pk tiebreaker (see :class:AppointmentPagination).

Status vocabulary -- the Django state machine uses its own status slugs, distinct from any PMS-side arrival_status value carried by sync tools. The three statuses that matter for the No-show report are:

• broken -- patient did not arrive (no-show). The Status.BROKEN choice is labelled Broken/No-Show in the model. This is the value the No-show report filters on.
• cancelled -- patient cancelled ahead of time (slot could be refilled; does not count as a no-show).
• complete -- patient arrived and the visit finished normally.

For convenience, ?status=no_show is accepted as an alias for ?status=broken so the web app can keep semantic URLs.

No-show shortcut -- ?no_show_between=YYYY-MM-DD,YYYY-MM-DD expands to status=no_show plus from/to using the supplied dates. Explicit from / to / status query params still win if passed alongside, so the shortcut is purely additive.

No-show annotations -- when the resolved status is broken / no_show, each row is additionally annotated with:

• patient_no_show_count -- lifetime count of broken appointments for the patient scoped to this practice (ignores other practices).
• patient_phone -- patient's best reach-out number (phone_mobile preferred, then phone_home, then phone_work).
• patient_outstanding_balance -- the patient's current aged receivables snapshot (Patient.balance_current).
• cancel_reason -- the appointment's cancellation_reason if set.

These fields are null on rows that are not no-shows, keeping the payload lean for normal schedule queries.

Handle PATCH on the list endpoint for bulk updates.

Read-only list of appointment status metadata.

Read-only list of appointment status metadata.

Update appointment confirmation status (orthogonal to lifecycle status).

POST {"confirmed_status": "Confirmed"}

Return the status transition history for an appointment.

Aggregate endpoint for the front-desk route-slip print template (api#239).

GET /v1/practice/<uid>/scheduling/appointment/<appt_uid>/route-slip/

Returns every field the print template renders -- appointment, patient, procedures, primary insurance, provider, and operatory -- in a single JSON response. Designed for under ~50ms per call so check-in at the front desk stays snappy; the N+1 alternative (fetch the appointment, then patient, then insurance, then procedures) was measured as a noticeable stall while the patient stood at the counter.

Transition an appointment to a new status with validation and audit logging.

POST {"status": "complete", "note": "optional reason"}

Find available appointment slots for a given date.

Query params: date: Date in YYYY-MM-DD format (required). duration_minutes: Appointment length in minutes (required). provider: Optional provider ID. operatory: Optional operatory ID. interval: Slot interval in minutes (default 15).

Returns only slot times — does not leak why other times are unavailable.

Return the complete day-sheet for operatory-based schedule rendering.

Single request returning operatories, schedule blocks, and appointments.

Each entry in operatories[] carries an in_chair_patient field (GH-713) — None when the chair is empty, otherwise the authoritatively-resolved currently-seated patient:

{
    "patient_id": "<uuid>",
    "patient_name": "Last, First",
    "appointment_id": "<uuid> | null",
    "since": "<ISO 8601 UTC>",
}

Resolution rules (see :func:apps.scheduling.services._resolve_in_chair_patients):

• Status is one of seated / ready_for_doctor / ready_for_walkout (the patient is in the chair across all three; arrived is lobby-only, complete sets dismissed_at).
• dismissed_at IS NULL as a safety net for imported data.
• On multiple "in chair" rows per operatory (back-to-back seatings without a dismiss — see GH-713 issue body), the most-recently-seated row wins.
• Walk-ins: not exposed today (no walk-in-patient surface exists in the API yet — OperatoryPresence tracks staff occupancy, not patients). The appointment_id field is nullable so the shape is forward-compatible.

Query params: date: Date in YYYY-MM-DD format (required). include_hidden: "true" to include cancelled/unscheduled/planned appointments (default false).

Multi-day slot search with patient scheduling constraints.

All constraint logic runs server-side. Clients send one request with constraints and get back matching slots across multiple days.

Query params: duration_minutes: Required appointment length in minutes. start_date: First date to search (default: today). YYYY-MM-DD. end_date: Last date to search (default: start_date + 30 days). YYYY-MM-DD. days_of_week: Legacy shorthand — comma-separated weekday ints (0=Mon..6=Sun). earliest_time: Legacy shorthand — earliest acceptable start time (HH:MM). latest_time: Legacy shorthand — latest acceptable start time (HH:MM). availability_windows: Repeatable <days>:<start>-<end> windows. Union semantics. Mutually exclusive with the legacy days_of_week / earliest_time / latest_time params — supply one form or the other. provider: Optional provider ID(s). Repeatable for union. operatory: Optional operatory ID(s). Repeatable for union. max_results: Max slots to return (default 20, max 50).

Per-day appointment aggregate for the month-view calendar grid.

GET /v1/practice/<uid>/scheduling/month-summary/?from=YYYY-MM-DD&to=YYYY-MM-DD

Returns a sparse map of local-date strings to {appointment_count, production} in a single round-trip, replacing the auto-paginated /scheduling/appointment/ fetch loop used by the web month-view (useMonthData).

Business rules:

• Days are bucketed in the practice's timezone, never server UTC nor the browser's timezone. An appointment at 11 PM local on 2026-04-01 stays on that date regardless of the server's wall clock.
• appointment_count and production both exclude appointments whose status is cancelled or broken, matching the client-side filter the web app used to apply.
• production sums AppointmentProcedure.fee for every scheduled procedure attached to an included appointment on the day.
• The response is sparse: only days with at least one included appointment appear. Callers treat absent keys as empty days.
• from / to are both inclusive. No server-side range cap is imposed (the caller bounds it to ~6 weeks for the month grid); the endpoint is a single GROUP BY query covered by (practice_id, date_time) so a reasonable window stays well under 50 ms even at 2000 appointments.