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

# Manage appointments

> Read and search Spark snapshots, then update or cancel supported appointments.

Use the environment variables from the [quickstart](https://docs.sparkserv.com/quickstart.md). Request the action scopes listed in [Authentication](https://docs.sparkserv.com/authentication.md), and set `APPOINTMENT_ID` to an ID returned by booking or appointment search.

> [!NOTE]
>
> Appointment reads and searches return Spark's local snapshots. They do not refresh the scheduler or prove the outcome of an unconfirmed upstream write.

## Read an appointment

Requires `appointments:read`.

```bash theme={null}
export APPOINTMENT_ID='appointment-uuid-from-your-response'

curl --fail-with-body --silent --show-error \
  "$SPARK_API_URL/public/v1/appointments/$APPOINTMENT_ID" \
  --header "Authorization: Bearer $SPARK_ACCESS_TOKEN"
```

The response includes the appointment's status, time, timezone, customer, vehicle, services, and recorded scheduling selections. Some values can be `null`. Status values include `Pending`, `Canceled`, `Showed`, `Missed`, `Duplicate`, `Completed`, and `Sold`; they are not instructions to write a new status.

## Search appointments

Requires `appointments:read` and `Dealership-Id`. Supply a customer or date filter. This example uses a customer ID from an authorized customer record or an appointment's `customer.id`.

```bash theme={null}
export CUSTOMER_ID='customer-uuid-from-your-response'

curl --fail-with-body --silent --show-error \
  "$SPARK_API_URL/public/v1/appointments/search" \
  --header "Authorization: Bearer $SPARK_ACCESS_TOKEN" \
  --header "Dealership-Id: $DEALERSHIP_ID" \
  --header 'Content-Type: application/json' \
  --data "$(jq -n --arg customerId "$CUSTOMER_ID" \
    '{customerId: $customerId, limit: 50}')"
```

You can also filter with `startDate` and `endDate`, which are inclusive dealership-local dates.

Search responses contain `items` and `nextCursor`. To fetch the next page, repeat the same filters with `cursor` set to the previous response's `nextCursor`. Stop when `nextCursor` is `null`. The default `limit` is 50, with a supported range of 1 to 100. Customer search uses the same pagination shape.

## Update an appointment

Requires `appointments:update`. Update support depends on the scheduler and the requested change.

> [!WARNING]
>
> Updates and cancellations affect real appointments. If an outcome is unknown, stop and follow the [recovery guidance](https://docs.sparkserv.com/guides/errors-and-retries.md) rather than retrying automatically.

```bash theme={null}
curl --fail-with-body --silent --show-error \
  --request PATCH \
  "$SPARK_API_URL/public/v1/appointments/$APPOINTMENT_ID" \
  --header "Authorization: Bearer $SPARK_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"comments":"Customer requested a call before additional work."}'
```

Supply at least one supported field: `appointmentAt`, `services`, `advisorId`, `transportId`, or `comments`.

* Omitted fields preserve their current values. Do not send `null` as a substitute for omission.
* Supplying `services` replaces the selected services. Include the complete desired list, not just additions; it must contain at least one service.
* Before changing the time or scheduling selections, repeat the relevant [discovery steps](https://docs.sparkserv.com/guides/book-an-appointment.md) and use a returned time with `Z` or an explicit offset.
* Moving an appointment between customers, vehicles, or dealerships is not supported by this update payload.

Successful updates return an object containing `id`. A scheduler can reject an unsupported change even when the request is structurally valid.

If you receive `REPLACEMENT_PARTIAL_FAILURE`, the original appointment was canceled and the replacement was not confirmed. Request operator review; do not issue another booking automatically.

## Cancel an appointment

Requires `appointments:cancel`. Cancellation requires a scheduler-backed appointment and a supported, available integration. Only pending appointments can be canceled.

```bash theme={null}
curl --fail-with-body --silent --show-error \
  --request DELETE \
  "$SPARK_API_URL/public/v1/appointments/$APPOINTMENT_ID" \
  --header "Authorization: Bearer $SPARK_ACCESS_TOKEN"
```

A successful cancellation returns an object containing `id`. Repeating cancellation of an appointment already marked canceled locally succeeds without another scheduler write. This does **not** make it safe to blindly retry a cancellation with an unknown outcome.

Use [Errors and safe retries](https://docs.sparkserv.com/guides/errors-and-retries.md) to distinguish unsupported operations, stale selections, and unconfirmed writes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.