Appointments API

About

Schedule and manage appointments, attach SMS reminders and linked contacts, and read or replace the key owner’s availability schedule. Enough for an integration or agent to book, reschedule, and cancel appointments and to drive 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. Optionally filter by participants, a startDate/endDate window, completed, and a searchTerm.
`listAppointmentReminders`	List the organization’s appointment reminders (SMS sent to the contact before an appointment). 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. Read this before `setMyAvailabilitySchedule` to get the current values.

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. By default it also attempts to create an event on the key owner’s connected calendar; pass `createCalendarEvent: false` for Goliath-only. Double-booking is allowed.
`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.

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.listAppointments is not a complete provider-level availability check, so a clear result means only that the visible Goliath calendar looks clear — not that every participant is free.

Organization guardAny appointment, contact, or reminder id you pass is org-guarded — supplying a foreign organization’s id returns 403 forbidden. This covers the appointmentId on update/delete, contactIds/addContactIds, participant userIds/addUserIds, and the appointmentReminderWorkflowGroupId. The availability operations (getMyAvailabilitySchedule, setMyAvailabilitySchedule) take no entity id and always act on your own schedule. See Authorization for the model.

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.

Getting Started

TypeScript SDK

Core Resources

Automations

Communication & Tasks

Account & Billing

About

Operations

Reading appointments and availability (`READ` scope)

Writing appointments and availability (`WRITE` scope)

Example

​About

​Operations

​Reading appointments and availability (READ scope)

​Writing appointments and availability (WRITE scope)

​Example

About

Operations

Reading appointments and availability (`READ` scope)

Writing appointments and availability (`WRITE` scope)

Example