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

# Events

Append-only activity events attached to contacts. Powers segments, flows, and analytics.

## List events across all contacts.

> Paginated event firehose, most recent first by \`occurred\_at\`. Common filters: \`?filter\[name]=purchase.completed\`, \`?filter\[contact\_id]=\`, \`?filter\[location\_id]=\`, \`?filter\[occurred\_at]\[gte]=...\`, \`?filter\[occurred\_at]\[lt]=...\`. For a single contact use \`GET /v3/contacts/{id}/events\`. For aggregates use \`POST /v3/reports/{id}/run\` or build a segment. Rate limit bucket: \`read\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Events","description":"Append-only activity events attached to contacts. Powers segments, flows, and analytics."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["events: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"}},"SortParam":{"name":"sort","in":"query","required":false,"description":"Comma-separated list of fields to sort by. Leading `-` reverses. Default `-created_at`. Sortable fields vary per resource; unsortable fields return 400 `invalid_sort_field`.\n","schema":{"type":"string"}}},"schemas":{"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`."}}},"Event":{"type":"object","description":"A single activity event attached to a contact. Events are **append-only** — there is no update or delete endpoint.\nEvent names use dot notation (`namespace.action`), e.g. `purchase.completed`, `class.checked_in`, `form.submitted`, `email.opened`.\n","required":["id","object","name","contact_id","occurred_at","created_at"],"properties":{"id":{"$ref":"#/components/schemas/EventId"},"object":{"type":"string","const":"event"},"name":{"type":"string","description":"Event name in `namespace.action` form. Lowercase snake_case. No spaces or special chars.\nCommon namespaces: `purchase`, `class`, `email`, `sms`, `form`, `page`, `appointment`, `membership`.\n","pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"},"contact_id":{"$ref":"#/components/schemas/ContactId"},"location_id":{"$ref":"#/components/schemas/LocationId","nullable":true,"description":"Location the event happened at. Integration-synced events store it as `club` (ABC), `data.club` (ClubReady) or `data.location_id` (ClubAutomation, uploads); this field reads whichever is set, and `filter[location_id]` matches any of them."},"properties":{"type":"object","additionalProperties":true,"description":"Free-form event payload. Keys are your choice. Reserved keys (`_amount`, `_currency`) are used by segment aggregates — see the Segment Query DSL for details.\n"},"occurred_at":{"$ref":"#/components/schemas/Timestamp","description":"When the event actually occurred (may be backdated)."},"created_at":{"$ref":"#/components/schemas/Timestamp","description":"When the event was recorded in Gleantap (always server-set)."},"type":{"type":"string","nullable":true,"description":"**Legacy discriminator field.** Every externalevents row has this. Common values: `appointment`, `badge`, `sale`, `checkin`, `visit`, `reservation`, `order`, `purchase`, `class`, `rating`, `form`, `challenge`, `club`, `membership`, `email`, `sms`. v3-emitted events derive `type` from the dot-notation name (e.g. `purchase.completed → sale`). Use `filter[type]=appointment` to fetch all appointment events regardless of whether they were emitted through v3 or the legacy dashboard.\n"},"is_visit":{"type":"boolean","description":"True for visit/checkin/arrival events (any legacy source)."},"is_purchase":{"type":"boolean","description":"True for sale/purchase/order events."},"is_appointment":{"type":"boolean","description":"True for appointment events."},"is_badge":{"type":"boolean","description":"True for loyalty-badge events."},"is_rating":{"type":"boolean","description":"True for rating/review events."},"is_reservation":{"type":"boolean","description":"True for class reservation events."},"is_challenge":{"type":"boolean","description":"True for loyalty challenge events."}},"additionalProperties":{"type":"boolean","description":"Any additional `is_*` boolean flags observed on the doc — v3 passes them through as-is so new legacy flags become queryable automatically."}},"EventId":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$"},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"LocationId":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/events":{"get":{"tags":["Events"],"operationId":"listEvents","summary":"List events across all contacts.","description":"Paginated event firehose, most recent first by `occurred_at`. Common filters: `?filter[name]=purchase.completed`, `?filter[contact_id]=`, `?filter[location_id]=`, `?filter[occurred_at][gte]=...`, `?filter[occurred_at][lt]=...`. For a single contact use `GET /v3/contacts/{id}/events`. For aggregates use `POST /v3/reports/{id}/run` or build a segment. Rate limit bucket: `read`.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"},{"$ref":"#/components/parameters/SortParam"},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":{"type":"string"}}}],"responses":{"200":{"description":"A page of events.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}]}}}}}}}}}
```

## Record an event.

> Append-only — no update or delete. Use \`namespace.action\` snake\_case naming. The server derives \`type\`, \`is\_visit\`, \`is\_purchase\`, and the display \`name\` from the namespace + your properties. Common patterns:\
> \
> \*\*Purchases (\`purchase.\*\`)\*\* — \`is\_purchase: 1\`, \`type: sale\`. Pass an \`items\[]\` array of product-name strings you purchased. If \`items\` is omitted the server synthesizes from \`properties.product\_name\` (or \`products\[]\`, \`product\_names\[]\`, \`sku\`). With none of those present it falls back to the event\_name string, which shows up as "purchase.completed" in the UI. Include \`amount\` (total order value) and \`currency\`. The dashboard's event card displays \`items\[0]\` as the headline.\
> \
> \*\*Visits (\`visit.\*\` or legacy \`class.checked\_in\`)\*\* — \`is\_visit: 1\`, \`type: visit\`. Pass \`properties.class\_name\` (or \`service\_name\`, \`visit\_name\`) — that becomes the event's \`name\` displayed in the UI. Add \`location\` / \`location\_id\` when known. Also updates the contact's \`visits.last\_visit\_\*\` / \`visits.first\_visit\_\*\` summary (pass \`properties.status\`; \`Cancelled\` visits are ignored for first-visit). Re-posting the same \`external\_id\` replaces the earlier event instead of adding a second one.\
> \
> \*\*Appointments (\`appointment.completed\`)\*\* — \`is\_visit: 1\`, \`type: appointment\`. Pass \`properties.appointment\_name\` or \`service\_name\`.\
> \
> State changes on first-class resources (opportunity moved, membership canceled, appointment rescheduled) are emitted automatically by the platform; recording them here as well produces duplicates that skew segments. \`Idempotency-Key\` is strongly recommended. Rate limit bucket: \`write\`.\
> \
> Requires the event name and which contact it belongs to. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Events","description":"Append-only activity events attached to contacts. Powers segments, flows, and analytics."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["events: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":{"EventCreate":{"type":"object","required":["name","contact_id","occurred_at"],"description":"Record a new event. Idempotency via `Idempotency-Key` is strongly recommended if the caller may retry —\nwithout it, network retries create duplicate events that skew counts in segments and reports.\n","properties":{"name":{"type":"string","pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"},"contact_id":{"$ref":"#/components/schemas/ContactId"},"location_id":{"$ref":"#/components/schemas/LocationId"},"properties":{"type":"object","additionalProperties":true},"occurred_at":{"$ref":"#/components/schemas/Timestamp","description":"When the event occurred. A timestamp without a UTC offset (e.g. `2026-05-01 18:00`) is read in the account's timezone; include `Z` or an offset to be explicit."}}},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"LocationId":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Event":{"type":"object","description":"A single activity event attached to a contact. Events are **append-only** — there is no update or delete endpoint.\nEvent names use dot notation (`namespace.action`), e.g. `purchase.completed`, `class.checked_in`, `form.submitted`, `email.opened`.\n","required":["id","object","name","contact_id","occurred_at","created_at"],"properties":{"id":{"$ref":"#/components/schemas/EventId"},"object":{"type":"string","const":"event"},"name":{"type":"string","description":"Event name in `namespace.action` form. Lowercase snake_case. No spaces or special chars.\nCommon namespaces: `purchase`, `class`, `email`, `sms`, `form`, `page`, `appointment`, `membership`.\n","pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"},"contact_id":{"$ref":"#/components/schemas/ContactId"},"location_id":{"$ref":"#/components/schemas/LocationId","nullable":true,"description":"Location the event happened at. Integration-synced events store it as `club` (ABC), `data.club` (ClubReady) or `data.location_id` (ClubAutomation, uploads); this field reads whichever is set, and `filter[location_id]` matches any of them."},"properties":{"type":"object","additionalProperties":true,"description":"Free-form event payload. Keys are your choice. Reserved keys (`_amount`, `_currency`) are used by segment aggregates — see the Segment Query DSL for details.\n"},"occurred_at":{"$ref":"#/components/schemas/Timestamp","description":"When the event actually occurred (may be backdated)."},"created_at":{"$ref":"#/components/schemas/Timestamp","description":"When the event was recorded in Gleantap (always server-set)."},"type":{"type":"string","nullable":true,"description":"**Legacy discriminator field.** Every externalevents row has this. Common values: `appointment`, `badge`, `sale`, `checkin`, `visit`, `reservation`, `order`, `purchase`, `class`, `rating`, `form`, `challenge`, `club`, `membership`, `email`, `sms`. v3-emitted events derive `type` from the dot-notation name (e.g. `purchase.completed → sale`). Use `filter[type]=appointment` to fetch all appointment events regardless of whether they were emitted through v3 or the legacy dashboard.\n"},"is_visit":{"type":"boolean","description":"True for visit/checkin/arrival events (any legacy source)."},"is_purchase":{"type":"boolean","description":"True for sale/purchase/order events."},"is_appointment":{"type":"boolean","description":"True for appointment events."},"is_badge":{"type":"boolean","description":"True for loyalty-badge events."},"is_rating":{"type":"boolean","description":"True for rating/review events."},"is_reservation":{"type":"boolean","description":"True for class reservation events."},"is_challenge":{"type":"boolean","description":"True for loyalty challenge events."}},"additionalProperties":{"type":"boolean","description":"Any additional `is_*` boolean flags observed on the doc — v3 passes them through as-is so new legacy flags become queryable automatically."}},"EventId":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/events":{"post":{"tags":["Events"],"operationId":"createEvent","summary":"Record an event.","description":"Append-only — no update or delete. Use `namespace.action` snake_case naming. The server derives `type`, `is_visit`, `is_purchase`, and the display `name` from the namespace + your properties. Common patterns:\n\n**Purchases (`purchase.*`)** — `is_purchase: 1`, `type: sale`. Pass an `items[]` array of product-name strings you purchased. If `items` is omitted the server synthesizes from `properties.product_name` (or `products[]`, `product_names[]`, `sku`). With none of those present it falls back to the event_name string, which shows up as \"purchase.completed\" in the UI. Include `amount` (total order value) and `currency`. The dashboard's event card displays `items[0]` as the headline.\n\n**Visits (`visit.*` or legacy `class.checked_in`)** — `is_visit: 1`, `type: visit`. Pass `properties.class_name` (or `service_name`, `visit_name`) — that becomes the event's `name` displayed in the UI. Add `location` / `location_id` when known. Also updates the contact's `visits.last_visit_*` / `visits.first_visit_*` summary (pass `properties.status`; `Cancelled` visits are ignored for first-visit). Re-posting the same `external_id` replaces the earlier event instead of adding a second one.\n\n**Appointments (`appointment.completed`)** — `is_visit: 1`, `type: appointment`. Pass `properties.appointment_name` or `service_name`.\n\nState changes on first-class resources (opportunity moved, membership canceled, appointment rescheduled) are emitted automatically by the platform; recording them here as well produces duplicates that skew segments. `Idempotency-Key` is strongly recommended. Rate limit bucket: `write`.\n\nRequires the event name and which contact it belongs to. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventCreate"}}}},"responses":{"201":{"description":"Event recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"The referenced contact doesn't exist.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}}}
```

