> ## Documentation Index
> Fetch the complete documentation index at: https://agents.nanonets.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PracticeSuite Save Appointment

> Books a PracticeSuite appointment against a patient natural key.

# 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](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`](practicesuite-get-patient.md) 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

```json theme={null}
{
  "success": true,
  "response_code": "",
  "response_msg": "Appointment saved successfully"
}
```

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.