Guides / Appointments API

Appointments API

Check calendar conflicts, manage appointments and SMS reminders, and configure booking availability through the Goliath developer API

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)

operationId	What it does
`listAppointments`	List appointments — org-wide for a team-admin key, the key owner’s own otherwise. Filter by participants, a `startDate`/`endDate` window, `completed`, or `searchTerm`. Returns `tasks`, the unpaged `total`, and `canFetchNext`; `limit` defaults to 25, capped at 50. Page forward with `cursor`.
`checkAvailability`	Check a proposed slot against Goliath appointments and connected Google/Microsoft calendars. Requires `userIds`, `startDate`, and `endDate`; optionally pass `excludeAppointmentId` when rescheduling. Returns `available` and overlapping `conflicts`. See the participant and completeness rules below.
`listAppointmentReminders`	List the organization’s appointment reminders, each with SMS `steps` ordered longest lead time first and `isGlobal` marking the flagged default. Use a reminder’s id as `appointmentReminderWorkflowGroupId` when creating or updating an appointment.
`getMyAvailabilitySchedule`	Fetch the key owner’s saved availability schedule — timezone, weekly hours, and per-date overrides. Null means no schedule was saved. Read this before `setMyAvailabilitySchedule` to get the current values.

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)

operationId	What it does
`createAppointment`	Create an appointment. Requires title, timezone, startDate, and endDate; optionally set location, description, linked contacts, participants, and a reminder. No default reminder is applied: pass `appointmentReminderWorkflowGroupId` explicitly. Attempts an external calendar event by default; pass `createCalendarEvent: false` for Goliath-only. The organizer is the key owner, except when `userIds` contains exactly one other teammate, who becomes the organizer. Double-booking is allowed; run `checkAvailability` first.
`updateAppointment`	Update an appointment by id — times, location, description, outcome; add/remove participants and linked contacts; switch or clear the reminder. Existing external events are updated. Pass `createCalendarEvent: true` to create a missing event.
`deleteAppointment`	Delete an appointment by id. Also removes the synced calendar event, if any.
`setMyAvailabilitySchedule`	Create or replace the key owner’s availability schedule (full replacement — read `getMyAvailabilitySchedule` first and send back a modified copy). Drives the open slots booking pages offer.

Appointment reminders (`WRITE` scope)

operationId	What it does
`createAppointmentReminder`	Create a reminder with `steps`, each containing `message`, positive `amountBefore`, and `unitBefore: MINUTES`, `HOURS`, or `DAYS`. Pass `isGlobal: true` to make it the organization default. List existing reminders first to avoid duplicates.
`updateAppointmentReminder`	Edit an `appointmentReminderId`. `steps` replaces the whole set: keep every step you still want. Omitting `isGlobal` preserves its flag; true makes it the default and false clears that flag.
`setDefaultAppointmentReminder`	Set or clear `isGlobal` for an `appointmentReminderId` without changing messages or timing. Setting it true clears the previous default’s flag.
`deleteAppointmentReminder`	Delete an `appointmentReminderId` and stop its scheduled texts, including those on existing appointments. If another dependency blocks deletion, preview with `getDeletionImpact(targetKind: WORKFLOW_GROUP, targetId: ...)` and pass its `dependencyResolution`.

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.

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.

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.

{
  "operationId": "setMyAvailabilitySchedule",
  "variables": {
    "timezone": "America/Chicago",
    "weeklyHours": [
      { "day": 1, "intervals": [{ "start": "09:00", "end": "17:00" }] },
      { "day": 3, "intervals": [{ "start": "09:00", "end": "17:00" }] }
    ],
    "dateOverrides": [
      { "date": "2026-12-24", "intervals": [] },
      { "startDate": "2026-12-29", "endDate": "2027-01-02", "intervals": [], "repeat": "yearly" }
    ]
  }
}

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.

Example

Create an appointment:

curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operationId": "createAppointment",
    "variables": {
      "title": "Property walkthrough",
      "timezone": "EST",
      "startDate": "2026-09-01T15:00:00Z",
      "endDate": "2026-09-01T16:00:00Z"
    }
  }'

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