Skip to main content

​
About

Check calendar conflicts, schedule appointments, attach SMS reminders and linked contacts, and read or replace the key owner’s availability schedule. An integration can book, reschedule, and cancel appointments and configure the open slots the booking pages offer. All operations go through the developer API gateway — one endpoint, called by operationId. If you haven’t set up a key yet, start with the Developer API Overview.

​
Operations

​
Reading appointments and availability (READ scope)

When users.getUserAppointments.canFetchNext is true, call again with the same filters and cursor set to the last appointment’s id. Repeat until false. There is no backward cursor; restart without one to revisit earlier rows. appointmentReminderQuery.listAppointmentReminders returns each reminder’s id, createdAt, isGlobal, and steps. Each step contains message, amountBefore, and unitBefore for one SMS and its lead time. Read those fields from each step; they are no longer top-level reminder fields.

​
Writing appointments and availability (WRITE scope)

Check calendarSync before reporting an inviteBoth appointment writes return calendarSync. Only SYNCED means the external Google/Microsoft event exists and guests were invited. NOT_REQUESTED, SKIPPED_NO_ACCESS, SKIPPED_WRITE_BLOCKED, and FAILED mean the appointment was recorded in Goliath but the external calendar did not reach the requested state. On an update, guests may still see the old time. Report that distinction explicitly.

​
Appointment reminders (WRITE scope)

The default is automatically attached to booking-page and AI-employee bookings and preselected in the app’s appointment form. It does not attach to existing appointments or to createAppointment calls; attach it explicitly with the appointment writes. When no reminder is flagged and exactly one exists, that reminder acts as the default anyway. Creating the first reminder can therefore start texts on new bookings without isGlobal: true.
Reminders text the appointment’s contacts automaticallyConfirm every message and lead time before creating or changing a reminder. APPOINTMENT merge fields are supported; a step is skipped when a field cannot be filled. On an update, removed steps stop sending on existing bookings, retained steps’ scheduled texts pick up the edit, and new steps reach only appointments booked afterward. Deletion stops upcoming reminder texts and cannot restore those runs.

​
Checking a slot

Call checkAvailability before creating or rescheduling an appointment. userIds must contain at least one participant; the server deduplicates ids and accepts at most 100 distinct participants. endDate must be after startDate. Users must be in your organization or visible through a partnership; an inaccessible id rejects the whole check.
  • Creating: check every proposed participant plus the key owner (their id comes from getMyProfile). If the appointment names exactly one other teammate, check that teammate alone: their calendar will host the event.
  • Rescheduling: check the resulting full participant set, accounting for both additions and removals, plus the key owner. Update-time calendar sync runs as the key owner. Pass excludeAppointmentId for the appointment being moved so it does not conflict with itself.
Read availabilityQuery.availabilityForSlot. Each conflict has start, end, and source (LOCAL, GOOGLE, or MICROSOFT); local conflicts also carry appointmentId and title. An external title can be null when the key owner cannot read that calendar’s details.
No conflicts found is not a guaranteeavailable: true means no conflicts were found on the calendars checked. Unconnected calendars cannot be checked, and provider failures can return no external conflicts without a failure flag. Name the participants checked and avoid promising that the slot is free. listAppointments only reads appointments recorded in Goliath and is not a substitute for this check.When a reschedule overlaps the old slot and the key owner organizes without being a participant, the old provider event can still appear as a conflict despite excludeAppointmentId. Provider busy ranges may also include a different event, so confirm that conflict against the calendar before booking over it. Conflicts do not prevent a write; double-booking is allowed.

​
Availability schedule shape

setMyAvailabilitySchedule replaces the schedule. Send an IANA timezone (such as America/Chicago) and weeklyHours, a non-empty list of weekday rules. day is 0–6 (Sunday–Saturday); omitted weekdays are not bookable. Each rule contains intervals with strict 24-hour HH:MM start/end times. Optional dateOverrides replaces the weekly hours for a single date or a startDate/endDate span, using YYYY-MM-DD dates. Empty intervals blocks that date or span. Add repeat: "monthly" or "yearly" for recurring exceptions; omit it for a one-time absence.
The whole save is rejected for an empty weeklyHours, invalid dates or times, an interval ending at or before its start, or overlapping intervals. Touching intervals are allowed. A span needs distinct start/end dates; a one-time span’s end must be later. Only recurring spans can wrap with an end that reads earlier than the start. Use a date override to block a week; clearing weeklyHours is invalid.
Organization guardAppointment writes validate appointment, contact, participant, and reminder access. The gateway pre-checks the declared contact, participant, and reminder ids on create/update; other checks run inside the operation. An inaccessible pre-checked id returns 403 forbidden; operation-level refusals appear in the response’s errors. checkAvailability separately accepts same-org or partnership-visible participants. The saved availability operations (getMyAvailabilitySchedule, setMyAvailabilitySchedule) take no entity id and always act on your own schedule. See Authorization for the model.

​
Example

Create an appointment:
Full variable schemas, response shapes, and worked examples for every operation are available from the discovery endpoint.