Skip to main content

​
PracticeSuite Save Appointment

This document covers practicesuite_save_appointment, the native PracticeSuite scheduling tool exposed through the Agents Platform.

​
Authentication

Uses the PracticeSuite connector (client_id, client_secret, environment). See practicesuite-save-patient.md for connection details and for the canonical patient_pcref derivation algorithm.

​
practicesuite_save_appointment

Books an appointment via POST /v2/api/scheduler/saveAppointmentAPI. This is a mutating tool. The appointment is attached to the patient by the natural key (patient_pcref), the same identifier practicesuite_save_patient writes — not PracticeSuite’s internal UUID.

​
Inputs

Required:
  • account_id — practice tenant to write into.
  • first_name, last_name, dob — the tool derives the patient key from these, identically to practicesuite_save_patient. Or pass patient_pcref on its own: the names are never sent on the wire, so an override makes them unnecessary.
  • physician_code — the physician code the appointment is booked against (e.g. VHA32), not a provider name. It must exist in the target account; an unknown code, a blank one, or a name returns Code: 100. Message: Provider Not Found. When no provider mapping has been supplied, practicesuite_get_patient returns the patient’s pcp_code, which is valid here.
  • scheduled_date — appointment start as a UTC ISO-8601 timestamp, e.g. 2026-12-05T16:00:00Z.
Optional:
  • appt_reason — reason for the visit. Truncated to 150 characters by the tool; the caller does not need to pre-trim it.
  • appointment_id — overrides the id the tool derives. Omit it unless you are deliberately replacing one specific appointment.
  • duration — length in minutes. Omitted, or 0, means 30; a zero-length appointment is not a real intent, so it is read as “unspecified” rather than rejected. Negative values are rejected.
access_token, client_id, client_secret and environment are injected from the integration and hidden from the model.

​
Output

A successful call returns an empty response_code; codes are populated on failure and are bare numbers (1013, 1020). Some failures carry no code at all and put everything in the message — save_appointment reports an unknown provider as Code: 100. Message: Provider Not Found. As with the other write tools, PracticeSuite reports failure in the response body rather than the HTTP status, and success: false (or the string "False") becomes a tool error carrying response_code and response_msg.

​
Limits and caveats

  • The patient must already exist — call practicesuite_save_patient first. The appointment references the patient by the natural key (patid on the wire), not the internal UUID.
  • The client supplies the parts of the envelope that never vary: the fixed action: save, apptStatus: CONFIRMED, apptType: APPOINTMENT, and an id derived from the patient key and the scheduled slot. That id is deterministic on purpose — a step retried after a lost response re-sends the same key rather than minting a new one, which is the only dedupe lever available while PracticeSuite exposes no readable appointment endpoint.
  • scheduled_date is passed through verbatim. Convert local clinic times to UTC before calling.
  • Whether PracticeSuite treats id as a dedupe key is unconfirmed — repeat calls with the same id, and different ids in the same slot, all return success, and there is no readable appointment endpoint to check against. The deterministic id makes a retry a no-op if the id is honoured; if it is not, a retry may still duplicate. (practicesuite_save_patient is confirmed to upsert.)

​
Agent Instruction Guidance

Book the appointment after the patient write succeeds, using the same patient_pcref you saved with. Do not pass a patient_id from practicesuite_get_patient here — this endpoint expects the natural key.