## Retrieve an event.

> Fetch a single event by ID.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Events","description":"Append-only activity events attached to contacts. Powers segments, flows, and analytics."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["events: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":{"Event":{"type":"object","description":"A single activity event attached to a contact. Events are **append-only** — there is no update or delete endpoint.\nEvent names use dot notation (`namespace.action`), e.g. `purchase.completed`, `class.checked_in`, `form.submitted`, `email.opened`.\n","required":["id","object","name","contact_id","occurred_at","created_at"],"properties":{"id":{"$ref":"#/components/schemas/EventId"},"object":{"type":"string","const":"event"},"name":{"type":"string","description":"Event name in `namespace.action` form. Lowercase snake_case. No spaces or special chars.\nCommon namespaces: `purchase`, `class`, `email`, `sms`, `form`, `page`, `appointment`, `membership`.\n","pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"},"contact_id":{"$ref":"#/components/schemas/ContactId"},"location_id":{"$ref":"#/components/schemas/LocationId","nullable":true,"description":"Location the event happened at. Integration-synced events store it as `club` (ABC), `data.club` (ClubReady) or `data.location_id` (ClubAutomation, uploads); this field reads whichever is set, and `filter[location_id]` matches any of them."},"properties":{"type":"object","additionalProperties":true,"description":"Free-form event payload. Keys are your choice. Reserved keys (`_amount`, `_currency`) are used by segment aggregates — see the Segment Query DSL for details.\n"},"occurred_at":{"$ref":"#/components/schemas/Timestamp","description":"When the event actually occurred (may be backdated)."},"created_at":{"$ref":"#/components/schemas/Timestamp","description":"When the event was recorded in Gleantap (always server-set)."},"type":{"type":"string","nullable":true,"description":"**Legacy discriminator field.** Every externalevents row has this. Common values: `appointment`, `badge`, `sale`, `checkin`, `visit`, `reservation`, `order`, `purchase`, `class`, `rating`, `form`, `challenge`, `club`, `membership`, `email`, `sms`. v3-emitted events derive `type` from the dot-notation name (e.g. `purchase.completed → sale`). Use `filter[type]=appointment` to fetch all appointment events regardless of whether they were emitted through v3 or the legacy dashboard.\n"},"is_visit":{"type":"boolean","description":"True for visit/checkin/arrival events (any legacy source)."},"is_purchase":{"type":"boolean","description":"True for sale/purchase/order events."},"is_appointment":{"type":"boolean","description":"True for appointment events."},"is_badge":{"type":"boolean","description":"True for loyalty-badge events."},"is_rating":{"type":"boolean","description":"True for rating/review events."},"is_reservation":{"type":"boolean","description":"True for class reservation events."},"is_challenge":{"type":"boolean","description":"True for loyalty challenge events."}},"additionalProperties":{"type":"boolean","description":"Any additional `is_*` boolean flags observed on the doc — v3 passes them through as-is so new legacy flags become queryable automatically."}},"EventId":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$"},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"LocationId":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/events/{id}":{"get":{"tags":["Events"],"operationId":"retrieveEvent","summary":"Retrieve an event.","description":"Fetch a single event by ID.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"The event.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Enumerate available event names, types, and flags for this workroom.

