> For the complete documentation index, see [llms.txt](https://developers.gleantap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gleantap.com/api-reference-v3/appointments.md).

# Appointments

One-off scheduled meetings or calls between a contact and staff, with `starts_at` / `ends_at`, an appointment type, and one or more responsible staff. Booking an appointment can trigger flows and is available to segments. Cancel with `POST /appointments/{id}/cancel` (keeps the record, status `Cancelled`) or `DELETE` (removes it).

Looking for a reusable booking page? See [Calendars](https://developers.gleantap.com/api-reference-v3/calendars.md).

## List appointments.

> Filter by any of \`contact\_id\`, \`responsible\_id\`, \`appointment\_type\_id\`, \`status\`, and a \`starts\_at\` range (\`gte\`/\`gt\`/\`lte\`/\`lt\`). Defaults to \`\_id\` DESC (most-recently-created first). Pass \`?sort=due\_at\` (or \`-due\_at\`) to sort server-side by the appointment's actual date/time instead; \`created\_at\`/\`-created\_at\` is also accepted as an alias for the default \`\_id\`-based order.\
> \
> Unlike most list endpoints, an omitted \`workroom\` defaults to the caller's own workroom, not account-wide — pass \`workroom=all\` for the old account-wide behavior. An explicit workroom id/name is unaffected either way.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Appointments","description":"Scheduled meetings/calls between contacts and staff, with a title, `starts_at` / `ends_at`, `appointment_type`, and one or more responsible staff. Writes mirror to `externalevents` (type=appointment) so segment DSL like `appointments.status = Upcoming` and flow triggers \"on appointment booked\" continue to work. Cancel via `POST /appointments/{id}/cancel` (soft, sets status=Cancelled + mirrors) or DELETE (hard). If the user says \"calendar meeting\" or \"calendar invite\" (e.g. \"create a calendar,\" \"create a calendar meeting,\" \"create a calendar invite\"), they mean the Calendars resource below - a reusable booking page - not one of these one-off appointments."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}},"SortParam":{"name":"sort","in":"query","required":false,"description":"Comma-separated list of fields to sort by. Leading `-` reverses. Default `-created_at`. Sortable fields vary per resource; unsortable fields return 400 `invalid_sort_field`.\n","schema":{"type":"string"}}},"schemas":{"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"AppointmentTypeId":{"type":"string","pattern":"^atyp_[0-9a-f]{24}$"},"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"Appointment":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AppointmentId"},"object":{"type":"string","enum":["appointment"]},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["Upcoming","Completed","Cancelled","No Show","Rescheduled"]},"contact_id":{"$ref":"#/components/schemas/ContactId","nullable":true},"contact_name":{"type":"string","nullable":true},"contact_invite":{"type":"boolean"},"appointment_type_id":{"$ref":"#/components/schemas/AppointmentTypeId","nullable":true},"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"}},"calendar_id":{"$ref":"#/components/schemas/CalendarId","nullable":true,"description":"Booking calendar this appointment is linked to (legacy `meeting_id`)."},"starts_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO datetime with the account's real UTC offset attached (e.g. \"2026-10-20T10:00:00-05:00\") — the appointment start, in the account's own configured timezone. Combines `due_on` (date) + `start_time` (HH:MM)."},"ends_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO datetime with the account's real UTC offset attached, same as `starts_at` — the appointment end."},"due_on":{"$ref":"#/components/schemas/Timestamp"},"start_time":{"type":"string","nullable":true,"description":"HH:MM string (raw legacy field)."},"end_time":{"type":"string","nullable":true},"google_event_id":{"type":"string","nullable":true},"microsoft_event_id":{"type":"string","nullable":true},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"cancelled_at":{"$ref":"#/components/schemas/Timestamp"},"is_overdue":{"type":"boolean","readOnly":true,"description":"Read-only. The dashboard's red \"past date\" flag: true when the appointment's date is before today in the WORKROOM's timezone. Date-only — `start_time` is ignored, so an appointment earlier today is not yet overdue — and status is NOT considered: a Completed or Cancelled appointment on a past date is also true, exactly as the dashboard paints it. Combine with `status: Upcoming` to find appointments that were never resolved. Computed at read time, never stored."}}},"AppointmentId":{"type":"string","pattern":"^apt_[0-9a-f]{24}$"},"CalendarId":{"type":"string","pattern":"^cal_[0-9a-fA-F]{24}$","description":"Bookable calendar ID."},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/appointments":{"get":{"tags":["Appointments"],"operationId":"listAppointments","summary":"List appointments.","description":"Filter by any of `contact_id`, `responsible_id`, `appointment_type_id`, `status`, and a `starts_at` range (`gte`/`gt`/`lte`/`lt`). Defaults to `_id` DESC (most-recently-created first). Pass `?sort=due_at` (or `-due_at`) to sort server-side by the appointment's actual date/time instead; `created_at`/`-created_at` is also accepted as an alias for the default `_id`-based order.\n\nUnlike most list endpoints, an omitted `workroom` defaults to the caller's own workroom, not account-wide — pass `workroom=all` for the old account-wide behavior. An explicit workroom id/name is unaffected either way.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"},{"$ref":"#/components/parameters/SortParam"},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"type":"object","properties":{"status":{"type":"string","enum":["Upcoming","Completed","Cancelled","No Show","Rescheduled"]},"contact_id":{"$ref":"#/components/schemas/ContactId"},"responsible_id":{"$ref":"#/components/schemas/StaffId"},"appointment_type_id":{"$ref":"#/components/schemas/AppointmentTypeId"},"starts_at":{"type":"object","properties":{"gte":{"type":"string","format":"date-time"},"lte":{"type":"string","format":"date-time"},"gt":{"type":"string","format":"date-time"},"lt":{"type":"string","format":"date-time"}}}}}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Appointment"}}}}]}}}}}}}}}
```

## Create an appointment.

> A single scheduled meeting with a contact, at a fixed date and time. This is distinct from a Gleantap Calendar, which is a reusable bookable page other people use to schedule their own time; that is created with createCalendar. The phrases "calendar meeting" and "calendar invite" describe that bookable page rather than an appointment.\
> \
> \`starts\_at\` is required (ISO datetime). Storage splits it into legacy \`due\_on\` (midnight of the date) + \`start\_time\` (HH:MM). Every write mirrors to \`externalevents\` so segment-DSL predicates like \`appointments.status = Upcoming\` see the new record.\
> \
> The distinction from a Calendar matters because the vocabulary overlaps: "calendar invite" and "calendar meeting" both name a reusable booking page (POST /calendars), even though "invite" and "meeting" sound appointment-like. This endpoint creates one specific, already-scheduled meeting with a real start time.\
> \
> \`starts\_at\` is required; \`ends\_at\` is not, but an appointment without it has no length and renders no duration on a calendar. When both are given, \`ends\_at\` must resolve to a later instant than \`starts\_at\` - an end at or before the start is rejected. An appointment with no \`responsible\_ids\` is unassigned. \`contact\_id\` links the appointment to an existing contact; an appointment without it is not attached to anyone. \`appointment\_type\_id\`, if given, must match a real appointment type in this account - a well-formed but nonexistent id is rejected rather than saved as a dangling reference, and the error lists the account's existing types (or says none exist yet) so the caller can offer a pick-or-create choice. \`contact\_id\`, if given as a raw id (not an \`external\_id:\` reference), must likewise match a real contact in this account - rejected rather than saved as an orphaned reference linked to no one.\
> \
> Requires the contact, the time and the appointment type. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Appointments","description":"Scheduled meetings/calls between contacts and staff, with a title, `starts_at` / `ends_at`, `appointment_type`, and one or more responsible staff. Writes mirror to `externalevents` (type=appointment) so segment DSL like `appointments.status = Upcoming` and flow triggers \"on appointment booked\" continue to work. Cancel via `POST /appointments/{id}/cancel` (soft, sets status=Cancelled + mirrors) or DELETE (hard). If the user says \"calendar meeting\" or \"calendar invite\" (e.g. \"create a calendar,\" \"create a calendar meeting,\" \"create a calendar invite\"), they mean the Calendars resource below - a reusable booking page - not one of these one-off appointments."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"AppointmentCreate":{"type":"object","required":["title","starts_at"],"properties":{"title":{"type":"string"},"description":{"type":"string"},"contact_id":{"$ref":"#/components/schemas/ContactId"},"contact_name":{"type":"string","description":"Optional; used when contact_id is missing."},"contact_invite":{"type":"boolean","description":"True → the contact is emailed a calendar invite (.ics) on create, and a \"Revised:\" invite whenever title/description/type/staff/date/time later change. Default false."},"calendar_id":{"$ref":"#/components/schemas/CalendarId","description":"Optional booking calendar to link. Its reminders are copied onto the appointment (sent by the reminder job while status is Upcoming) and it is stored as the appointment's meeting_id, the same as a booking made on that calendar."},"appointment_type_id":{"$ref":"#/components/schemas/AppointmentTypeId"},"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"}},"starts_at":{"type":"string","format":"date-time","description":"REQUIRED. ISO datetime; the model derives storage `due_on` + `start_time` from it. Must resolve to a future instant — a past value is rejected. An offset-less value is interpreted in the account's own configured timezone, not UTC. A value carrying `Z` or an offset is converted into the account's timezone before storage (the dashboard stores the account-local date + HH:MM), so it reads back as the same instant with the account's offset — e.g. `14:00:00Z` in an Asia/Kolkata account reads back as `19:30:00+05:30`; an offset-less `14:00:00` reads back as `14:00:00+05:30`."},"ends_at":{"type":"string","format":"date-time","description":"No default — an appointment with no end time won't display a duration; confirm with the user or default to +30min if they say they don't care."},"google_event_id":{"type":"string"},"microsoft_event_id":{"type":"string"},"created_by":{"$ref":"#/components/schemas/StaffId","description":"Defaults to the calling staff user, or the account owner for API keys. Newly assigned staff are emailed (subject to the workroom's CRM notification settings)."}}},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"CalendarId":{"type":"string","pattern":"^cal_[0-9a-fA-F]{24}$","description":"Bookable calendar ID."},"AppointmentTypeId":{"type":"string","pattern":"^atyp_[0-9a-f]{24}$"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Appointment":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AppointmentId"},"object":{"type":"string","enum":["appointment"]},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["Upcoming","Completed","Cancelled","No Show","Rescheduled"]},"contact_id":{"$ref":"#/components/schemas/ContactId","nullable":true},"contact_name":{"type":"string","nullable":true},"contact_invite":{"type":"boolean"},"appointment_type_id":{"$ref":"#/components/schemas/AppointmentTypeId","nullable":true},"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"}},"calendar_id":{"$ref":"#/components/schemas/CalendarId","nullable":true,"description":"Booking calendar this appointment is linked to (legacy `meeting_id`)."},"starts_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO datetime with the account's real UTC offset attached (e.g. \"2026-10-20T10:00:00-05:00\") — the appointment start, in the account's own configured timezone. Combines `due_on` (date) + `start_time` (HH:MM)."},"ends_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO datetime with the account's real UTC offset attached, same as `starts_at` — the appointment end."},"due_on":{"$ref":"#/components/schemas/Timestamp"},"start_time":{"type":"string","nullable":true,"description":"HH:MM string (raw legacy field)."},"end_time":{"type":"string","nullable":true},"google_event_id":{"type":"string","nullable":true},"microsoft_event_id":{"type":"string","nullable":true},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"cancelled_at":{"$ref":"#/components/schemas/Timestamp"},"is_overdue":{"type":"boolean","readOnly":true,"description":"Read-only. The dashboard's red \"past date\" flag: true when the appointment's date is before today in the WORKROOM's timezone. Date-only — `start_time` is ignored, so an appointment earlier today is not yet overdue — and status is NOT considered: a Completed or Cancelled appointment on a past date is also true, exactly as the dashboard paints it. Combine with `status: Upcoming` to find appointments that were never resolved. Computed at read time, never stored."}}},"AppointmentId":{"type":"string","pattern":"^apt_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"Unprocessable":{"description":"Semantic validation failed — the request is well-formed but references an object in the wrong state (e.g., sending to an opted-out contact).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/appointments":{"post":{"tags":["Appointments"],"operationId":"createAppointment","summary":"Create an appointment.","description":"A single scheduled meeting with a contact, at a fixed date and time. This is distinct from a Gleantap Calendar, which is a reusable bookable page other people use to schedule their own time; that is created with createCalendar. The phrases \"calendar meeting\" and \"calendar invite\" describe that bookable page rather than an appointment.\n\n`starts_at` is required (ISO datetime). Storage splits it into legacy `due_on` (midnight of the date) + `start_time` (HH:MM). Every write mirrors to `externalevents` so segment-DSL predicates like `appointments.status = Upcoming` see the new record.\n\nThe distinction from a Calendar matters because the vocabulary overlaps: \"calendar invite\" and \"calendar meeting\" both name a reusable booking page (POST /calendars), even though \"invite\" and \"meeting\" sound appointment-like. This endpoint creates one specific, already-scheduled meeting with a real start time.\n\n`starts_at` is required; `ends_at` is not, but an appointment without it has no length and renders no duration on a calendar. When both are given, `ends_at` must resolve to a later instant than `starts_at` - an end at or before the start is rejected. An appointment with no `responsible_ids` is unassigned. `contact_id` links the appointment to an existing contact; an appointment without it is not attached to anyone. `appointment_type_id`, if given, must match a real appointment type in this account - a well-formed but nonexistent id is rejected rather than saved as a dangling reference, and the error lists the account's existing types (or says none exist yet) so the caller can offer a pick-or-create choice. `contact_id`, if given as a raw id (not an `external_id:` reference), must likewise match a real contact in this account - rejected rather than saved as an orphaned reference linked to no one.\n\nRequires the contact, the time and the appointment type. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentCreate"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Appointment"}}}},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## Retrieve one appointment.

> Time, attendees, type, status and the linked contact. Times come back as \`starts\_at\`/\`ends\_at\` in ISO form.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Appointments","description":"Scheduled meetings/calls between contacts and staff, with a title, `starts_at` / `ends_at`, `appointment_type`, and one or more responsible staff. Writes mirror to `externalevents` (type=appointment) so segment DSL like `appointments.status = Upcoming` and flow triggers \"on appointment booked\" continue to work. Cancel via `POST /appointments/{id}/cancel` (soft, sets status=Cancelled + mirrors) or DELETE (hard). If the user says \"calendar meeting\" or \"calendar invite\" (e.g. \"create a calendar,\" \"create a calendar meeting,\" \"create a calendar invite\"), they mean the Calendars resource below - a reusable booking page - not one of these one-off appointments."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"Appointment":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AppointmentId"},"object":{"type":"string","enum":["appointment"]},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["Upcoming","Completed","Cancelled","No Show","Rescheduled"]},"contact_id":{"$ref":"#/components/schemas/ContactId","nullable":true},"contact_name":{"type":"string","nullable":true},"contact_invite":{"type":"boolean"},"appointment_type_id":{"$ref":"#/components/schemas/AppointmentTypeId","nullable":true},"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"}},"calendar_id":{"$ref":"#/components/schemas/CalendarId","nullable":true,"description":"Booking calendar this appointment is linked to (legacy `meeting_id`)."},"starts_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO datetime with the account's real UTC offset attached (e.g. \"2026-10-20T10:00:00-05:00\") — the appointment start, in the account's own configured timezone. Combines `due_on` (date) + `start_time` (HH:MM)."},"ends_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO datetime with the account's real UTC offset attached, same as `starts_at` — the appointment end."},"due_on":{"$ref":"#/components/schemas/Timestamp"},"start_time":{"type":"string","nullable":true,"description":"HH:MM string (raw legacy field)."},"end_time":{"type":"string","nullable":true},"google_event_id":{"type":"string","nullable":true},"microsoft_event_id":{"type":"string","nullable":true},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"cancelled_at":{"$ref":"#/components/schemas/Timestamp"},"is_overdue":{"type":"boolean","readOnly":true,"description":"Read-only. The dashboard's red \"past date\" flag: true when the appointment's date is before today in the WORKROOM's timezone. Date-only — `start_time` is ignored, so an appointment earlier today is not yet overdue — and status is NOT considered: a Completed or Cancelled appointment on a past date is also true, exactly as the dashboard paints it. Combine with `status: Upcoming` to find appointments that were never resolved. Computed at read time, never stored."}}},"AppointmentId":{"type":"string","pattern":"^apt_[0-9a-f]{24}$"},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"AppointmentTypeId":{"type":"string","pattern":"^atyp_[0-9a-f]{24}$"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"CalendarId":{"type":"string","pattern":"^cal_[0-9a-fA-F]{24}$","description":"Bookable calendar ID."},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/appointments/{id}":{"get":{"tags":["Appointments"],"operationId":"retrieveAppointment","summary":"Retrieve one appointment.","description":"Time, attendees, type, status and the linked contact. Times come back as `starts_at`/`ends_at` in ISO form.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Appointment"}}}}}}}}}
```

## Update an appointment (partial). Also mirrors to externalevents.

> Only send the fields that are changing - this is a true partial update, nothing is required. To change just one thing (e.g. \`contact\_invite\`), you do not need to also re-send \`title\` or \`starts\_at\`. If you change only one of \`starts\_at\`/\`ends\_at\`, the other is still checked against its current stored value - the effective end must stay after the effective start. Changing \`appointment\_type\_id\` or \`contact\_id\` to a well-formed but nonexistent id is rejected rather than saved as a dangling/orphaned reference.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Appointments","description":"Scheduled meetings/calls between contacts and staff, with a title, `starts_at` / `ends_at`, `appointment_type`, and one or more responsible staff. Writes mirror to `externalevents` (type=appointment) so segment DSL like `appointments.status = Upcoming` and flow triggers \"on appointment booked\" continue to work. Cancel via `POST /appointments/{id}/cancel` (soft, sets status=Cancelled + mirrors) or DELETE (hard). If the user says \"calendar meeting\" or \"calendar invite\" (e.g. \"create a calendar,\" \"create a calendar meeting,\" \"create a calendar invite\"), they mean the Calendars resource below - a reusable booking page - not one of these one-off appointments."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"AppointmentUpdate":{"type":"object","description":"Partial update - every field is optional, only send what's changing. Deliberately a separate schema from `AppointmentCreate` rather than reusing it: that one requires `title` + `starts_at`, which would make a true partial update (e.g. just `contact_invite`) look invalid even though the backend does not actually require either field here.\n","properties":{"title":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["Upcoming","Completed","Cancelled","No Show","Rescheduled"],"description":"Setting `Cancelled` also stamps `cancelled_on`."},"contact_id":{"$ref":"#/components/schemas/ContactId"},"contact_name":{"type":"string","description":"Used when contact_id is missing."},"contact_invite":{"type":"boolean","description":"True → the contact is emailed a (revised) calendar invite when invite-relevant fields change."},"calendar_id":{"$ref":"#/components/schemas/CalendarId","nullable":true,"description":"Link a booking calendar (re-copies its reminders); null unlinks."},"appointment_type_id":{"$ref":"#/components/schemas/AppointmentTypeId"},"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"}},"starts_at":{"type":"string","format":"date-time","description":"ISO datetime. If you change it, it must resolve to a future instant - a past value is rejected UNLESS it is identical to the appointment's current starts_at (re-sending the same value never fails just because that moment has since passed). An offset-less value is interpreted in the account's own configured timezone, not UTC. A value carrying `Z` or an offset is converted into the account's timezone before storage (the dashboard stores the account-local date + HH:MM), so it reads back as the same instant with the account's offset — e.g. `14:00:00Z` in an Asia/Kolkata account reads back as `19:30:00+05:30`; an offset-less `14:00:00` reads back as `14:00:00+05:30`."},"ends_at":{"type":"string","format":"date-time"},"google_event_id":{"type":"string"},"microsoft_event_id":{"type":"string"}}},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"CalendarId":{"type":"string","pattern":"^cal_[0-9a-fA-F]{24}$","description":"Bookable calendar ID."},"AppointmentTypeId":{"type":"string","pattern":"^atyp_[0-9a-f]{24}$"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Appointment":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AppointmentId"},"object":{"type":"string","enum":["appointment"]},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["Upcoming","Completed","Cancelled","No Show","Rescheduled"]},"contact_id":{"$ref":"#/components/schemas/ContactId","nullable":true},"contact_name":{"type":"string","nullable":true},"contact_invite":{"type":"boolean"},"appointment_type_id":{"$ref":"#/components/schemas/AppointmentTypeId","nullable":true},"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"}},"calendar_id":{"$ref":"#/components/schemas/CalendarId","nullable":true,"description":"Booking calendar this appointment is linked to (legacy `meeting_id`)."},"starts_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO datetime with the account's real UTC offset attached (e.g. \"2026-10-20T10:00:00-05:00\") — the appointment start, in the account's own configured timezone. Combines `due_on` (date) + `start_time` (HH:MM)."},"ends_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO datetime with the account's real UTC offset attached, same as `starts_at` — the appointment end."},"due_on":{"$ref":"#/components/schemas/Timestamp"},"start_time":{"type":"string","nullable":true,"description":"HH:MM string (raw legacy field)."},"end_time":{"type":"string","nullable":true},"google_event_id":{"type":"string","nullable":true},"microsoft_event_id":{"type":"string","nullable":true},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"cancelled_at":{"$ref":"#/components/schemas/Timestamp"},"is_overdue":{"type":"boolean","readOnly":true,"description":"Read-only. The dashboard's red \"past date\" flag: true when the appointment's date is before today in the WORKROOM's timezone. Date-only — `start_time` is ignored, so an appointment earlier today is not yet overdue — and status is NOT considered: a Completed or Cancelled appointment on a past date is also true, exactly as the dashboard paints it. Combine with `status: Upcoming` to find appointments that were never resolved. Computed at read time, never stored."}}},"AppointmentId":{"type":"string","pattern":"^apt_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/appointments/{id}":{"patch":{"tags":["Appointments"],"operationId":"updateAppointment","summary":"Update an appointment (partial). Also mirrors to externalevents.","description":"Only send the fields that are changing - this is a true partial update, nothing is required. To change just one thing (e.g. `contact_invite`), you do not need to also re-send `title` or `starts_at`. If you change only one of `starts_at`/`ends_at`, the other is still checked against its current stored value - the effective end must stay after the effective start. Changing `appointment_type_id` or `contact_id` to a well-formed but nonexistent id is rejected rather than saved as a dangling/orphaned reference.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentUpdate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Appointment"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}}}
```

## Hard-delete an appointment + remove the mirrored externalevents row.

> \*\*Permanent.\*\* There is no undo and no trash to restore from. Anything that references the deleted record is affected too.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Appointments","description":"Scheduled meetings/calls between contacts and staff, with a title, `starts_at` / `ends_at`, `appointment_type`, and one or more responsible staff. Writes mirror to `externalevents` (type=appointment) so segment DSL like `appointments.status = Upcoming` and flow triggers \"on appointment booked\" continue to work. Cancel via `POST /appointments/{id}/cancel` (soft, sets status=Cancelled + mirrors) or DELETE (hard). If the user says \"calendar meeting\" or \"calendar invite\" (e.g. \"create a calendar,\" \"create a calendar meeting,\" \"create a calendar invite\"), they mean the Calendars resource below - a reusable booking page - not one of these one-off appointments."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}}},"paths":{"/appointments/{id}":{"delete":{"tags":["Appointments"],"operationId":"deleteAppointment","description":"**Permanent.** There is no undo and no trash to restore from. Anything that references the deleted record is affected too.\n","summary":"Hard-delete an appointment + remove the mirrored externalevents row.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"responses":{"204":{"description":"Deleted."}}}}}}
```

## POST /appointments/{id}/reschedule

> Move an appointment to a new time in-place. Body \`{starts\_at, ends\_at?}\`.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Appointments","description":"Scheduled meetings/calls between contacts and staff, with a title, `starts_at` / `ends_at`, `appointment_type`, and one or more responsible staff. Writes mirror to `externalevents` (type=appointment) so segment DSL like `appointments.status = Upcoming` and flow triggers \"on appointment booked\" continue to work. Cancel via `POST /appointments/{id}/cancel` (soft, sets status=Cancelled + mirrors) or DELETE (hard). If the user says \"calendar meeting\" or \"calendar invite\" (e.g. \"create a calendar,\" \"create a calendar meeting,\" \"create a calendar invite\"), they mean the Calendars resource below - a reusable booking page - not one of these one-off appointments."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"Appointment":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AppointmentId"},"object":{"type":"string","enum":["appointment"]},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["Upcoming","Completed","Cancelled","No Show","Rescheduled"]},"contact_id":{"$ref":"#/components/schemas/ContactId","nullable":true},"contact_name":{"type":"string","nullable":true},"contact_invite":{"type":"boolean"},"appointment_type_id":{"$ref":"#/components/schemas/AppointmentTypeId","nullable":true},"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"}},"calendar_id":{"$ref":"#/components/schemas/CalendarId","nullable":true,"description":"Booking calendar this appointment is linked to (legacy `meeting_id`)."},"starts_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO datetime with the account's real UTC offset attached (e.g. \"2026-10-20T10:00:00-05:00\") — the appointment start, in the account's own configured timezone. Combines `due_on` (date) + `start_time` (HH:MM)."},"ends_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO datetime with the account's real UTC offset attached, same as `starts_at` — the appointment end."},"due_on":{"$ref":"#/components/schemas/Timestamp"},"start_time":{"type":"string","nullable":true,"description":"HH:MM string (raw legacy field)."},"end_time":{"type":"string","nullable":true},"google_event_id":{"type":"string","nullable":true},"microsoft_event_id":{"type":"string","nullable":true},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"cancelled_at":{"$ref":"#/components/schemas/Timestamp"},"is_overdue":{"type":"boolean","readOnly":true,"description":"Read-only. The dashboard's red \"past date\" flag: true when the appointment's date is before today in the WORKROOM's timezone. Date-only — `start_time` is ignored, so an appointment earlier today is not yet overdue — and status is NOT considered: a Completed or Cancelled appointment on a past date is also true, exactly as the dashboard paints it. Combine with `status: Upcoming` to find appointments that were never resolved. Computed at read time, never stored."}}},"AppointmentId":{"type":"string","pattern":"^apt_[0-9a-f]{24}$"},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"AppointmentTypeId":{"type":"string","pattern":"^atyp_[0-9a-f]{24}$"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"CalendarId":{"type":"string","pattern":"^cal_[0-9a-fA-F]{24}$","description":"Bookable calendar ID."},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/appointments/{id}/reschedule":{"post":{"tags":["Appointments"],"operationId":"rescheduleAppointment","summary":"Move an appointment to a new time in-place. Body `{starts_at, ends_at?}`.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["starts_at"],"properties":{"starts_at":{"type":"string","format":"date-time","description":"New start. Must resolve to a future instant; an offset-less value is interpreted in the account's configured timezone, not UTC."},"ends_at":{"type":"string","format":"date-time","description":"New end. If omitted, the appointment's current end is kept and checked against the new starts_at - still must stay after it."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Appointment"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}}}
```

## Soft-cancel: sets status=Cancelled + mirrors to externalevents. To hard-delete, use DELETE /appointments/{id}.

> \*\*Affects something real.\*\* This cancels a scheduled send or a booking a person is expecting.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Appointments","description":"Scheduled meetings/calls between contacts and staff, with a title, `starts_at` / `ends_at`, `appointment_type`, and one or more responsible staff. Writes mirror to `externalevents` (type=appointment) so segment DSL like `appointments.status = Upcoming` and flow triggers \"on appointment booked\" continue to work. Cancel via `POST /appointments/{id}/cancel` (soft, sets status=Cancelled + mirrors) or DELETE (hard). If the user says \"calendar meeting\" or \"calendar invite\" (e.g. \"create a calendar,\" \"create a calendar meeting,\" \"create a calendar invite\"), they mean the Calendars resource below - a reusable booking page - not one of these one-off appointments."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"Appointment":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AppointmentId"},"object":{"type":"string","enum":["appointment"]},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["Upcoming","Completed","Cancelled","No Show","Rescheduled"]},"contact_id":{"$ref":"#/components/schemas/ContactId","nullable":true},"contact_name":{"type":"string","nullable":true},"contact_invite":{"type":"boolean"},"appointment_type_id":{"$ref":"#/components/schemas/AppointmentTypeId","nullable":true},"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"}},"calendar_id":{"$ref":"#/components/schemas/CalendarId","nullable":true,"description":"Booking calendar this appointment is linked to (legacy `meeting_id`)."},"starts_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO datetime with the account's real UTC offset attached (e.g. \"2026-10-20T10:00:00-05:00\") — the appointment start, in the account's own configured timezone. Combines `due_on` (date) + `start_time` (HH:MM)."},"ends_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO datetime with the account's real UTC offset attached, same as `starts_at` — the appointment end."},"due_on":{"$ref":"#/components/schemas/Timestamp"},"start_time":{"type":"string","nullable":true,"description":"HH:MM string (raw legacy field)."},"end_time":{"type":"string","nullable":true},"google_event_id":{"type":"string","nullable":true},"microsoft_event_id":{"type":"string","nullable":true},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"cancelled_at":{"$ref":"#/components/schemas/Timestamp"},"is_overdue":{"type":"boolean","readOnly":true,"description":"Read-only. The dashboard's red \"past date\" flag: true when the appointment's date is before today in the WORKROOM's timezone. Date-only — `start_time` is ignored, so an appointment earlier today is not yet overdue — and status is NOT considered: a Completed or Cancelled appointment on a past date is also true, exactly as the dashboard paints it. Combine with `status: Upcoming` to find appointments that were never resolved. Computed at read time, never stored."}}},"AppointmentId":{"type":"string","pattern":"^apt_[0-9a-f]{24}$"},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"AppointmentTypeId":{"type":"string","pattern":"^atyp_[0-9a-f]{24}$"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"CalendarId":{"type":"string","pattern":"^cal_[0-9a-fA-F]{24}$","description":"Bookable calendar ID."},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/appointments/{id}/cancel":{"post":{"tags":["Appointments"],"operationId":"cancelAppointment","description":"**Affects something real.** This cancels a scheduled send or a booking a person is expecting.\n","summary":"Soft-cancel: sets status=Cancelled + mirrors to externalevents. To hard-delete, use DELETE /appointments/{id}.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Appointment"}}}}}}}}}
```

## Duplicate an appointment.

> Clones the appointment (contact, type, responsible staff, time). Status resets to \`Upcoming\`, cancellation/activity history is cleared, and \`google\_event\_id\`/\`microsoft\_event\_id\` are NOT copied — the duplicate isn't linked to the source's calendar events. Unless \`title\` is overridden, it's suffixed \`" (copy)"\`. The clone's effective \`starts\_at\` (the override if one is given, otherwise the source's own date/time) must resolve to a future instant - same rule as \`createAppointment\`. Duplicating a past appointment without also passing a new, future \`starts\_at\` in the body is rejected with a 422 telling you to supply one. The clone's effective \`ends\_at\` must also stay after its effective \`starts\_at\`, same as \`createAppointment\`. Overriding \`appointment\_type\_id\` or \`contact\_id\` to a well-formed but nonexistent id is rejected rather than saved as a dangling/orphaned reference.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Appointments","description":"Scheduled meetings/calls between contacts and staff, with a title, `starts_at` / `ends_at`, `appointment_type`, and one or more responsible staff. Writes mirror to `externalevents` (type=appointment) so segment DSL like `appointments.status = Upcoming` and flow triggers \"on appointment booked\" continue to work. Cancel via `POST /appointments/{id}/cancel` (soft, sets status=Cancelled + mirrors) or DELETE (hard). If the user says \"calendar meeting\" or \"calendar invite\" (e.g. \"create a calendar,\" \"create a calendar meeting,\" \"create a calendar invite\"), they mean the Calendars resource below - a reusable booking page - not one of these one-off appointments."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"AppointmentTypeId":{"type":"string","pattern":"^atyp_[0-9a-f]{24}$"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Appointment":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AppointmentId"},"object":{"type":"string","enum":["appointment"]},"title":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["Upcoming","Completed","Cancelled","No Show","Rescheduled"]},"contact_id":{"$ref":"#/components/schemas/ContactId","nullable":true},"contact_name":{"type":"string","nullable":true},"contact_invite":{"type":"boolean"},"appointment_type_id":{"$ref":"#/components/schemas/AppointmentTypeId","nullable":true},"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"}},"calendar_id":{"$ref":"#/components/schemas/CalendarId","nullable":true,"description":"Booking calendar this appointment is linked to (legacy `meeting_id`)."},"starts_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO datetime with the account's real UTC offset attached (e.g. \"2026-10-20T10:00:00-05:00\") — the appointment start, in the account's own configured timezone. Combines `due_on` (date) + `start_time` (HH:MM)."},"ends_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO datetime with the account's real UTC offset attached, same as `starts_at` — the appointment end."},"due_on":{"$ref":"#/components/schemas/Timestamp"},"start_time":{"type":"string","nullable":true,"description":"HH:MM string (raw legacy field)."},"end_time":{"type":"string","nullable":true},"google_event_id":{"type":"string","nullable":true},"microsoft_event_id":{"type":"string","nullable":true},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"cancelled_at":{"$ref":"#/components/schemas/Timestamp"},"is_overdue":{"type":"boolean","readOnly":true,"description":"Read-only. The dashboard's red \"past date\" flag: true when the appointment's date is before today in the WORKROOM's timezone. Date-only — `start_time` is ignored, so an appointment earlier today is not yet overdue — and status is NOT considered: a Completed or Cancelled appointment on a past date is also true, exactly as the dashboard paints it. Combine with `status: Upcoming` to find appointments that were never resolved. Computed at read time, never stored."}}},"AppointmentId":{"type":"string","pattern":"^apt_[0-9a-f]{24}$"},"CalendarId":{"type":"string","pattern":"^cal_[0-9a-fA-F]{24}$","description":"Bookable calendar ID."},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unprocessable":{"description":"Semantic validation failed — the request is well-formed but references an object in the wrong state (e.g., sending to an opted-out contact).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/appointments/{id}/duplicate":{"post":{"tags":["Appointments"],"operationId":"duplicateAppointment","summary":"Duplicate an appointment.","description":"Clones the appointment (contact, type, responsible staff, time). Status resets to `Upcoming`, cancellation/activity history is cleared, and `google_event_id`/`microsoft_event_id` are NOT copied — the duplicate isn't linked to the source's calendar events. Unless `title` is overridden, it's suffixed `\" (copy)\"`. The clone's effective `starts_at` (the override if one is given, otherwise the source's own date/time) must resolve to a future instant - same rule as `createAppointment`. Duplicating a past appointment without also passing a new, future `starts_at` in the body is rejected with a 422 telling you to supply one. The clone's effective `ends_at` must also stay after its effective `starts_at`, same as `createAppointment`. Overriding `appointment_type_id` or `contact_id` to a well-formed but nonexistent id is rejected rather than saved as a dangling/orphaned reference.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","description":"All fields optional — overrides applied on top of the cloned appointment.","properties":{"title":{"type":"string","description":"Defaults to \"{original title} (copy)\" when omitted."},"description":{"type":"string"},"contact_id":{"$ref":"#/components/schemas/ContactId"},"contact_name":{"type":"string","description":"Optional; used when contact_id is missing."},"contact_invite":{"type":"boolean","description":"True → the contact is emailed a calendar invite for the copy."},"appointment_type_id":{"$ref":"#/components/schemas/AppointmentTypeId"},"responsible_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"}},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"}}}}}},"responses":{"201":{"description":"Duplicated appointment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Appointment"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## List appointment types (call, demo, walkthrough, etc.).

> Defaults to \`\_id\` DESC (most-recently-created first), 25 per page. Pass the response's \`next\_cursor\` back as \`?cursor=...\` to fetch the next page when \`has\_more\` is true.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Appointments","description":"Scheduled meetings/calls between contacts and staff, with a title, `starts_at` / `ends_at`, `appointment_type`, and one or more responsible staff. Writes mirror to `externalevents` (type=appointment) so segment DSL like `appointments.status = Upcoming` and flow triggers \"on appointment booked\" continue to work. Cancel via `POST /appointments/{id}/cancel` (soft, sets status=Cancelled + mirrors) or DELETE (hard). If the user says \"calendar meeting\" or \"calendar invite\" (e.g. \"create a calendar,\" \"create a calendar meeting,\" \"create a calendar invite\"), they mean the Calendars resource below - a reusable booking page - not one of these one-off appointments."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}}},"schemas":{"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"AppointmentType":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AppointmentTypeId"},"object":{"type":"string","enum":["appointment_type"]},"name":{"type":"string","nullable":true},"color":{"type":"string","nullable":true,"description":"Hex background color used in dashboard calendar UI."}}},"AppointmentTypeId":{"type":"string","pattern":"^atyp_[0-9a-f]{24}$"}}},"paths":{"/appointment_types":{"get":{"tags":["Appointments"],"operationId":"listAppointmentTypes","summary":"List appointment types (call, demo, walkthrough, etc.).","description":"Defaults to `_id` DESC (most-recently-created first), 25 per page. Pass the response's `next_cursor` back as `?cursor=...` to fetch the next page when `has_more` is true.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AppointmentType"}}}}]}}}}}}}}}
```

## Create an appointment type.

> Requires a writable workroom (pass \`?workroom=\<name-or-id>\` if the token spans more than one). \`name\` must be unique within that workroom.\
> \
> Requires the name and duration. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Appointments","description":"Scheduled meetings/calls between contacts and staff, with a title, `starts_at` / `ends_at`, `appointment_type`, and one or more responsible staff. Writes mirror to `externalevents` (type=appointment) so segment DSL like `appointments.status = Upcoming` and flow triggers \"on appointment booked\" continue to work. Cancel via `POST /appointments/{id}/cancel` (soft, sets status=Cancelled + mirrors) or DELETE (hard). If the user says \"calendar meeting\" or \"calendar invite\" (e.g. \"create a calendar,\" \"create a calendar meeting,\" \"create a calendar invite\"), they mean the Calendars resource below - a reusable booking page - not one of these one-off appointments."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"AppointmentTypeCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Required — the appointment type's display name (dashboard-facing). Must be unique within the workroom; a duplicate returns 409 `appointment_type_conflict`."},"color":{"type":"string","description":"Hex background color used in the dashboard calendar UI. Optional."}}},"AppointmentType":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AppointmentTypeId"},"object":{"type":"string","enum":["appointment_type"]},"name":{"type":"string","nullable":true},"color":{"type":"string","nullable":true,"description":"Hex background color used in dashboard calendar UI."}}},"AppointmentTypeId":{"type":"string","pattern":"^atyp_[0-9a-f]{24}$"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"Unprocessable":{"description":"Semantic validation failed — the request is well-formed but references an object in the wrong state (e.g., sending to an opted-out contact).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/appointment_types":{"post":{"tags":["Appointments"],"operationId":"createAppointmentType","summary":"Create an appointment type.","description":"Requires a writable workroom (pass `?workroom=<name-or-id>` if the token spans more than one). `name` must be unique within that workroom.\n\nRequires the name and duration. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentTypeCreate"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentType"}}}},"409":{"description":"An appointment type with this name already exists in the workroom.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## Retrieve one appointment type.

> A bookable meeting type — its name, default duration and the calendar it belongs to. Read-only.\
> \
> An omitted workroom resolves to the account's default workroom, not the whole account - pass \`?workroom=\<name-or-id>\` (or the header) to reach a type that lives in a different workroom.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Appointments","description":"Scheduled meetings/calls between contacts and staff, with a title, `starts_at` / `ends_at`, `appointment_type`, and one or more responsible staff. Writes mirror to `externalevents` (type=appointment) so segment DSL like `appointments.status = Upcoming` and flow triggers \"on appointment booked\" continue to work. Cancel via `POST /appointments/{id}/cancel` (soft, sets status=Cancelled + mirrors) or DELETE (hard). If the user says \"calendar meeting\" or \"calendar invite\" (e.g. \"create a calendar,\" \"create a calendar meeting,\" \"create a calendar invite\"), they mean the Calendars resource below - a reusable booking page - not one of these one-off appointments."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"AppointmentType":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AppointmentTypeId"},"object":{"type":"string","enum":["appointment_type"]},"name":{"type":"string","nullable":true},"color":{"type":"string","nullable":true,"description":"Hex background color used in dashboard calendar UI."}}},"AppointmentTypeId":{"type":"string","pattern":"^atyp_[0-9a-f]{24}$"}}},"paths":{"/appointment_types/{id}":{"get":{"tags":["Appointments"],"operationId":"retrieveAppointmentType","summary":"Retrieve one appointment type.","description":"A bookable meeting type — its name, default duration and the calendar it belongs to. Read-only.\n\nAn omitted workroom resolves to the account's default workroom, not the whole account - pass `?workroom=<name-or-id>` (or the header) to reach a type that lives in a different workroom.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentType"}}}}}}}}}
```

## Update an appointment type (partial).

> Renaming re-checks uniqueness within the workroom.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Appointments","description":"Scheduled meetings/calls between contacts and staff, with a title, `starts_at` / `ends_at`, `appointment_type`, and one or more responsible staff. Writes mirror to `externalevents` (type=appointment) so segment DSL like `appointments.status = Upcoming` and flow triggers \"on appointment booked\" continue to work. Cancel via `POST /appointments/{id}/cancel` (soft, sets status=Cancelled + mirrors) or DELETE (hard). If the user says \"calendar meeting\" or \"calendar invite\" (e.g. \"create a calendar,\" \"create a calendar meeting,\" \"create a calendar invite\"), they mean the Calendars resource below - a reusable booking page - not one of these one-off appointments."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"AppointmentTypeUpdate":{"type":"object","properties":{"name":{"type":"string","description":"Renaming re-checks uniqueness within the workroom; a conflict returns 409 `appointment_type_conflict`."},"color":{"type":"string"}}},"AppointmentType":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/AppointmentTypeId"},"object":{"type":"string","enum":["appointment_type"]},"name":{"type":"string","nullable":true},"color":{"type":"string","nullable":true,"description":"Hex background color used in dashboard calendar UI."}}},"AppointmentTypeId":{"type":"string","pattern":"^atyp_[0-9a-f]{24}$"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/appointment_types/{id}":{"patch":{"tags":["Appointments"],"operationId":"updateAppointmentType","summary":"Update an appointment type (partial).","description":"Renaming re-checks uniqueness within the workroom.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentTypeUpdate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentType"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Another appointment type in this workroom already uses that name.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}}}
```

## Delete an appointment type.

> \*\*Permanent.\*\* There is no undo and no trash to restore from. Anything that references the deleted record is affected too.\
> \
> An omitted workroom resolves to the account's default workroom, not the whole account - pass \`?workroom=\<name-or-id>\` (or the header) to reach a type that lives in a different workroom.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Appointments","description":"Scheduled meetings/calls between contacts and staff, with a title, `starts_at` / `ends_at`, `appointment_type`, and one or more responsible staff. Writes mirror to `externalevents` (type=appointment) so segment DSL like `appointments.status = Upcoming` and flow triggers \"on appointment booked\" continue to work. Cancel via `POST /appointments/{id}/cancel` (soft, sets status=Cancelled + mirrors) or DELETE (hard). If the user says \"calendar meeting\" or \"calendar invite\" (e.g. \"create a calendar,\" \"create a calendar meeting,\" \"create a calendar invite\"), they mean the Calendars resource below - a reusable booking page - not one of these one-off appointments."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/appointment_types/{id}":{"delete":{"tags":["Appointments"],"operationId":"deleteAppointmentType","description":"**Permanent.** There is no undo and no trash to restore from. Anything that references the deleted record is affected too.\n\nAn omitted workroom resolves to the account's default workroom, not the whole account - pass `?workroom=<name-or-id>` (or the header) to reach a type that lives in a different workroom.\n","summary":"Delete an appointment type.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"responses":{"204":{"description":"Deleted."},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
