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

# Appointments API

> Schedule appointments and manage availability through the Goliath developer 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](/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.                                                                                                                                      |

<Warning>
  **Check `calendarSync` before reporting an invite**

  Both 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.
</Warning>

<Note>
  **Organization guard**

  Any 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](/developer-api/authorization) for the model.
</Note>

## Example

Create an appointment:

```bash theme={null}
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](/developer-api/overview#discovering-operations).