> Catalog for authoring a flow trigger or a segment condition that keys on an event. Returns the union of every event vocabulary currently active on the workroom's \`externalevents\` collection:\
> \
> &#x20; \- \*\*\`types\`\*\* — distinct legacy \`type\` values observed with counts, last-seen timestamps, sample \`data.\*\` property keys, and the \`is\_\*\` flag(s) each type carries. Legacy dashboard-emitted events use \`type\` as the primary discriminator (\`type: "appointment"\`, \`type: "badge"\`, \`type: "sale"\`, etc.) with no dot-notation event\_name. This is the dimension you'll most often use for flow triggers.\
> &#x20; \- \*\*\`event\_names\`\*\* — distinct v3-native dot-notation \`event\_name\` values (\`purchase.completed\`, \`visit.checked\_in\`, \`form.submitted\`) with the same metadata. Only populated on events created through v3 API paths.\
> &#x20; \- \*\*\`documented\_types\`\*\* and \*\*\`documented\_names\`\*\* — hardcoded guidance covering common conventions even when the workroom has no rows of that type yet, including which segment-DSL category to use for flow triggers.\
> &#x20; \- \*\*\`filter\_guidance\`\*\* — plain-English hints on which \`filter\[…]\` to use for common lookups.\
> \
> Workroom-aware via \`?workroom=\<name-or-id>\` or the \`Gleantap-Workroom\` header. Without a scope, aggregates across the account.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Events","description":"Append-only activity events attached to contacts. Powers segments, flows, and analytics."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["events: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":{"EventCatalog":{"type":"object","description":"Machine-readable event vocabulary for the account/workroom. Combines the legacy `type`-based dimension (dashboard-emitted events) with the v3-native `event_name` dimension (v3-emitted events), plus documented conventions for both.\n","properties":{"object":{"type":"string","enum":["event_catalog"]},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true},"types":{"type":"array","description":"Legacy `type` values observed on externalevents. Use with `filter[type]=<value>` when listing events or building flow triggers.","items":{"type":"object","properties":{"value":{"type":"string","description":"The `type` field value."},"count":{"type":"integer"},"last_seen_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"is_flags":{"type":"array","items":{"type":"string"},"description":"Boolean flags observed alongside this type (`is_appointment`, `is_badge`, `is_purchase`, ...)."},"sample_property_keys":{"type":"array","items":{"type":"string"},"description":"Property keys present under `data.*` on a sample event of this type."},"sample_event_id":{"$ref":"#/components/schemas/EventId"}}}},"event_names":{"type":"array","description":"v3-native `event_name` values (dot-notation). Only present on events emitted through v3 API.","items":{"type":"object","properties":{"value":{"type":"string"},"count":{"type":"integer"},"last_seen_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"derived_type":{"type":"string","nullable":true,"description":"The legacy `type` this event_name derives to."},"sample_property_keys":{"type":"array","items":{"type":"string"}},"sample_event_id":{"$ref":"#/components/schemas/EventId"}}}},"documented_types":{"type":"array","description":"Hardcoded catalog of well-known `type` values with descriptions and flow-trigger guidance. Present even when no rows of that type exist yet.","items":{"type":"object","properties":{"value":{"type":"string"},"description":{"type":"string"},"is_flag":{"type":"string","nullable":true},"flow_trigger":{"type":"string","nullable":true,"description":"Recommended segment-DSL category for triggering flows on this type of event."}}}},"documented_names":{"type":"array","description":"Hardcoded catalog of v3 dot-notation event_name conventions to prefer for new emissions.","items":{"type":"object","properties":{"value":{"type":"string"},"description":{"type":"string"},"derived_type":{"type":"string"},"is_flags":{"type":"array","items":{"type":"string"}}}}},"filter_guidance":{"type":"array","items":{"type":"string"}}}},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"EventId":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$"}}},"paths":{"/events/catalog":{"get":{"tags":["Events"],"operationId":"describeEventCatalog","summary":"Enumerate available event names, types, and flags for this workroom.","description":"Catalog for authoring a flow trigger or a segment condition that keys on an event. Returns the union of every event vocabulary currently active on the workroom's `externalevents` collection:\n\n  - **`types`** — distinct legacy `type` values observed with counts, last-seen timestamps, sample `data.*` property keys, and the `is_*` flag(s) each type carries. Legacy dashboard-emitted events use `type` as the primary discriminator (`type: \"appointment\"`, `type: \"badge\"`, `type: \"sale\"`, etc.) with no dot-notation event_name. This is the dimension you'll most often use for flow triggers.\n  - **`event_names`** — distinct v3-native dot-notation `event_name` values (`purchase.completed`, `visit.checked_in`, `form.submitted`) with the same metadata. Only populated on events created through v3 API paths.\n  - **`documented_types`** and **`documented_names`** — hardcoded guidance covering common conventions even when the workroom has no rows of that type yet, including which segment-DSL category to use for flow triggers.\n  - **`filter_guidance`** — plain-English hints on which `filter[…]` to use for common lookups.\n\nWorkroom-aware via `?workroom=<name-or-id>` or the `Gleantap-Workroom` header. Without a scope, aggregates across the account.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"The event catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventCatalog"}}}}}}}}}
```

## Bulk-create events.

> Up to 10,000 events per request. Returns a \`job\` immediately; ingestion is async. Bulk sends still trigger flows and segment recompute, but with minutes of lag, so downstream triggers are not synchronously acknowledged. \`Idempotency-Key\` is required. Rate limit bucket: \`bulk\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Events","description":"Append-only activity events attached to contacts. Powers segments, flows, and analytics."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["events: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":{"EventBulkCreate":{"type":"object","required":["data"],"description":"Bulk event insertion. Max 10,000 events per request. Returns a `job` immediately; large batches are ingested asynchronously.\n","properties":{"data":{"type":"array","maxItems":10000,"items":{"$ref":"#/components/schemas/EventCreate"}}}},"EventCreate":{"type":"object","required":["name","contact_id","occurred_at"],"description":"Record a new event. Idempotency via `Idempotency-Key` is strongly recommended if the caller may retry —\nwithout it, network retries create duplicate events that skew counts in segments and reports.\n","properties":{"name":{"type":"string","pattern":"^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"},"contact_id":{"$ref":"#/components/schemas/ContactId"},"location_id":{"$ref":"#/components/schemas/LocationId"},"properties":{"type":"object","additionalProperties":true},"occurred_at":{"$ref":"#/components/schemas/Timestamp","description":"When the event occurred. A timestamp without a UTC offset (e.g. `2026-05-01 18:00`) is read in the account's timezone; include `Z` or an offset to be explicit."}}},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"LocationId":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Job":{"type":"object","description":"Job record. Bulk work runs inline, so a job is finished by the time its POST returns: contacts bulk answers `completed` (with `kind`/`progress`/`errors`/`result` alongside the summary counts), events bulk answers `succeeded` or `failed` (with per-row `errors`). The `id` addresses the job afterwards — `GET /v3/jobs/{id}` returns this same body, so a caller that lost the response can read it back instead of re-running the batch.\n","required":["id","object","status","operation","created_at"],"properties":{"id":{"$ref":"#/components/schemas/JobId"},"object":{"type":"string","const":"job"},"status":{"type":"string","enum":["queued","running","succeeded","completed","failed","canceled"],"description":"`completed` — ran inline to the end (check `failed` / `errors` for per-row failures)."},"kind":{"type":"string","description":"Legacy name of the operation, e.g. `contacts.upsert`. Prefer `operation`."},"progress":{"type":"object","properties":{"total":{"type":"integer"},"processed":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"created":{"type":"integer"},"updated":{"type":"integer"},"deleted":{"type":"integer"}}},"result":{"type":"object","properties":{"contact_ids":{"type":"array","items":{"$ref":"#/components/schemas/ContactId"}}}},"completed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"operation":{"type":"string","description":"The operation this job is running (e.g., `contacts.bulk_upsert`, `events.bulk_create`)."},"total":{"type":"integer","minimum":0},"succeeded":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"result_url":{"type":"string","nullable":true,"description":"On success, a short-lived signed URL to the result payload if it's too large to inline."},"errors_url":{"type":"string","nullable":true,"description":"On partial success, a signed URL to a CSV listing per-row errors."},"errors":{"type":"array","description":"Per-row failures, inline, for jobs processed synchronously (e.g. `events.bulk_create`). A job that ran to completion has `status: succeeded` even when some rows failed — check `failed` / `errors`. `status: failed` means no row succeeded.","items":{"type":"object","properties":{"index":{"type":"integer","description":"Zero-based position in the request `data` array."},"code":{"type":"string"},"message":{"type":"string"}}}},"created_at":{"$ref":"#/components/schemas/Timestamp"},"started_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"finished_at":{"$ref":"#/components/schemas/Timestamp","nullable":true}}},"JobId":{"type":"string","pattern":"^job_[0-9A-HJKMNP-TV-Z]{26}$"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"TooManyRequests":{"description":"Rate limited.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"headers":{"RetryAfter":{"description":"On 429, seconds to wait before retrying.","schema":{"type":"integer"}}}},"paths":{"/events/bulk":{"post":{"tags":["Events"],"operationId":"bulkCreateEvents","summary":"Bulk-create events.","description":"Up to 10,000 events per request. Returns a `job` immediately; ingestion is async. Bulk sends still trigger flows and segment recompute, but with minutes of lag, so downstream triggers are not synchronously acknowledged. `Idempotency-Key` is required. Rate limit bucket: `bulk`.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventBulkCreate"}}}},"responses":{"202":{"description":"Job accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```
