> 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/calendars.md).

# Calendars

Reusable booking pages (Calendly-style). Each calendar has a public URL slug, a weekly availability schedule, intake fields, and confirmation/reminder messaging. The hosted booking link is returned as `booking_url`.

For a single scheduled meeting, see [Appointments](https://developers.gleantap.com/api-reference-v3/appointments.md).

## List bookable calendars.

> Sorted newest-created first (\`\_id\` descending) - a small \`limit\` returns the most recently created calendars, not necessarily every calendar on the account.\
> \
> By default only non-inactive calendars are returned (status missing/null/empty is treated as active, same as an unset status field). Pass \`filter\[status]=inactive\` for only inactive ones, or \`filter\[status]=all\` to remove the status restriction entirely.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Calendars","description":"Booking calendar meetings (Calendly-style). Each calendar has a public URL slug, weekly availability schedule, capture fields (name/email/phone/dob + custom questions), and post-booking messaging (confirmation, reminders). Booking pages are hosted by the dashboard at `/meeting/{app_id}/{slug}`; the API exposes that URL as `booking_url`. Server-side availability queries and inline booking are deferred to a later phase.\n\nIf the user mentions \"calendar\" at all - \"create a calendar,\" \"calendar invite,\" \"calendar meeting\" - this is the resource they mean: a reusable booking page/link, not a specific scheduled Appointment (see that resource for an actual one-off meeting).\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["calendars:read"]}],"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"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"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"}}},"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`."}}},"Calendar":{"type":"object","properties":{"object":{"type":"string","const":"calendar"},"id":{"$ref":"#/components/schemas/CalendarId"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId"},"name":{"type":"string","nullable":true},"slug":{"type":"string","nullable":true,"description":"Public URL segment. Unique per workroom."},"meeting_type":{"type":"string","enum":["meeting","user"],"description":"Whether this is a general workroom-wide calendar (meeting) or a personal per-staff calendar (user). Not related to how bookings are assigned across staff - see notify_type."},"status":{"type":"string","enum":["active","inactive"]},"booking_url":{"type":"string","nullable":true,"description":"Public dashboard-hosted booking page. Hand this URL to end users."},"assigned_user_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"Each id must be an existing staff member in this account - an id that is well-formed but doesn't exist returns a not-found error rather than being silently accepted."},"duration_minutes":{"type":"integer","nullable":true},"buffer_minutes":{"type":"integer","nullable":true,"description":"Buffer between back-to-back bookings. Cannot be negative."},"minimum_booking_window":{"type":"integer","nullable":true,"description":"Minimum hours ahead a booking can be made. Cannot be negative."},"appointment_type_id":{"type":"string","nullable":true,"description":"The appointment type this calendar books, by id (atyp_...) or by name. An id that is well-formed but doesn't exist in this workroom returns a not-found error - it is never treated as a name. Matching by name is exact and silent: any name that does not match an existing type exactly - including a typo or near-miss - creates a brand new appointment type with no error, which can quietly fill the workroom with unwanted types. List GET /v3/appointment_types first and confirm the exact name (or that a new one is really wanted) with the user instead of guessing."},"notify_type":{"type":"string","nullable":true,"enum":["roundrobin","all"],"description":"How bookings are assigned across assigned_user_ids: one at a time (roundrobin) or all of them (all). This is what the Gleantap dashboard UI itself labels \"Meeting Type\" - do not confuse with the meeting_type field above."},"instructions":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"submit_button_text":{"type":"string","nullable":true},"custom_redirect_url":{"type":"string","nullable":true,"description":"Where a booker is sent right after booking."},"default_capture":{"type":"array","items":{"type":"string","enum":["name","email","phone","dob"]},"description":"Which built-in contact fields the booking form asks for."},"custom_questions":{"type":"array","items":{"$ref":"#/components/schemas/CalendarQuestion"}},"schedule":{"$ref":"#/components/schemas/CalendarSchedule"},"confirmation":{"$ref":"#/components/schemas/CalendarConfirmation"},"reminders":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/CalendarReminder"}},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"CalendarId":{"type":"string","pattern":"^cal_[0-9a-fA-F]{24}$","description":"Bookable calendar ID."},"WorkroomId":{"type":"string","pattern":"^wrm_[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."},"CalendarQuestion":{"type":"object","required":["label"],"properties":{"label":{"type":"string","minLength":1,"description":"Required and must be non-blank - a blank label shows as an unlabeled field on the booking form."},"type":{"type":"string","enum":["text","textarea","select","radio","checkbox","number"],"default":"text"},"required":{"type":"boolean","default":false},"options":{"type":"array","items":{"type":"string"},"description":"Only used for select/radio/checkbox, and required (at least one non-blank option) for those three - otherwise the question can't be answered."}}},"CalendarSchedule":{"type":"object","description":"Weekly availability. Keys are lowercased weekday names; each maps to an array of `{from_time, to_time}` time-of-day slots in the workroom's timezone (24h \"HH:MM\" strings).\n","properties":{"monday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"tuesday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"wednesday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"thursday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"friday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"saturday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"sunday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}}}},"CalendarScheduleSlot":{"type":"object","required":["from_time","to_time"],"description":"to_time must be strictly after from_time, and slots within the same day cannot overlap.","properties":{"from_time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"24-hour HH:MM, 00:00-23:59."},"to_time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"24-hour HH:MM, 00:00-23:59. Must be after from_time."}}},"CalendarConfirmation":{"type":"object","properties":{"type":{"oneOf":[{"type":"array","items":{"type":"string","enum":["sms","email"]}},{"type":"string","enum":["sms","email"]}],"description":"Which channel(s) send a confirmation. The dashboard allows both sms and email enabled at once (a multi-select), so reads always return an array (e.g. [\"sms\",\"email\"], or [\"sms\"] for one channel only, or [] for none). On write, a single string (e.g. \"sms\") is also accepted as a convenience for setting one channel - it is normalized to an array before storage."},"email_subject":{"type":"string"},"message":{"type":"string","maxLength":1530,"description":"The SMS body, sent when sms is one of the enabled channels. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. Longer bodies are rejected with 400 `sms_too_long`."},"email":{"type":"string","description":"The email body (HTML), sent when email is one of the enabled channels. Unlike CalendarReminder below, confirmations can send both channels at once, so each needs its own separate content field."}}},"CalendarReminder":{"type":"object","description":"No two reminders in the same list can fire the same channel at the same due_hour - that would send the contact the identical reminder twice at once. One reminder entry can cover both channels at once (type: [\"sms\",\"email\"]) with separate content per channel below. Merge tags use single braces (e.g. {first_name}) - a double-brace tag like {{contact.first_name}} is rejected in subject/message/email, since that syntax can never resolve here and would otherwise send as literal text. A <script> tag is also rejected in any of these three fields - the email body is real HTML by design, but could still be a stored-XSS risk if a sent-message preview elsewhere ever renders it back to staff unescaped.","properties":{"type":{"oneOf":[{"type":"array","items":{"type":"string","enum":["sms","email"]}},{"type":"string","enum":["sms","email"]}],"default":"sms","description":"Which channel(s) this reminder fires on. The dashboard's own reminder control is a multi-select (one reminder row can fire both sms and email), so reads always return an array (e.g. [\"sms\"], or [\"sms\",\"email\"] for both). On write, a single string (e.g. \"sms\") is also accepted as a convenience for one channel - it is normalized to an array before storage."},"subject":{"type":"string","description":"Required and must be non-blank when email is one of the enabled channels. Not used for sms."},"due_hour":{"type":"string","description":"Hours before the appointment to send, as a numeric string (e.g. \"24\"). Must be a whole number from 1 to 720 (30 days) - 0 would fire at the appointment start time instead of before it, fractional hours like \"0.5\" are rejected, and anything past 720 would never fire for a realistic booking. Defaults to 24 if omitted."},"message":{"type":"string","maxLength":1530,"description":"The sms body. Required and must be non-blank when sms is one of the enabled channels. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. Longer bodies are rejected with 400 `sms_too_long` - carriers reject them at send time. Cannot contain any HTML tag - sms is never rendered as HTML on the recipient's end, so a tag would send as literal markup text."},"email":{"type":"string","description":"The email body (HTML). Required and must be non-blank when email is one of the enabled channels."}}}}},"paths":{"/calendars":{"get":{"tags":["Calendars"],"operationId":"listCalendars","summary":"List bookable calendars.","description":"Sorted newest-created first (`_id` descending) - a small `limit` returns the most recently created calendars, not necessarily every calendar on the account.\n\nBy default only non-inactive calendars are returned (status missing/null/empty is treated as active, same as an unset status field). Pass `filter[status]=inactive` for only inactive ones, or `filter[status]=all` to remove the status restriction entirely.\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"},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"type":"object","properties":{"meeting_type":{"type":"string","enum":["meeting","user"]},"status":{"type":"string","enum":["active","inactive","all"],"default":"active","description":"active (default) excludes inactive calendars; inactive returns only inactive ones; all removes the status restriction."},"q":{"type":"string","description":"Case-insensitive substring match on meeting name."}}}}],"responses":{"200":{"description":"Page of calendars.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Calendar"}}}}]}}}}}}}}}
```

## Create a bookable calendar - this IS what "calendar meeting," "calendar invite," or "create a calendar" mean. Not a single scheduled meeting (that's createAppointment).

> \`meeting\_type: meeting\` for workroom-wide meetings; \`meeting\_type: user\` for per-staff calendars - this kind must have exactly one owner, defaulted to the calling user when the caller is human, otherwise \`assigned\_user\_ids\` must be passed explicitly (an API-key caller has no calling user to default to).\
> \
> Slugs are auto-generated from \`name\` if not supplied and are unique per workroom; conflicts get numeric suffixes automatically.\
> \
> A bookable calendar is defined by six things, and a calendar missing any of them is created successfully but does not work as intended:\
> \
> \- \*\*workroom\*\* — an omitted workroom resolves to the account default. \`listWorkrooms\` returns the alternatives.\
> \- \*\*name\*\*\
> \- \*\*appointment type\*\* — \`listAppointmentTypes\`, scoped to the target workroom, returns the types that already exist. A new name creates a new type.\
> \- \*\*\`assigned\_user\_ids\`\*\* — who the bookings belong to. For \`meeting\_type: meeting\` the candidates come from \`listStaff\`; for \`meeting\_type: user\` this defaults to the calling user.\
> \- \*\*\`duration\_minutes\`\*\* — the length of each booking, e.g. 15/30/45/60. Required: without it the dashboard cannot generate bookable time slots at all.\
> \- \*\*availability\*\* — which days and hours are offered.\
> \- \*\*capture fields\*\* — any of \`name\`, \`email\`, \`phone\`, \`dob\`, plus custom questions. Email or phone is required; a request with neither is rejected.\
> \
> Optional fields fall back to a server-side default when omitted. Defaults are not inferred from the account's other calendars, so settings that match an existing pattern elsewhere still have to be passed explicitly.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Calendars","description":"Booking calendar meetings (Calendly-style). Each calendar has a public URL slug, weekly availability schedule, capture fields (name/email/phone/dob + custom questions), and post-booking messaging (confirmation, reminders). Booking pages are hosted by the dashboard at `/meeting/{app_id}/{slug}`; the API exposes that URL as `booking_url`. Server-side availability queries and inline booking are deferred to a later phase.\n\nIf the user mentions \"calendar\" at all - \"create a calendar,\" \"calendar invite,\" \"calendar meeting\" - this is the resource they mean: a reusable booking page/link, not a specific scheduled Appointment (see that resource for an actual one-off meeting).\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["calendars:write"]}],"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"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"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"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique key (≤255 chars) chosen by the client. Replays with the same key + same body return the cached response. Replays with the same key + different body return 409 `idempotency_conflict`. Required on messaging sends and bulk operations; recommended elsewhere.\n","schema":{"type":"string","maxLength":255}}},"schemas":{"CalendarCreate":{"type":"object","required":["name","appointment_type_id","duration_minutes","schedule","default_capture"],"properties":{"name":{"type":"string","minLength":1},"slug":{"type":"string"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId"},"meeting_type":{"type":"string","enum":["meeting","user"],"default":"meeting","description":"Whether this is a general workroom-wide calendar (meeting) or a personal per-staff calendar (user). Not related to how bookings are assigned across staff - see notify_type. \"user\" must have exactly one owner: defaults to the calling user for a human caller, otherwise assigned_user_ids is required."},"status":{"type":"string","enum":["active","inactive"],"default":"active"},"assigned_user_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"Each id must be an existing staff member in this account - an id that is well-formed but doesn't exist returns a not-found error rather than being silently accepted."},"duration_minutes":{"type":"integer","minimum":1,"description":"Required. Length of each booking. Without this the dashboard cannot generate bookable time slots for this calendar."},"buffer_minutes":{"type":"integer","minimum":0,"description":"Buffer between back-to-back bookings. Cannot be negative."},"minimum_booking_window":{"type":"integer","minimum":0,"description":"Minimum hours ahead a booking can be made. Cannot be negative."},"appointment_type_id":{"type":"string","description":"Required. The appointment type this calendar books, by id (atyp_...) or by name. An id that is well-formed but doesn't exist in this workroom returns a not-found error - it is never treated as a name. Matching by name is exact and silent: any name that does not match an existing type exactly - including a typo or near-miss - creates a brand new appointment type with no error, which can quietly fill the workroom with unwanted types. List GET /v3/appointment_types first and confirm the exact name (or that a new one is really wanted) with the user instead of guessing."},"notify_type":{"type":"string","enum":["roundrobin","all"],"default":"roundrobin","description":"How bookings are assigned across assigned_user_ids: one at a time (roundrobin) or all of them (all). This is what the Gleantap dashboard UI itself labels \"Meeting Type\" - do not confuse with the meeting_type field above."},"instructions":{"type":"string"},"address":{"type":"string"},"submit_button_text":{"type":"string"},"custom_redirect_url":{"type":"string","description":"Where a booker is sent right after booking. Must be a valid http:// or https:// URL, or blank to clear a previously-set redirect."},"default_capture":{"type":"array","items":{"type":"string","enum":["name","email","phone","dob"]},"description":"Must include \"email\" or \"phone\" - otherwise a booking would arrive with no way to contact the booker."},"custom_questions":{"type":"array","items":{"$ref":"#/components/schemas/CalendarQuestion"}},"schedule":{"$ref":"#/components/schemas/CalendarSchedule"},"confirmation":{"$ref":"#/components/schemas/CalendarConfirmation"},"reminders":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/CalendarReminder"}}}},"WorkroomId":{"type":"string","pattern":"^wrm_[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."},"CalendarQuestion":{"type":"object","required":["label"],"properties":{"label":{"type":"string","minLength":1,"description":"Required and must be non-blank - a blank label shows as an unlabeled field on the booking form."},"type":{"type":"string","enum":["text","textarea","select","radio","checkbox","number"],"default":"text"},"required":{"type":"boolean","default":false},"options":{"type":"array","items":{"type":"string"},"description":"Only used for select/radio/checkbox, and required (at least one non-blank option) for those three - otherwise the question can't be answered."}}},"CalendarSchedule":{"type":"object","description":"Weekly availability. Keys are lowercased weekday names; each maps to an array of `{from_time, to_time}` time-of-day slots in the workroom's timezone (24h \"HH:MM\" strings).\n","properties":{"monday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"tuesday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"wednesday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"thursday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"friday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"saturday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"sunday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}}}},"CalendarScheduleSlot":{"type":"object","required":["from_time","to_time"],"description":"to_time must be strictly after from_time, and slots within the same day cannot overlap.","properties":{"from_time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"24-hour HH:MM, 00:00-23:59."},"to_time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"24-hour HH:MM, 00:00-23:59. Must be after from_time."}}},"CalendarConfirmation":{"type":"object","properties":{"type":{"oneOf":[{"type":"array","items":{"type":"string","enum":["sms","email"]}},{"type":"string","enum":["sms","email"]}],"description":"Which channel(s) send a confirmation. The dashboard allows both sms and email enabled at once (a multi-select), so reads always return an array (e.g. [\"sms\",\"email\"], or [\"sms\"] for one channel only, or [] for none). On write, a single string (e.g. \"sms\") is also accepted as a convenience for setting one channel - it is normalized to an array before storage."},"email_subject":{"type":"string"},"message":{"type":"string","maxLength":1530,"description":"The SMS body, sent when sms is one of the enabled channels. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. Longer bodies are rejected with 400 `sms_too_long`."},"email":{"type":"string","description":"The email body (HTML), sent when email is one of the enabled channels. Unlike CalendarReminder below, confirmations can send both channels at once, so each needs its own separate content field."}}},"CalendarReminder":{"type":"object","description":"No two reminders in the same list can fire the same channel at the same due_hour - that would send the contact the identical reminder twice at once. One reminder entry can cover both channels at once (type: [\"sms\",\"email\"]) with separate content per channel below. Merge tags use single braces (e.g. {first_name}) - a double-brace tag like {{contact.first_name}} is rejected in subject/message/email, since that syntax can never resolve here and would otherwise send as literal text. A <script> tag is also rejected in any of these three fields - the email body is real HTML by design, but could still be a stored-XSS risk if a sent-message preview elsewhere ever renders it back to staff unescaped.","properties":{"type":{"oneOf":[{"type":"array","items":{"type":"string","enum":["sms","email"]}},{"type":"string","enum":["sms","email"]}],"default":"sms","description":"Which channel(s) this reminder fires on. The dashboard's own reminder control is a multi-select (one reminder row can fire both sms and email), so reads always return an array (e.g. [\"sms\"], or [\"sms\",\"email\"] for both). On write, a single string (e.g. \"sms\") is also accepted as a convenience for one channel - it is normalized to an array before storage."},"subject":{"type":"string","description":"Required and must be non-blank when email is one of the enabled channels. Not used for sms."},"due_hour":{"type":"string","description":"Hours before the appointment to send, as a numeric string (e.g. \"24\"). Must be a whole number from 1 to 720 (30 days) - 0 would fire at the appointment start time instead of before it, fractional hours like \"0.5\" are rejected, and anything past 720 would never fire for a realistic booking. Defaults to 24 if omitted."},"message":{"type":"string","maxLength":1530,"description":"The sms body. Required and must be non-blank when sms is one of the enabled channels. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. Longer bodies are rejected with 400 `sms_too_long` - carriers reject them at send time. Cannot contain any HTML tag - sms is never rendered as HTML on the recipient's end, so a tag would send as literal markup text."},"email":{"type":"string","description":"The email body (HTML). Required and must be non-blank when email is one of the enabled channels."}}},"Calendar":{"type":"object","properties":{"object":{"type":"string","const":"calendar"},"id":{"$ref":"#/components/schemas/CalendarId"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId"},"name":{"type":"string","nullable":true},"slug":{"type":"string","nullable":true,"description":"Public URL segment. Unique per workroom."},"meeting_type":{"type":"string","enum":["meeting","user"],"description":"Whether this is a general workroom-wide calendar (meeting) or a personal per-staff calendar (user). Not related to how bookings are assigned across staff - see notify_type."},"status":{"type":"string","enum":["active","inactive"]},"booking_url":{"type":"string","nullable":true,"description":"Public dashboard-hosted booking page. Hand this URL to end users."},"assigned_user_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"Each id must be an existing staff member in this account - an id that is well-formed but doesn't exist returns a not-found error rather than being silently accepted."},"duration_minutes":{"type":"integer","nullable":true},"buffer_minutes":{"type":"integer","nullable":true,"description":"Buffer between back-to-back bookings. Cannot be negative."},"minimum_booking_window":{"type":"integer","nullable":true,"description":"Minimum hours ahead a booking can be made. Cannot be negative."},"appointment_type_id":{"type":"string","nullable":true,"description":"The appointment type this calendar books, by id (atyp_...) or by name. An id that is well-formed but doesn't exist in this workroom returns a not-found error - it is never treated as a name. Matching by name is exact and silent: any name that does not match an existing type exactly - including a typo or near-miss - creates a brand new appointment type with no error, which can quietly fill the workroom with unwanted types. List GET /v3/appointment_types first and confirm the exact name (or that a new one is really wanted) with the user instead of guessing."},"notify_type":{"type":"string","nullable":true,"enum":["roundrobin","all"],"description":"How bookings are assigned across assigned_user_ids: one at a time (roundrobin) or all of them (all). This is what the Gleantap dashboard UI itself labels \"Meeting Type\" - do not confuse with the meeting_type field above."},"instructions":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"submit_button_text":{"type":"string","nullable":true},"custom_redirect_url":{"type":"string","nullable":true,"description":"Where a booker is sent right after booking."},"default_capture":{"type":"array","items":{"type":"string","enum":["name","email","phone","dob"]},"description":"Which built-in contact fields the booking form asks for."},"custom_questions":{"type":"array","items":{"$ref":"#/components/schemas/CalendarQuestion"}},"schedule":{"$ref":"#/components/schemas/CalendarSchedule"},"confirmation":{"$ref":"#/components/schemas/CalendarConfirmation"},"reminders":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/CalendarReminder"}},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"CalendarId":{"type":"string","pattern":"^cal_[0-9a-fA-F]{24}$","description":"Bookable calendar ID."},"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":{"/calendars":{"post":{"tags":["Calendars"],"operationId":"createCalendar","summary":"Create a bookable calendar - this IS what \"calendar meeting,\" \"calendar invite,\" or \"create a calendar\" mean. Not a single scheduled meeting (that's createAppointment).","description":"`meeting_type: meeting` for workroom-wide meetings; `meeting_type: user` for per-staff calendars - this kind must have exactly one owner, defaulted to the calling user when the caller is human, otherwise `assigned_user_ids` must be passed explicitly (an API-key caller has no calling user to default to).\n\nSlugs are auto-generated from `name` if not supplied and are unique per workroom; conflicts get numeric suffixes automatically.\n\nA bookable calendar is defined by six things, and a calendar missing any of them is created successfully but does not work as intended:\n\n- **workroom** — an omitted workroom resolves to the account default. `listWorkrooms` returns the alternatives.\n- **name**\n- **appointment type** — `listAppointmentTypes`, scoped to the target workroom, returns the types that already exist. A new name creates a new type.\n- **`assigned_user_ids`** — who the bookings belong to. For `meeting_type: meeting` the candidates come from `listStaff`; for `meeting_type: user` this defaults to the calling user.\n- **`duration_minutes`** — the length of each booking, e.g. 15/30/45/60. Required: without it the dashboard cannot generate bookable time slots at all.\n- **availability** — which days and hours are offered.\n- **capture fields** — any of `name`, `email`, `phone`, `dob`, plus custom questions. Email or phone is required; a request with neither is rejected.\n\nOptional fields fall back to a server-side default when omitted. Defaults are not inferred from the account's other calendars, so settings that match an existing pattern elsewhere still have to be passed explicitly.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarCreate"}}}},"responses":{"201":{"description":"Calendar created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Calendar"}}}},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## GET /calendars/{id}

> Retrieve a calendar (with full settings).

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Calendars","description":"Booking calendar meetings (Calendly-style). Each calendar has a public URL slug, weekly availability schedule, capture fields (name/email/phone/dob + custom questions), and post-booking messaging (confirmation, reminders). Booking pages are hosted by the dashboard at `/meeting/{app_id}/{slug}`; the API exposes that URL as `booking_url`. Server-side availability queries and inline booking are deferred to a later phase.\n\nIf the user mentions \"calendar\" at all - \"create a calendar,\" \"calendar invite,\" \"calendar meeting\" - this is the resource they mean: a reusable booking page/link, not a specific scheduled Appointment (see that resource for an actual one-off meeting).\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["calendars:read"]}],"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"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"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":{"Calendar":{"type":"object","properties":{"object":{"type":"string","const":"calendar"},"id":{"$ref":"#/components/schemas/CalendarId"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId"},"name":{"type":"string","nullable":true},"slug":{"type":"string","nullable":true,"description":"Public URL segment. Unique per workroom."},"meeting_type":{"type":"string","enum":["meeting","user"],"description":"Whether this is a general workroom-wide calendar (meeting) or a personal per-staff calendar (user). Not related to how bookings are assigned across staff - see notify_type."},"status":{"type":"string","enum":["active","inactive"]},"booking_url":{"type":"string","nullable":true,"description":"Public dashboard-hosted booking page. Hand this URL to end users."},"assigned_user_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"Each id must be an existing staff member in this account - an id that is well-formed but doesn't exist returns a not-found error rather than being silently accepted."},"duration_minutes":{"type":"integer","nullable":true},"buffer_minutes":{"type":"integer","nullable":true,"description":"Buffer between back-to-back bookings. Cannot be negative."},"minimum_booking_window":{"type":"integer","nullable":true,"description":"Minimum hours ahead a booking can be made. Cannot be negative."},"appointment_type_id":{"type":"string","nullable":true,"description":"The appointment type this calendar books, by id (atyp_...) or by name. An id that is well-formed but doesn't exist in this workroom returns a not-found error - it is never treated as a name. Matching by name is exact and silent: any name that does not match an existing type exactly - including a typo or near-miss - creates a brand new appointment type with no error, which can quietly fill the workroom with unwanted types. List GET /v3/appointment_types first and confirm the exact name (or that a new one is really wanted) with the user instead of guessing."},"notify_type":{"type":"string","nullable":true,"enum":["roundrobin","all"],"description":"How bookings are assigned across assigned_user_ids: one at a time (roundrobin) or all of them (all). This is what the Gleantap dashboard UI itself labels \"Meeting Type\" - do not confuse with the meeting_type field above."},"instructions":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"submit_button_text":{"type":"string","nullable":true},"custom_redirect_url":{"type":"string","nullable":true,"description":"Where a booker is sent right after booking."},"default_capture":{"type":"array","items":{"type":"string","enum":["name","email","phone","dob"]},"description":"Which built-in contact fields the booking form asks for."},"custom_questions":{"type":"array","items":{"$ref":"#/components/schemas/CalendarQuestion"}},"schedule":{"$ref":"#/components/schemas/CalendarSchedule"},"confirmation":{"$ref":"#/components/schemas/CalendarConfirmation"},"reminders":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/CalendarReminder"}},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"CalendarId":{"type":"string","pattern":"^cal_[0-9a-fA-F]{24}$","description":"Bookable calendar ID."},"WorkroomId":{"type":"string","pattern":"^wrm_[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."},"CalendarQuestion":{"type":"object","required":["label"],"properties":{"label":{"type":"string","minLength":1,"description":"Required and must be non-blank - a blank label shows as an unlabeled field on the booking form."},"type":{"type":"string","enum":["text","textarea","select","radio","checkbox","number"],"default":"text"},"required":{"type":"boolean","default":false},"options":{"type":"array","items":{"type":"string"},"description":"Only used for select/radio/checkbox, and required (at least one non-blank option) for those three - otherwise the question can't be answered."}}},"CalendarSchedule":{"type":"object","description":"Weekly availability. Keys are lowercased weekday names; each maps to an array of `{from_time, to_time}` time-of-day slots in the workroom's timezone (24h \"HH:MM\" strings).\n","properties":{"monday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"tuesday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"wednesday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"thursday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"friday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"saturday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"sunday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}}}},"CalendarScheduleSlot":{"type":"object","required":["from_time","to_time"],"description":"to_time must be strictly after from_time, and slots within the same day cannot overlap.","properties":{"from_time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"24-hour HH:MM, 00:00-23:59."},"to_time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"24-hour HH:MM, 00:00-23:59. Must be after from_time."}}},"CalendarConfirmation":{"type":"object","properties":{"type":{"oneOf":[{"type":"array","items":{"type":"string","enum":["sms","email"]}},{"type":"string","enum":["sms","email"]}],"description":"Which channel(s) send a confirmation. The dashboard allows both sms and email enabled at once (a multi-select), so reads always return an array (e.g. [\"sms\",\"email\"], or [\"sms\"] for one channel only, or [] for none). On write, a single string (e.g. \"sms\") is also accepted as a convenience for setting one channel - it is normalized to an array before storage."},"email_subject":{"type":"string"},"message":{"type":"string","maxLength":1530,"description":"The SMS body, sent when sms is one of the enabled channels. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. Longer bodies are rejected with 400 `sms_too_long`."},"email":{"type":"string","description":"The email body (HTML), sent when email is one of the enabled channels. Unlike CalendarReminder below, confirmations can send both channels at once, so each needs its own separate content field."}}},"CalendarReminder":{"type":"object","description":"No two reminders in the same list can fire the same channel at the same due_hour - that would send the contact the identical reminder twice at once. One reminder entry can cover both channels at once (type: [\"sms\",\"email\"]) with separate content per channel below. Merge tags use single braces (e.g. {first_name}) - a double-brace tag like {{contact.first_name}} is rejected in subject/message/email, since that syntax can never resolve here and would otherwise send as literal text. A <script> tag is also rejected in any of these three fields - the email body is real HTML by design, but could still be a stored-XSS risk if a sent-message preview elsewhere ever renders it back to staff unescaped.","properties":{"type":{"oneOf":[{"type":"array","items":{"type":"string","enum":["sms","email"]}},{"type":"string","enum":["sms","email"]}],"default":"sms","description":"Which channel(s) this reminder fires on. The dashboard's own reminder control is a multi-select (one reminder row can fire both sms and email), so reads always return an array (e.g. [\"sms\"], or [\"sms\",\"email\"] for both). On write, a single string (e.g. \"sms\") is also accepted as a convenience for one channel - it is normalized to an array before storage."},"subject":{"type":"string","description":"Required and must be non-blank when email is one of the enabled channels. Not used for sms."},"due_hour":{"type":"string","description":"Hours before the appointment to send, as a numeric string (e.g. \"24\"). Must be a whole number from 1 to 720 (30 days) - 0 would fire at the appointment start time instead of before it, fractional hours like \"0.5\" are rejected, and anything past 720 would never fire for a realistic booking. Defaults to 24 if omitted."},"message":{"type":"string","maxLength":1530,"description":"The sms body. Required and must be non-blank when sms is one of the enabled channels. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. Longer bodies are rejected with 400 `sms_too_long` - carriers reject them at send time. Cannot contain any HTML tag - sms is never rendered as HTML on the recipient's end, so a tag would send as literal markup text."},"email":{"type":"string","description":"The email body (HTML). Required and must be non-blank when email is one of the enabled channels."}}},"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":{"/calendars/{id}":{"get":{"tags":["Calendars"],"operationId":"retrieveCalendar","summary":"Retrieve a calendar (with full settings).","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"Calendar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Calendar"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Update a calendar.

> Change a booking calendar — its name, URL slug, weekly availability, the details it captures from bookers, or its confirmation and reminder messaging. Only the fields supplied are changed. Changing the slug changes the public booking URL, so links already shared stop resolving.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Calendars","description":"Booking calendar meetings (Calendly-style). Each calendar has a public URL slug, weekly availability schedule, capture fields (name/email/phone/dob + custom questions), and post-booking messaging (confirmation, reminders). Booking pages are hosted by the dashboard at `/meeting/{app_id}/{slug}`; the API exposes that URL as `booking_url`. Server-side availability queries and inline booking are deferred to a later phase.\n\nIf the user mentions \"calendar\" at all - \"create a calendar,\" \"calendar invite,\" \"calendar meeting\" - this is the resource they mean: a reusable booking page/link, not a specific scheduled Appointment (see that resource for an actual one-off meeting).\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["calendars:write"]}],"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"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"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":{"CalendarUpdate":{"type":"object","description":"Partial update - every field is optional, only send what's changing. Deliberately a separate schema from `CalendarCreate` rather than reusing it: that one requires `name`, `appointment_type_id`, `duration_minutes`, `schedule` and `default_capture`, which would make a true partial update (e.g. just `confirmation`) look invalid even though the backend does not actually require any of them here.\n","properties":{"name":{"type":"string","minLength":1},"slug":{"type":"string"},"meeting_type":{"type":"string","enum":["meeting","user"],"description":"Whether this is a general workroom-wide calendar (meeting) or a personal per-staff calendar (user). Not related to how bookings are assigned across staff - see notify_type. \"user\" must have exactly one owner - either already set, defaulted to the calling user for a human caller, or passed explicitly via assigned_user_ids."},"status":{"type":"string","enum":["active","inactive"]},"assigned_user_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"Each id must be an existing staff member in this account - an id that is well-formed but doesn't exist returns a not-found error rather than being silently accepted."},"duration_minutes":{"type":"integer","minimum":1,"description":"Length of each booking."},"buffer_minutes":{"type":"integer","minimum":0,"description":"Buffer between back-to-back bookings. Cannot be negative."},"minimum_booking_window":{"type":"integer","minimum":0,"description":"Minimum hours ahead a booking can be made. Cannot be negative."},"appointment_type_id":{"type":"string","description":"The appointment type this calendar books, by id (atyp_...) or by name. An id that is well-formed but doesn't exist in this workroom returns a not-found error - it is never treated as a name. Matching by name is exact and silent: any name that does not match an existing type exactly - including a typo or near-miss - creates a brand new appointment type with no error, which can quietly fill the workroom with unwanted types. List GET /v3/appointment_types first and confirm the exact name (or that a new one is really wanted) with the user instead of guessing."},"notify_type":{"type":"string","enum":["roundrobin","all"],"description":"How bookings are assigned across assigned_user_ids: one at a time (roundrobin) or all of them (all). This is what the Gleantap dashboard UI itself labels \"Meeting Type\" - do not confuse with the meeting_type field above."},"instructions":{"type":"string"},"address":{"type":"string"},"submit_button_text":{"type":"string"},"custom_redirect_url":{"type":"string","description":"Where a booker is sent right after booking. Must be a valid http:// or https:// URL, or blank to clear a previously-set redirect."},"default_capture":{"type":"array","items":{"type":"string","enum":["name","email","phone","dob"]},"description":"Must include \"email\" or \"phone\" - otherwise a booking would arrive with no way to contact the booker."},"custom_questions":{"type":"array","items":{"$ref":"#/components/schemas/CalendarQuestion"}},"schedule":{"$ref":"#/components/schemas/CalendarSchedule","description":"Merged per day into the existing stored schedule, not replaced wholesale - a day left out of this object keeps its current slots untouched (so updating just one day's hours can't accidentally wipe the rest of the week). To remove a day entirely, include it explicitly with an empty array (e.g. \"tuesday\": []) rather than omitting it."},"confirmation":{"$ref":"#/components/schemas/CalendarConfirmation"},"reminders":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/CalendarReminder"}}}},"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."},"CalendarQuestion":{"type":"object","required":["label"],"properties":{"label":{"type":"string","minLength":1,"description":"Required and must be non-blank - a blank label shows as an unlabeled field on the booking form."},"type":{"type":"string","enum":["text","textarea","select","radio","checkbox","number"],"default":"text"},"required":{"type":"boolean","default":false},"options":{"type":"array","items":{"type":"string"},"description":"Only used for select/radio/checkbox, and required (at least one non-blank option) for those three - otherwise the question can't be answered."}}},"CalendarSchedule":{"type":"object","description":"Weekly availability. Keys are lowercased weekday names; each maps to an array of `{from_time, to_time}` time-of-day slots in the workroom's timezone (24h \"HH:MM\" strings).\n","properties":{"monday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"tuesday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"wednesday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"thursday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"friday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"saturday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"sunday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}}}},"CalendarScheduleSlot":{"type":"object","required":["from_time","to_time"],"description":"to_time must be strictly after from_time, and slots within the same day cannot overlap.","properties":{"from_time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"24-hour HH:MM, 00:00-23:59."},"to_time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"24-hour HH:MM, 00:00-23:59. Must be after from_time."}}},"CalendarConfirmation":{"type":"object","properties":{"type":{"oneOf":[{"type":"array","items":{"type":"string","enum":["sms","email"]}},{"type":"string","enum":["sms","email"]}],"description":"Which channel(s) send a confirmation. The dashboard allows both sms and email enabled at once (a multi-select), so reads always return an array (e.g. [\"sms\",\"email\"], or [\"sms\"] for one channel only, or [] for none). On write, a single string (e.g. \"sms\") is also accepted as a convenience for setting one channel - it is normalized to an array before storage."},"email_subject":{"type":"string"},"message":{"type":"string","maxLength":1530,"description":"The SMS body, sent when sms is one of the enabled channels. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. Longer bodies are rejected with 400 `sms_too_long`."},"email":{"type":"string","description":"The email body (HTML), sent when email is one of the enabled channels. Unlike CalendarReminder below, confirmations can send both channels at once, so each needs its own separate content field."}}},"CalendarReminder":{"type":"object","description":"No two reminders in the same list can fire the same channel at the same due_hour - that would send the contact the identical reminder twice at once. One reminder entry can cover both channels at once (type: [\"sms\",\"email\"]) with separate content per channel below. Merge tags use single braces (e.g. {first_name}) - a double-brace tag like {{contact.first_name}} is rejected in subject/message/email, since that syntax can never resolve here and would otherwise send as literal text. A <script> tag is also rejected in any of these three fields - the email body is real HTML by design, but could still be a stored-XSS risk if a sent-message preview elsewhere ever renders it back to staff unescaped.","properties":{"type":{"oneOf":[{"type":"array","items":{"type":"string","enum":["sms","email"]}},{"type":"string","enum":["sms","email"]}],"default":"sms","description":"Which channel(s) this reminder fires on. The dashboard's own reminder control is a multi-select (one reminder row can fire both sms and email), so reads always return an array (e.g. [\"sms\"], or [\"sms\",\"email\"] for both). On write, a single string (e.g. \"sms\") is also accepted as a convenience for one channel - it is normalized to an array before storage."},"subject":{"type":"string","description":"Required and must be non-blank when email is one of the enabled channels. Not used for sms."},"due_hour":{"type":"string","description":"Hours before the appointment to send, as a numeric string (e.g. \"24\"). Must be a whole number from 1 to 720 (30 days) - 0 would fire at the appointment start time instead of before it, fractional hours like \"0.5\" are rejected, and anything past 720 would never fire for a realistic booking. Defaults to 24 if omitted."},"message":{"type":"string","maxLength":1530,"description":"The sms body. Required and must be non-blank when sms is one of the enabled channels. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. Longer bodies are rejected with 400 `sms_too_long` - carriers reject them at send time. Cannot contain any HTML tag - sms is never rendered as HTML on the recipient's end, so a tag would send as literal markup text."},"email":{"type":"string","description":"The email body (HTML). Required and must be non-blank when email is one of the enabled channels."}}},"Calendar":{"type":"object","properties":{"object":{"type":"string","const":"calendar"},"id":{"$ref":"#/components/schemas/CalendarId"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId"},"name":{"type":"string","nullable":true},"slug":{"type":"string","nullable":true,"description":"Public URL segment. Unique per workroom."},"meeting_type":{"type":"string","enum":["meeting","user"],"description":"Whether this is a general workroom-wide calendar (meeting) or a personal per-staff calendar (user). Not related to how bookings are assigned across staff - see notify_type."},"status":{"type":"string","enum":["active","inactive"]},"booking_url":{"type":"string","nullable":true,"description":"Public dashboard-hosted booking page. Hand this URL to end users."},"assigned_user_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"Each id must be an existing staff member in this account - an id that is well-formed but doesn't exist returns a not-found error rather than being silently accepted."},"duration_minutes":{"type":"integer","nullable":true},"buffer_minutes":{"type":"integer","nullable":true,"description":"Buffer between back-to-back bookings. Cannot be negative."},"minimum_booking_window":{"type":"integer","nullable":true,"description":"Minimum hours ahead a booking can be made. Cannot be negative."},"appointment_type_id":{"type":"string","nullable":true,"description":"The appointment type this calendar books, by id (atyp_...) or by name. An id that is well-formed but doesn't exist in this workroom returns a not-found error - it is never treated as a name. Matching by name is exact and silent: any name that does not match an existing type exactly - including a typo or near-miss - creates a brand new appointment type with no error, which can quietly fill the workroom with unwanted types. List GET /v3/appointment_types first and confirm the exact name (or that a new one is really wanted) with the user instead of guessing."},"notify_type":{"type":"string","nullable":true,"enum":["roundrobin","all"],"description":"How bookings are assigned across assigned_user_ids: one at a time (roundrobin) or all of them (all). This is what the Gleantap dashboard UI itself labels \"Meeting Type\" - do not confuse with the meeting_type field above."},"instructions":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"submit_button_text":{"type":"string","nullable":true},"custom_redirect_url":{"type":"string","nullable":true,"description":"Where a booker is sent right after booking."},"default_capture":{"type":"array","items":{"type":"string","enum":["name","email","phone","dob"]},"description":"Which built-in contact fields the booking form asks for."},"custom_questions":{"type":"array","items":{"$ref":"#/components/schemas/CalendarQuestion"}},"schedule":{"$ref":"#/components/schemas/CalendarSchedule"},"confirmation":{"$ref":"#/components/schemas/CalendarConfirmation"},"reminders":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/CalendarReminder"}},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"CalendarId":{"type":"string","pattern":"^cal_[0-9a-fA-F]{24}$","description":"Bookable calendar ID."},"WorkroomId":{"type":"string","pattern":"^wrm_[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"}}}},"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":{"/calendars/{id}":{"patch":{"tags":["Calendars"],"operationId":"updateCalendar","summary":"Update a calendar.","description":"Change a booking calendar — its name, URL slug, weekly availability, the details it captures from bookers, or its confirmation and reminder messaging. Only the fields supplied are changed. Changing the slug changes the public booking URL, so links already shared stop resolving.\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/CalendarUpdate"}}}},"responses":{"200":{"description":"Updated calendar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Calendar"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## Permanently delete a calendar.

> Hard-deletes the calendar document, matching the dashboard's own delete exactly. Booking page returns 404.\
> \
> \*\*Permanent.\*\* There is no undo and no trash to restore from. Confirm with the user before calling this - 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":"Calendars","description":"Booking calendar meetings (Calendly-style). Each calendar has a public URL slug, weekly availability schedule, capture fields (name/email/phone/dob + custom questions), and post-booking messaging (confirmation, reminders). Booking pages are hosted by the dashboard at `/meeting/{app_id}/{slug}`; the API exposes that URL as `booking_url`. Server-side availability queries and inline booking are deferred to a later phase.\n\nIf the user mentions \"calendar\" at all - \"create a calendar,\" \"calendar invite,\" \"calendar meeting\" - this is the resource they mean: a reusable booking page/link, not a specific scheduled Appointment (see that resource for an actual one-off meeting).\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["calendars:write"]}],"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"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"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"}}},"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":{"/calendars/{id}":{"delete":{"tags":["Calendars"],"operationId":"deleteCalendar","summary":"Permanently delete a calendar.","description":"Hard-deletes the calendar document, matching the dashboard's own delete exactly. Booking page returns 404.\n\n**Permanent.** There is no undo and no trash to restore from. Confirm with the user before calling this - anything that references the deleted record is affected too.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"204":{"description":"Deleted."},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Duplicate a calendar (starts inactive).

> Clones all settings — schedule, capture fields, confirmation, reminders — with a new slug. The clone starts \`status=inactive\` so callers can review and activate.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Calendars","description":"Booking calendar meetings (Calendly-style). Each calendar has a public URL slug, weekly availability schedule, capture fields (name/email/phone/dob + custom questions), and post-booking messaging (confirmation, reminders). Booking pages are hosted by the dashboard at `/meeting/{app_id}/{slug}`; the API exposes that URL as `booking_url`. Server-side availability queries and inline booking are deferred to a later phase.\n\nIf the user mentions \"calendar\" at all - \"create a calendar,\" \"calendar invite,\" \"calendar meeting\" - this is the resource they mean: a reusable booking page/link, not a specific scheduled Appointment (see that resource for an actual one-off meeting).\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["calendars:write"]}],"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"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"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":{"Calendar":{"type":"object","properties":{"object":{"type":"string","const":"calendar"},"id":{"$ref":"#/components/schemas/CalendarId"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId"},"name":{"type":"string","nullable":true},"slug":{"type":"string","nullable":true,"description":"Public URL segment. Unique per workroom."},"meeting_type":{"type":"string","enum":["meeting","user"],"description":"Whether this is a general workroom-wide calendar (meeting) or a personal per-staff calendar (user). Not related to how bookings are assigned across staff - see notify_type."},"status":{"type":"string","enum":["active","inactive"]},"booking_url":{"type":"string","nullable":true,"description":"Public dashboard-hosted booking page. Hand this URL to end users."},"assigned_user_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"Each id must be an existing staff member in this account - an id that is well-formed but doesn't exist returns a not-found error rather than being silently accepted."},"duration_minutes":{"type":"integer","nullable":true},"buffer_minutes":{"type":"integer","nullable":true,"description":"Buffer between back-to-back bookings. Cannot be negative."},"minimum_booking_window":{"type":"integer","nullable":true,"description":"Minimum hours ahead a booking can be made. Cannot be negative."},"appointment_type_id":{"type":"string","nullable":true,"description":"The appointment type this calendar books, by id (atyp_...) or by name. An id that is well-formed but doesn't exist in this workroom returns a not-found error - it is never treated as a name. Matching by name is exact and silent: any name that does not match an existing type exactly - including a typo or near-miss - creates a brand new appointment type with no error, which can quietly fill the workroom with unwanted types. List GET /v3/appointment_types first and confirm the exact name (or that a new one is really wanted) with the user instead of guessing."},"notify_type":{"type":"string","nullable":true,"enum":["roundrobin","all"],"description":"How bookings are assigned across assigned_user_ids: one at a time (roundrobin) or all of them (all). This is what the Gleantap dashboard UI itself labels \"Meeting Type\" - do not confuse with the meeting_type field above."},"instructions":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"submit_button_text":{"type":"string","nullable":true},"custom_redirect_url":{"type":"string","nullable":true,"description":"Where a booker is sent right after booking."},"default_capture":{"type":"array","items":{"type":"string","enum":["name","email","phone","dob"]},"description":"Which built-in contact fields the booking form asks for."},"custom_questions":{"type":"array","items":{"$ref":"#/components/schemas/CalendarQuestion"}},"schedule":{"$ref":"#/components/schemas/CalendarSchedule"},"confirmation":{"$ref":"#/components/schemas/CalendarConfirmation"},"reminders":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/CalendarReminder"}},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"CalendarId":{"type":"string","pattern":"^cal_[0-9a-fA-F]{24}$","description":"Bookable calendar ID."},"WorkroomId":{"type":"string","pattern":"^wrm_[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."},"CalendarQuestion":{"type":"object","required":["label"],"properties":{"label":{"type":"string","minLength":1,"description":"Required and must be non-blank - a blank label shows as an unlabeled field on the booking form."},"type":{"type":"string","enum":["text","textarea","select","radio","checkbox","number"],"default":"text"},"required":{"type":"boolean","default":false},"options":{"type":"array","items":{"type":"string"},"description":"Only used for select/radio/checkbox, and required (at least one non-blank option) for those three - otherwise the question can't be answered."}}},"CalendarSchedule":{"type":"object","description":"Weekly availability. Keys are lowercased weekday names; each maps to an array of `{from_time, to_time}` time-of-day slots in the workroom's timezone (24h \"HH:MM\" strings).\n","properties":{"monday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"tuesday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"wednesday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"thursday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"friday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"saturday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}},"sunday":{"type":"array","items":{"$ref":"#/components/schemas/CalendarScheduleSlot"}}}},"CalendarScheduleSlot":{"type":"object","required":["from_time","to_time"],"description":"to_time must be strictly after from_time, and slots within the same day cannot overlap.","properties":{"from_time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"24-hour HH:MM, 00:00-23:59."},"to_time":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$","description":"24-hour HH:MM, 00:00-23:59. Must be after from_time."}}},"CalendarConfirmation":{"type":"object","properties":{"type":{"oneOf":[{"type":"array","items":{"type":"string","enum":["sms","email"]}},{"type":"string","enum":["sms","email"]}],"description":"Which channel(s) send a confirmation. The dashboard allows both sms and email enabled at once (a multi-select), so reads always return an array (e.g. [\"sms\",\"email\"], or [\"sms\"] for one channel only, or [] for none). On write, a single string (e.g. \"sms\") is also accepted as a convenience for setting one channel - it is normalized to an array before storage."},"email_subject":{"type":"string"},"message":{"type":"string","maxLength":1530,"description":"The SMS body, sent when sms is one of the enabled channels. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. Longer bodies are rejected with 400 `sms_too_long`."},"email":{"type":"string","description":"The email body (HTML), sent when email is one of the enabled channels. Unlike CalendarReminder below, confirmations can send both channels at once, so each needs its own separate content field."}}},"CalendarReminder":{"type":"object","description":"No two reminders in the same list can fire the same channel at the same due_hour - that would send the contact the identical reminder twice at once. One reminder entry can cover both channels at once (type: [\"sms\",\"email\"]) with separate content per channel below. Merge tags use single braces (e.g. {first_name}) - a double-brace tag like {{contact.first_name}} is rejected in subject/message/email, since that syntax can never resolve here and would otherwise send as literal text. A <script> tag is also rejected in any of these three fields - the email body is real HTML by design, but could still be a stored-XSS risk if a sent-message preview elsewhere ever renders it back to staff unescaped.","properties":{"type":{"oneOf":[{"type":"array","items":{"type":"string","enum":["sms","email"]}},{"type":"string","enum":["sms","email"]}],"default":"sms","description":"Which channel(s) this reminder fires on. The dashboard's own reminder control is a multi-select (one reminder row can fire both sms and email), so reads always return an array (e.g. [\"sms\"], or [\"sms\",\"email\"] for both). On write, a single string (e.g. \"sms\") is also accepted as a convenience for one channel - it is normalized to an array before storage."},"subject":{"type":"string","description":"Required and must be non-blank when email is one of the enabled channels. Not used for sms."},"due_hour":{"type":"string","description":"Hours before the appointment to send, as a numeric string (e.g. \"24\"). Must be a whole number from 1 to 720 (30 days) - 0 would fire at the appointment start time instead of before it, fractional hours like \"0.5\" are rejected, and anything past 720 would never fire for a realistic booking. Defaults to 24 if omitted."},"message":{"type":"string","maxLength":1530,"description":"The sms body. Required and must be non-blank when sms is one of the enabled channels. At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. Longer bodies are rejected with 400 `sms_too_long` - carriers reject them at send time. Cannot contain any HTML tag - sms is never rendered as HTML on the recipient's end, so a tag would send as literal markup text."},"email":{"type":"string","description":"The email body (HTML). Required and must be non-blank when email is one of the enabled channels."}}},"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":{"/calendars/{id}/duplicate":{"post":{"tags":["Calendars"],"operationId":"duplicateCalendar","summary":"Duplicate a calendar (starts inactive).","description":"Clones all settings — schedule, capture fields, confirmation, reminders — with a new slug. The clone starts `status=inactive` so callers can review and activate.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"201":{"description":"Duplicated calendar (inactive).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Calendar"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
