Skip to main content
Use the environment variables from the quickstart. Request the action scopes listed in Authentication, and set APPOINTMENT_ID to an ID returned by booking or appointment search.
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.
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.
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.
Updates and cancellations affect real appointments. If an outcome is unknown, stop and follow the recovery guidance rather than retrying automatically.
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 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.
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 to distinguish unsupported operations, stale selections, and unconfirmed writes.