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

# Contacts

The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count.

## List contacts.

> Paginated list of contacts, most recent first. Common filters: \`?filter\[email]=\`, \`?filter\[phone]=\`, \`?filter\[external\_id]=\`, \`?filter\[tags]=vip,trial\`, \`?filter\[created\_at]\[gte]=...\`, \`?filter\[consent.email.status]=opted\_in\`, \`?filter\[deleted]=true\` (soft-deleted excluded by default). For known-ID lookups use \`GET /v3/contacts/{id}\`; for audience DSL use \`POST /v3/segments/preview\`. Supports backward paging via \`?before=\<prev\_cursor>\`. To retrieve a complete contact set (full export or sync, including \`filter\[deleted]=true\`), use \`sort=-id\` (or \`sort=id\`): it pages on the contact id in a stable order and stays fast on large workrooms, whereas the default recency sort can be slow on workrooms with 100k+ contacts. Follow \`next\_cursor\` until \`has\_more\` is false, and compare the row total with the contacts count for the same filters to confirm full coverage. Rate limit bucket: \`read\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts: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"}},"BeforeParam":{"name":"before","in":"query","required":false,"description":"Opaque cursor from a prior response's `prev_cursor`, to fetch the PREVIOUS page. Supported on listContacts and listSegmentContacts only. If both `before` and `cursor` are sent, `before` wins.","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"}},"FieldsParam":{"name":"fields","in":"query","required":false,"description":"Sparse fieldset — comma-separated list of fields to include in the response. Reduces payload size on high-volume reads. Nested field access is not supported; request the parent object.\n","schema":{"type":"string"}}},"headers":{"XRequestId":{"description":"Unique ID for this request. Include when reporting issues.","schema":{"type":"string","pattern":"^req_[A-Za-z0-9]+$"}},"XRateLimitLimit":{"description":"Requests permitted in the current window.","schema":{"type":"integer"}},"XRateLimitRemaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"XRateLimitReset":{"description":"Unix timestamp (seconds) when the current window resets.","schema":{"type":"integer"}},"RetryAfter":{"description":"On 429, seconds to wait before retrying.","schema":{"type":"integer"}}},"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`."}}},"Contact":{"type":"object","description":"A person record. Central to almost every other resource in Gleantap.\nContacts have an internal id (`con_<24-hex>`) and optionally an external ID (`external_id`) you set from your own system. Both can be used to look up the record.\n","required":["id","object","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/ContactId"},"object":{"type":"string","const":"contact"},"external_id":{"type":"string","nullable":true,"description":"Your system's ID for this contact. Unique within the account. For contacts synced by an integration this is the member id the integration stores in `user_id` (returned when `external_id` itself is unset and `user_id` is not just the email/phone). `filter[external_id]` and `GET /v3/contacts/external_id:<x>` match either field, as string or integer."},"email":{"$ref":"#/components/schemas/Email","nullable":true},"phone":{"$ref":"#/components/schemas/PhoneE164","nullable":true,"description":"Stored the way every Gleantap writer stores it (formatPhone) — a `+` number is kept, a national number gets the account's country code (US/CA +1, GB +44, AU +61 with the trunk 0 dropped, NL, DK, LB, AE). Writes accept either form."},"first_name":{"type":"string","nullable":true,"maxLength":100},"last_name":{"type":"string","nullable":true,"maxLength":100},"date_of_birth":{"$ref":"#/components/schemas/Date","nullable":true,"description":"Stored as `personalinfo.dob` (date) + `personalinfo.birthday` (day of year), the pair birthday segments, campaigns and loyalty birthday rewards match on; `data.dob` is kept in step."},"locale":{"$ref":"#/components/schemas/Locale","nullable":true},"timezone":{"$ref":"#/components/schemas/Timezone","nullable":true},"tags":{"type":"array","items":{"$ref":"#/components/schemas/TagName"},"description":"All tags currently applied to this contact (`sales.tags`, the list the dashboard shows)."},"custom_fields":{"type":"object","additionalProperties":true,"description":"Account-defined custom fields. Schema is per-workroom (see `/v3/custom_fields`). Values are coerced to the declared type on write, as the dashboard CSV import does: date → stored date (a bare `YYYY-MM-DD` is midnight in the account timezone), number → integer/decimal, boolean → true/false. Dates are returned as ISO-8601 strings.\n"},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/ContactMembership"},"description":"The contact's memberships/plans. Segment engine reads `memberships.status` / `memberships.type` / `memberships.renewal_date` / etc. directly off this array. Populated by CRM syncs (Mariana etc.) or by direct API writes.\n"},"consent":{"type":"object","description":"Per-channel consent records. Server-enforced on all marketing sends.","properties":{"sms":{"$ref":"#/components/schemas/ConsentRecord"},"email":{"$ref":"#/components/schemas/ConsentRecord"}}},"primary_location_id":{"$ref":"#/components/schemas/LocationId","nullable":true,"description":"Not populated yet (no Location resource). Use `location` / `location_id`."},"location":{"type":"string","nullable":true,"description":"The contact's location/club name as the integration or CSV import recorded it (`accountinfo.location`, else `data.location` / `data.location_name`). Numeric on some accounts; always returned as a string. Same value `filter[location]` matches."},"location_id":{"type":"string","nullable":true,"description":"The integration's location id (`accountinfo.location_id`, else `data.location_id`)."},"member_status":{"type":"string","nullable":true,"description":"Membership/account status as synced (`accountinfo.status`), e.g. `active`, `inactive`, `cancelled`. Vocabulary is the integration's."},"owner_user_id":{"$ref":"#/components/schemas/UserId","nullable":true},"segments":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Segment IDs this contact is currently a member of. Eventually consistent (up to minutes of lag from an underlying data change)."},"pipelines":{"type":"array","description":"Pipelines and stages this contact currently belongs to.","items":{"type":"object","properties":{"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"stage_id":{"$ref":"#/components/schemas/StageId","nullable":true},"stage_name":{"type":"string","nullable":true},"status":{"type":"string"},"added_at":{"$ref":"#/components/schemas/Timestamp"},"last_updated_at":{"$ref":"#/components/schemas/Timestamp"}}}},"lifecycle_stage":{"type":"string","nullable":true,"description":"Stage label stored in `accountinfo.type`. The values in real data are `member`, `prospect`, `past` and `non-member`, plus raw labels integrations pass through in their own case (`Kid`, `Parent`, `Individual`, …). Not enforced; `filter[lifecycle_stage]` matches case-insensitively. Writing `member` (or `customer`) also sets `accountinfo.member: 1`; anything other than member/former sets `accountinfo.prospect: 1`.\n"},"last_seen_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp","description":"Last change by any writer — the later of v3's own stamp and the `last_updated_on` the integrations and dashboard maintain. `sort=updated_at` orders by `last_updated_on`."},"deleted_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Set if this contact was soft-deleted. Soft-deleted contacts are hidden from all list endpoints, the dashboard and every send by default; include `?filter[deleted]=true` to see them. Merged-away contacts also carry it."},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"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"},"Email":{"type":"string","format":"email"},"PhoneE164":{"type":"string","description":"E.164 international phone format.","pattern":"^\\+[1-9]\\d{1,14}$"},"Date":{"type":"string","format":"date","description":"Calendar date (no time), ISO 8601 `YYYY-MM-DD`."},"Locale":{"type":"string","description":"BCP 47 locale tag."},"Timezone":{"type":"string","description":"IANA timezone name."},"TagName":{"type":"string","description":"Tag name. Case-preserving, but case-insensitive on match. Whitespace preserved.","pattern":"^[^\\n\\r]{1,100}$"},"ContactMembership":{"type":"object","description":"A single membership/plan on a contact. Stored inline on `userdetails.memberships[]` (the segment DSL's `memberships.*` category queries this array via `$elemMatch`). Purchases live on events, but memberships live here because the segment engine needs cheap membership-status lookups without JOINing.\n","required":["id","name"],"properties":{"id":{"type":"string","description":"External identifier (from CRM / source system). Not a v3-prefixed ID."},"name":{"type":"string","description":"Plan name (e.g., \"Unlimited Monthly\", \"Class Pack — 10 sessions\")."},"type":{"type":"string","nullable":true,"description":"Optional plan type discriminator (e.g., \"monthly\", \"annual\", \"class_pack\")."},"status":{"type":"string","nullable":true,"description":"Current membership status. Common values: `active`, `on hold`, `cancelled`, `expired`, `pending cancel`. Free-form — call `GET /v3/segments/schema` to see `possible_values` observed in the current workroom. Mirrored to `member_status` on write.\n"},"member_status":{"type":"string","nullable":true,"description":"Segment-engine mirror of `status`. If you only set `status`, this is auto-populated (and vice versa) so segments querying either field find the contact."},"member_status_date":{"type":"string","format":"date-time","nullable":true,"description":"When the status was last set (used for tenure segments)."},"price":{"type":"number","nullable":true,"description":"Plan price in the account's currency."},"total_sessions":{"type":"integer","nullable":true,"description":"For class-pack / punch-card style memberships — the total number of sessions the plan grants at start (e.g., \"10-Class Pack\" → 10). Segment engine reads `memberships.total_sessions` as Numeric.\n"},"sessions_remaining":{"type":"integer","nullable":true,"description":"For class-pack / punch-card style memberships — sessions the contact has left. Decrement client-side or via CRM sync when a class is attended. Segments commonly filter on `memberships.sessions_remaining <= 2` for \"sessions running low\" campaigns.\n"},"location_id":{"type":"string","nullable":true,"description":"External location identifier (e.g., a Mariana / CRM location ID). Not a v3 `loc_` prefixed ID."},"start_date":{"type":"string","format":"date-time","nullable":true},"begin_date":{"type":"string","format":"date-time","nullable":true,"description":"Alias of `start_date` in some source systems."},"renewal_date":{"type":"string","format":"date-time","nullable":true},"next_billing_date":{"type":"string","format":"date-time","nullable":true},"end_date":{"type":"string","format":"date-time","nullable":true},"expiration_date":{"type":"string","format":"date-time","nullable":true},"renewal_type":{"type":"string","nullable":true,"description":"How the plan renews. Common values: `monthly`, `annual`, `manual`."},"invoice_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"External invoice identifiers linked to this membership."}},"additionalProperties":true},"ConsentRecord":{"type":"object","required":["status"],"properties":{"status":{"$ref":"#/components/schemas/ConsentStatus"},"source":{"type":"string","description":"How consent was captured (`form_submission`, `import`, `api`, `admin_ui`, `double_opt_in_confirmed`).","nullable":true},"timestamp":{"$ref":"#/components/schemas/Timestamp","nullable":true},"source_ip":{"type":"string","nullable":true},"source_user_agent":{"type":"string","nullable":true}}},"ConsentStatus":{"type":"string","enum":["opted_in","opted_out","unknown","pending"],"description":"Consent state for a given channel. `opted_in` means the contact affirmatively consented (via form, import with proof, or explicit API call). `opted_out` means they revoked consent. `unknown` is the default for imported contacts without proof. `pending` means an opt-in confirmation was sent but not yet completed.\n"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"LocationId":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"},"UserId":{"type":"string","pattern":"^usr_[0-9A-HJKMNP-TV-Z]{26}$"},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"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":{"Unauthorized":{"description":"Missing or invalid credentials.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Forbidden":{"description":"Authenticated but not authorized (scope, role, or feature-flag mismatch).","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"}}}}}},"paths":{"/contacts":{"get":{"tags":["Contacts"],"operationId":"listContacts","summary":"List contacts.","description":"Paginated list of contacts, most recent first. Common filters: `?filter[email]=`, `?filter[phone]=`, `?filter[external_id]=`, `?filter[tags]=vip,trial`, `?filter[created_at][gte]=...`, `?filter[consent.email.status]=opted_in`, `?filter[deleted]=true` (soft-deleted excluded by default). For known-ID lookups use `GET /v3/contacts/{id}`; for audience DSL use `POST /v3/segments/preview`. Supports backward paging via `?before=<prev_cursor>`. To retrieve a complete contact set (full export or sync, including `filter[deleted]=true`), use `sort=-id` (or `sort=id`): it pages on the contact id in a stable order and stays fast on large workrooms, whereas the default recency sort can be slow on workrooms with 100k+ contacts. Follow `next_cursor` until `has_more` is false, and compare the row total with the contacts count for the same filters to confirm full coverage. 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/BeforeParam"},{"$ref":"#/components/parameters/SortParam"},{"$ref":"#/components/parameters/FieldsParam"},{"name":"filter","in":"query","style":"deepObject","explode":true,"description":"Filterable fields. Anything outside this list is REJECTED, not ignored — a dropped filter would return the unfiltered total, which reads as an answer rather than as the mistake it is.\n\n`email` (case-insensitive), `external_id` (also matches the integration member id in `user_id`), `phone` (national numbers are formatted with the account's country code, as stored), `lifecycle_stage` (case-insensitive), `tags`, `deleted`, `created_at` (with `gte`/`gt`/`lte`/`lt`), `location` (exact, case-insensitive, matches numeric locations), `has_email`, `has_phone`, `subscribed_email`, `subscribed_sms`, `reachable_email`, `reachable_sms`, `consent.email.status`, `consent.sms.status` (`opted_out` or `opted_in`), `suppression` (`sms_unsubscribes`, `email_unsubscribes`, `email_bounces`, `sms_bounces`, `email_complaints`, `email_inactive`), `suppressed_email`, `suppressed_sms`.\n\nThe two `subscribed_*` filters are consent only: they read the opt-out flag, where an absent flag means subscribed — so `subscribed_email=false` finds contacts who actively opted out, not contacts with no preference recorded. A subscribed contact can still be undeliverable.\n\nThe two `reachable_*` filters are what a send would actually reach — the dashboard's email/SMS member counts and the send path's own checks: subscribed AND an address on file AND not suppressed as invalid (`reachable_email` excludes bounced, complained and inactive addresses — `invalid_email` 2/3/4; `reachable_sms` excludes failed numbers — `invalid_phone` 1). Use these to size an audience.\n\n`consent.<channel>.status=opted_out` is the same test as `subscribed_<channel>=false`. SMS opt-outs match the dashboard's SMS unsubscribe list (contacts unsubscribed by STOP replies, imports and integrations as well as through this API). To pull a complete list, page with `cursor` until `has_more` is false.\n","schema":{"type":"object","additionalProperties":{"type":"string"}}}],"responses":{"200":{"description":"A page of contacts.","headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```

## Create or upsert a contact.

> Upsert by default — if an existing contact matches on \`match\_on\` (default \`email\`), it's updated; otherwise a new record is created. Set \`match\_on: "none"\` to force create and 409 on match. If you already have the ID use \`PATCH /v3/contacts/{id}\`; for 5k+ records use \`POST /v3/contacts/bulk\`. Provide \`consent.sms\` / \`consent.email\` with source and timestamp if the contact will receive marketing sends — otherwise sends return 422 \`compliance\_block\`. Rate limit bucket: \`write\`.\
> \
> \*\*Structured domain data\*\* (memberships, purchases, visits) has first-class handling and does not belong in \`custom\_fields\`:\
> \
> &#x20; \- \*\*Memberships / plans\*\* → pass \`memberships\[]\` (array of \`ContactMembership\` objects) on this endpoint. Segment engine reads \`memberships.status\`, \`memberships.type\`, \`memberships.renewal\_date\`, etc. directly off the contact.\
> &#x20; \- \*\*Purchases\*\* → record via \`POST /v3/events\` with \`name: "purchase.completed"\` (or \`.refunded\`, etc.) and \`properties.product\_name\` + \`properties.amount\`. The events model auto-updates the contact's \`purchases.\*\` summary counters and secondaryobject product master.\
> &#x20; \- \*\*Visits / class check-ins\*\* → \`POST /v3/events\` with \`name: "visit.checked\_in"\` and \`properties.class\_name\`. Sets \`is\_visit=1\` and populates the \`visits.\*\` category for segments.\
> \
> Use \`custom\_fields\` only for genuinely account-specific attributes with no built-in category (see \`GET /v3/segments/schema\` for the current category list).\
> \
> Requires at least an email or phone. 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":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts: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":{"ContactCreate":{"type":"object","description":"Body for creating or upserting a contact.\n- If you pass an `email`, `phone`, or `external_id` that matches an existing contact in this account, the existing record is updated (upsert).\n- Provide `match_on` in the request to control which field is used for matching (default: `email` if provided, else `phone`, else `external_id`).\n- `consent` is optional but recommended for any contact that may receive marketing messages — sending to a contact without opted-in consent returns 422 `compliance_block`.\n","anyOf":[{"required":["email"]},{"required":["phone"]},{"required":["external_id"]},{"required":["match_on"]}],"properties":{"external_id":{"type":"string","maxLength":200},"email":{"$ref":"#/components/schemas/Email"},"phone":{"$ref":"#/components/schemas/PhoneE164"},"first_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":100},"date_of_birth":{"$ref":"#/components/schemas/Date"},"locale":{"$ref":"#/components/schemas/Locale"},"timezone":{"$ref":"#/components/schemas/Timezone"},"tags":{"type":"array","items":{"$ref":"#/components/schemas/TagName"}},"custom_fields":{"type":"object","additionalProperties":true},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/ContactMembership"},"description":"Optional. Set the contact's memberships/plans in one shot. Full replacement — pass the complete current set (this is how CRM syncs write). To bump a single membership use PATCH with the updated array.\n"},"consent":{"type":"object","properties":{"sms":{"$ref":"#/components/schemas/ConsentRecord"},"email":{"$ref":"#/components/schemas/ConsentRecord"}}},"primary_location_id":{"$ref":"#/components/schemas/LocationId"},"owner_user_id":{"$ref":"#/components/schemas/UserId"},"lifecycle_stage":{"type":"string","maxLength":50},"metadata":{"$ref":"#/components/schemas/Metadata"},"match_on":{"type":"string","enum":["email","phone","external_id","id","none"],"description":"Which field to use for upsert matching. Default heuristic: `email` if provided, else `phone`, else `external_id`. Set `none` to always create a new record (no upsert).\n"}}},"Email":{"type":"string","format":"email"},"PhoneE164":{"type":"string","description":"E.164 international phone format.","pattern":"^\\+[1-9]\\d{1,14}$"},"Date":{"type":"string","format":"date","description":"Calendar date (no time), ISO 8601 `YYYY-MM-DD`."},"Locale":{"type":"string","description":"BCP 47 locale tag."},"Timezone":{"type":"string","description":"IANA timezone name."},"TagName":{"type":"string","description":"Tag name. Case-preserving, but case-insensitive on match. Whitespace preserved.","pattern":"^[^\\n\\r]{1,100}$"},"ContactMembership":{"type":"object","description":"A single membership/plan on a contact. Stored inline on `userdetails.memberships[]` (the segment DSL's `memberships.*` category queries this array via `$elemMatch`). Purchases live on events, but memberships live here because the segment engine needs cheap membership-status lookups without JOINing.\n","required":["id","name"],"properties":{"id":{"type":"string","description":"External identifier (from CRM / source system). Not a v3-prefixed ID."},"name":{"type":"string","description":"Plan name (e.g., \"Unlimited Monthly\", \"Class Pack — 10 sessions\")."},"type":{"type":"string","nullable":true,"description":"Optional plan type discriminator (e.g., \"monthly\", \"annual\", \"class_pack\")."},"status":{"type":"string","nullable":true,"description":"Current membership status. Common values: `active`, `on hold`, `cancelled`, `expired`, `pending cancel`. Free-form — call `GET /v3/segments/schema` to see `possible_values` observed in the current workroom. Mirrored to `member_status` on write.\n"},"member_status":{"type":"string","nullable":true,"description":"Segment-engine mirror of `status`. If you only set `status`, this is auto-populated (and vice versa) so segments querying either field find the contact."},"member_status_date":{"type":"string","format":"date-time","nullable":true,"description":"When the status was last set (used for tenure segments)."},"price":{"type":"number","nullable":true,"description":"Plan price in the account's currency."},"total_sessions":{"type":"integer","nullable":true,"description":"For class-pack / punch-card style memberships — the total number of sessions the plan grants at start (e.g., \"10-Class Pack\" → 10). Segment engine reads `memberships.total_sessions` as Numeric.\n"},"sessions_remaining":{"type":"integer","nullable":true,"description":"For class-pack / punch-card style memberships — sessions the contact has left. Decrement client-side or via CRM sync when a class is attended. Segments commonly filter on `memberships.sessions_remaining <= 2` for \"sessions running low\" campaigns.\n"},"location_id":{"type":"string","nullable":true,"description":"External location identifier (e.g., a Mariana / CRM location ID). Not a v3 `loc_` prefixed ID."},"start_date":{"type":"string","format":"date-time","nullable":true},"begin_date":{"type":"string","format":"date-time","nullable":true,"description":"Alias of `start_date` in some source systems."},"renewal_date":{"type":"string","format":"date-time","nullable":true},"next_billing_date":{"type":"string","format":"date-time","nullable":true},"end_date":{"type":"string","format":"date-time","nullable":true},"expiration_date":{"type":"string","format":"date-time","nullable":true},"renewal_type":{"type":"string","nullable":true,"description":"How the plan renews. Common values: `monthly`, `annual`, `manual`."},"invoice_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"External invoice identifiers linked to this membership."}},"additionalProperties":true},"ConsentRecord":{"type":"object","required":["status"],"properties":{"status":{"$ref":"#/components/schemas/ConsentStatus"},"source":{"type":"string","description":"How consent was captured (`form_submission`, `import`, `api`, `admin_ui`, `double_opt_in_confirmed`).","nullable":true},"timestamp":{"$ref":"#/components/schemas/Timestamp","nullable":true},"source_ip":{"type":"string","nullable":true},"source_user_agent":{"type":"string","nullable":true}}},"ConsentStatus":{"type":"string","enum":["opted_in","opted_out","unknown","pending"],"description":"Consent state for a given channel. `opted_in` means the contact affirmatively consented (via form, import with proof, or explicit API call). `opted_out` means they revoked consent. `unknown` is the default for imported contacts without proof. `pending` means an opt-in confirmation was sent but not yet completed.\n"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"LocationId":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"},"UserId":{"type":"string","pattern":"^usr_[0-9A-HJKMNP-TV-Z]{26}$"},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"Contact":{"type":"object","description":"A person record. Central to almost every other resource in Gleantap.\nContacts have an internal id (`con_<24-hex>`) and optionally an external ID (`external_id`) you set from your own system. Both can be used to look up the record.\n","required":["id","object","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/ContactId"},"object":{"type":"string","const":"contact"},"external_id":{"type":"string","nullable":true,"description":"Your system's ID for this contact. Unique within the account. For contacts synced by an integration this is the member id the integration stores in `user_id` (returned when `external_id` itself is unset and `user_id` is not just the email/phone). `filter[external_id]` and `GET /v3/contacts/external_id:<x>` match either field, as string or integer."},"email":{"$ref":"#/components/schemas/Email","nullable":true},"phone":{"$ref":"#/components/schemas/PhoneE164","nullable":true,"description":"Stored the way every Gleantap writer stores it (formatPhone) — a `+` number is kept, a national number gets the account's country code (US/CA +1, GB +44, AU +61 with the trunk 0 dropped, NL, DK, LB, AE). Writes accept either form."},"first_name":{"type":"string","nullable":true,"maxLength":100},"last_name":{"type":"string","nullable":true,"maxLength":100},"date_of_birth":{"$ref":"#/components/schemas/Date","nullable":true,"description":"Stored as `personalinfo.dob` (date) + `personalinfo.birthday` (day of year), the pair birthday segments, campaigns and loyalty birthday rewards match on; `data.dob` is kept in step."},"locale":{"$ref":"#/components/schemas/Locale","nullable":true},"timezone":{"$ref":"#/components/schemas/Timezone","nullable":true},"tags":{"type":"array","items":{"$ref":"#/components/schemas/TagName"},"description":"All tags currently applied to this contact (`sales.tags`, the list the dashboard shows)."},"custom_fields":{"type":"object","additionalProperties":true,"description":"Account-defined custom fields. Schema is per-workroom (see `/v3/custom_fields`). Values are coerced to the declared type on write, as the dashboard CSV import does: date → stored date (a bare `YYYY-MM-DD` is midnight in the account timezone), number → integer/decimal, boolean → true/false. Dates are returned as ISO-8601 strings.\n"},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/ContactMembership"},"description":"The contact's memberships/plans. Segment engine reads `memberships.status` / `memberships.type` / `memberships.renewal_date` / etc. directly off this array. Populated by CRM syncs (Mariana etc.) or by direct API writes.\n"},"consent":{"type":"object","description":"Per-channel consent records. Server-enforced on all marketing sends.","properties":{"sms":{"$ref":"#/components/schemas/ConsentRecord"},"email":{"$ref":"#/components/schemas/ConsentRecord"}}},"primary_location_id":{"$ref":"#/components/schemas/LocationId","nullable":true,"description":"Not populated yet (no Location resource). Use `location` / `location_id`."},"location":{"type":"string","nullable":true,"description":"The contact's location/club name as the integration or CSV import recorded it (`accountinfo.location`, else `data.location` / `data.location_name`). Numeric on some accounts; always returned as a string. Same value `filter[location]` matches."},"location_id":{"type":"string","nullable":true,"description":"The integration's location id (`accountinfo.location_id`, else `data.location_id`)."},"member_status":{"type":"string","nullable":true,"description":"Membership/account status as synced (`accountinfo.status`), e.g. `active`, `inactive`, `cancelled`. Vocabulary is the integration's."},"owner_user_id":{"$ref":"#/components/schemas/UserId","nullable":true},"segments":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Segment IDs this contact is currently a member of. Eventually consistent (up to minutes of lag from an underlying data change)."},"pipelines":{"type":"array","description":"Pipelines and stages this contact currently belongs to.","items":{"type":"object","properties":{"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"stage_id":{"$ref":"#/components/schemas/StageId","nullable":true},"stage_name":{"type":"string","nullable":true},"status":{"type":"string"},"added_at":{"$ref":"#/components/schemas/Timestamp"},"last_updated_at":{"$ref":"#/components/schemas/Timestamp"}}}},"lifecycle_stage":{"type":"string","nullable":true,"description":"Stage label stored in `accountinfo.type`. The values in real data are `member`, `prospect`, `past` and `non-member`, plus raw labels integrations pass through in their own case (`Kid`, `Parent`, `Individual`, …). Not enforced; `filter[lifecycle_stage]` matches case-insensitively. Writing `member` (or `customer`) also sets `accountinfo.member: 1`; anything other than member/former sets `accountinfo.prospect: 1`.\n"},"last_seen_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp","description":"Last change by any writer — the later of v3's own stamp and the `last_updated_on` the integrations and dashboard maintain. `sort=updated_at` orders by `last_updated_on`."},"deleted_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Set if this contact was soft-deleted. Soft-deleted contacts are hidden from all list endpoints, the dashboard and every send by default; include `?filter[deleted]=true` to see them. Merged-away contacts also carry it."},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"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"},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"StageId":{"type":"string","pattern":"^stg_[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":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"Missing or invalid credentials.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Forbidden":{"description":"Authenticated but not authorized (scope, role, or feature-flag mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Conflict":{"description":"Idempotency conflict, version conflict (`If-Match`), or state conflict.","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"}}}},"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":{"/contacts":{"post":{"tags":["Contacts"],"operationId":"createContact","summary":"Create or upsert a contact.","description":"Upsert by default — if an existing contact matches on `match_on` (default `email`), it's updated; otherwise a new record is created. Set `match_on: \"none\"` to force create and 409 on match. If you already have the ID use `PATCH /v3/contacts/{id}`; for 5k+ records use `POST /v3/contacts/bulk`. Provide `consent.sms` / `consent.email` with source and timestamp if the contact will receive marketing sends — otherwise sends return 422 `compliance_block`. Rate limit bucket: `write`.\n\n**Structured domain data** (memberships, purchases, visits) has first-class handling and does not belong in `custom_fields`:\n\n  - **Memberships / plans** → pass `memberships[]` (array of `ContactMembership` objects) on this endpoint. Segment engine reads `memberships.status`, `memberships.type`, `memberships.renewal_date`, etc. directly off the contact.\n  - **Purchases** → record via `POST /v3/events` with `name: \"purchase.completed\"` (or `.refunded`, etc.) and `properties.product_name` + `properties.amount`. The events model auto-updates the contact's `purchases.*` summary counters and secondaryobject product master.\n  - **Visits / class check-ins** → `POST /v3/events` with `name: \"visit.checked_in\"` and `properties.class_name`. Sets `is_visit=1` and populates the `visits.*` category for segments.\n\nUse `custom_fields` only for genuinely account-specific attributes with no built-in category (see `GET /v3/segments/schema` for the current category list).\n\nRequires at least an email or phone. 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/ContactCreate"}}}},"responses":{"200":{"description":"An existing contact was matched and updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"201":{"description":"A new contact was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```

## Audience size and subscriber growth.

> How large the audience is, how much of it is reachable, and how many contacts arrived in a window. Answers "how many SMS subscribers do we have in Boston" and "how many contacts did we add last month" without listing anyone.\
> \
> Pass \`group\_by=location\` for a per-location breakdown, or \`group\_by=day\` for arrivals over time.\
> \
> Stock and flow are kept apart deliberately. Contact and subscriber counts are current state and do NOT change with the window — only \`new\_contacts\` does. The response says which is which in \`window\.applies\_to\`. The exception is \`group\_by=day\`, where the whole view is scoped to contacts added in the window, so each bucket describes that day's cohort.\
> \
> \*\*Email unsubscribes can be placed in time; SMS opt-outs cannot.\*\* The unsubscribe webhook records \`optout\_email\_on\` alongside the flag, so \`unsubscribed\_in\_window\` is a real windowed figure. The SMS STOP handler records only the flag, so those opt-outs are counted in \`sms\_unsubscribed\_undateable\` and deliberately left out of the windowed figure rather than dated by guesswork.\
> \
> A contact with no phone number has not declined SMS, so unsubscribe rates are computed against the contacts that hold the channel, not the whole audience.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts: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":{"ContactReport":{"type":"object","properties":{"object":{"type":"string","enum":["contact_report"]},"window":{"type":"object","properties":{"since":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"},"timezone":{"type":"string","description":"IANA zone the window's day boundaries (and day groups) are drawn in — the workroom's, as dashboard reports use."},"applies_to":{"type":"string","description":"Which figures the window actually governs","stated plainly.":null}}},"summary":{"$ref":"#/components/schemas/ContactMetrics"}}},"ContactMetrics":{"type":"object","description":"Audience counters. `contacts` and every subscriber figure are CURRENT STATE and do not move with the window; `new_contacts` is the only figure the window governs. The exception is a `day` grouping, where the whole view is scoped to contacts added in the window.\n","properties":{"contacts":{"type":"integer"},"with_email":{"type":"integer","description":"Contacts holding an email address at all."},"with_phone":{"type":"integer"},"email_subscribers":{"type":"integer","description":"Hold an email address and have not opted out (consent only — see email_reachable)."},"sms_subscribers":{"type":"integer","description":"Hold a phone and have not opted out of SMS (consent only)."},"email_suppressed":{"type":"integer","description":"Hold an email address the send path will skip — bounced, complained or inactive (invalid_email 2/3/4), whatever their consent."},"sms_suppressed":{"type":"integer","description":"Hold a phone marked undeliverable (invalid_phone 1)."},"email_reachable":{"type":"integer","description":"What an email send would reach: subscribed and not suppressed. Matches the dashboard's email member count."},"sms_reachable":{"type":"integer","description":"What an SMS send would reach: a top-level phone, subscribed and not suppressed. Matches the dashboard's phone member count."},"email_unsubscribed":{"type":"integer","description":"Current email opt-outs","all time.":null},"unsubscribed_in_window":{"type":"integer","description":"Email unsubscribes that happened within the window. Email only: the unsubscribe webhook records a timestamp, so these can be placed in time.\n"},"sms_unsubscribed_undateable":{"type":"integer","description":"SMS opt-outs that cannot be placed in time, because the STOP handler records only the flag. Reported separately so a growth series shows what it is missing rather than understating churn.\n"},"sms_unsubscribed":{"type":"integer"},"reachable":{"type":"integer","description":"email_reachable OR sms_reachable — a send can actually reach them on at least one channel. Suppressed addresses do not count."},"new_contacts":{"type":"integer","description":"Added within the window."},"reachable_rate":{"type":"number","description":"reachable / contacts."},"email_reachable_rate":{"type":"number","description":"email_reachable / with_email."},"sms_reachable_rate":{"type":"number","description":"sms_reachable / with_phone."},"email_unsubscribe_rate":{"type":"number","description":"email_unsubscribed / with_email — of the contacts that have an address, not of the whole audience."},"sms_unsubscribe_rate":{"type":"number"}}},"ContactReportGrouped":{"type":"object","properties":{"object":{"type":"string","enum":["contact_report_grouped"]},"window":{"type":"object","properties":{"since":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"},"applies_to":{"type":"string"}}},"group_by":{"type":"string"},"summary":{"$ref":"#/components/schemas/ContactMetrics"},"groups":{"type":"array","description":"Ordered by `contacts`, except `group_by=day`, which is chronological. Capped at 500 groups.","items":{"allOf":[{"type":"object","properties":{"key":{"type":"string","description":"The dimension value; `(none)` when the contact carries none."}}},{"$ref":"#/components/schemas/ContactMetrics"}]}}}},"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":{"/contacts/report":{"get":{"tags":["Contacts"],"operationId":"getContactReport","summary":"Audience size and subscriber growth.","description":"How large the audience is, how much of it is reachable, and how many contacts arrived in a window. Answers \"how many SMS subscribers do we have in Boston\" and \"how many contacts did we add last month\" without listing anyone.\n\nPass `group_by=location` for a per-location breakdown, or `group_by=day` for arrivals over time.\n\nStock and flow are kept apart deliberately. Contact and subscriber counts are current state and do NOT change with the window — only `new_contacts` does. The response says which is which in `window.applies_to`. The exception is `group_by=day`, where the whole view is scoped to contacts added in the window, so each bucket describes that day's cohort.\n\n**Email unsubscribes can be placed in time; SMS opt-outs cannot.** The unsubscribe webhook records `optout_email_on` alongside the flag, so `unsubscribed_in_window` is a real windowed figure. The SMS STOP handler records only the flag, so those opt-outs are counted in `sms_unsubscribed_undateable` and deliberately left out of the windowed figure rather than dated by guesswork.\n\nA contact with no phone number has not declined SMS, so unsubscribe rates are computed against the contacts that hold the channel, not the whole audience.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"name":"group_by","in":"query","schema":{"type":"string","enum":["day","location"]}},{"name":"since","in":"query","description":"Start of the window, inclusive. Defaults to midnight 30 days before `until`. A bare date is 00:00:00 of that day in the workroom's timezone (as dashboard reports draw it); a date-time without an offset is read in that zone too.","schema":{"type":"string"}},{"name":"until","in":"query","description":"End of the window, inclusive. Defaults to the end of today. A bare date is 23:59:59 of that day in the workroom's timezone, so `until=2026-06-30` includes the 30th.","schema":{"type":"string"}},{"name":"location","in":"query","description":"Exact match, case-insensitive. Matches numeric locations too.","schema":{"type":"string"}}],"responses":{"200":{"description":"Audience figures, or a breakdown when `group_by` was passed.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ContactReport"},{"$ref":"#/components/schemas/ContactReportGrouped"}]}}}},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## Retrieve a contact.

> Get the full contact record by \`id\` or \`external\_id:\<x>\`. A soft-deleted contact returns 410 unless \`?include\_deleted=true\`. For event history use \`GET /v3/contacts/{id}/events\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts: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"}},"FieldsParam":{"name":"fields","in":"query","required":false,"description":"Sparse fieldset — comma-separated list of fields to include in the response. Reduces payload size on high-volume reads. Nested field access is not supported; request the parent object.\n","schema":{"type":"string"}}},"schemas":{"Contact":{"type":"object","description":"A person record. Central to almost every other resource in Gleantap.\nContacts have an internal id (`con_<24-hex>`) and optionally an external ID (`external_id`) you set from your own system. Both can be used to look up the record.\n","required":["id","object","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/ContactId"},"object":{"type":"string","const":"contact"},"external_id":{"type":"string","nullable":true,"description":"Your system's ID for this contact. Unique within the account. For contacts synced by an integration this is the member id the integration stores in `user_id` (returned when `external_id` itself is unset and `user_id` is not just the email/phone). `filter[external_id]` and `GET /v3/contacts/external_id:<x>` match either field, as string or integer."},"email":{"$ref":"#/components/schemas/Email","nullable":true},"phone":{"$ref":"#/components/schemas/PhoneE164","nullable":true,"description":"Stored the way every Gleantap writer stores it (formatPhone) — a `+` number is kept, a national number gets the account's country code (US/CA +1, GB +44, AU +61 with the trunk 0 dropped, NL, DK, LB, AE). Writes accept either form."},"first_name":{"type":"string","nullable":true,"maxLength":100},"last_name":{"type":"string","nullable":true,"maxLength":100},"date_of_birth":{"$ref":"#/components/schemas/Date","nullable":true,"description":"Stored as `personalinfo.dob` (date) + `personalinfo.birthday` (day of year), the pair birthday segments, campaigns and loyalty birthday rewards match on; `data.dob` is kept in step."},"locale":{"$ref":"#/components/schemas/Locale","nullable":true},"timezone":{"$ref":"#/components/schemas/Timezone","nullable":true},"tags":{"type":"array","items":{"$ref":"#/components/schemas/TagName"},"description":"All tags currently applied to this contact (`sales.tags`, the list the dashboard shows)."},"custom_fields":{"type":"object","additionalProperties":true,"description":"Account-defined custom fields. Schema is per-workroom (see `/v3/custom_fields`). Values are coerced to the declared type on write, as the dashboard CSV import does: date → stored date (a bare `YYYY-MM-DD` is midnight in the account timezone), number → integer/decimal, boolean → true/false. Dates are returned as ISO-8601 strings.\n"},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/ContactMembership"},"description":"The contact's memberships/plans. Segment engine reads `memberships.status` / `memberships.type` / `memberships.renewal_date` / etc. directly off this array. Populated by CRM syncs (Mariana etc.) or by direct API writes.\n"},"consent":{"type":"object","description":"Per-channel consent records. Server-enforced on all marketing sends.","properties":{"sms":{"$ref":"#/components/schemas/ConsentRecord"},"email":{"$ref":"#/components/schemas/ConsentRecord"}}},"primary_location_id":{"$ref":"#/components/schemas/LocationId","nullable":true,"description":"Not populated yet (no Location resource). Use `location` / `location_id`."},"location":{"type":"string","nullable":true,"description":"The contact's location/club name as the integration or CSV import recorded it (`accountinfo.location`, else `data.location` / `data.location_name`). Numeric on some accounts; always returned as a string. Same value `filter[location]` matches."},"location_id":{"type":"string","nullable":true,"description":"The integration's location id (`accountinfo.location_id`, else `data.location_id`)."},"member_status":{"type":"string","nullable":true,"description":"Membership/account status as synced (`accountinfo.status`), e.g. `active`, `inactive`, `cancelled`. Vocabulary is the integration's."},"owner_user_id":{"$ref":"#/components/schemas/UserId","nullable":true},"segments":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Segment IDs this contact is currently a member of. Eventually consistent (up to minutes of lag from an underlying data change)."},"pipelines":{"type":"array","description":"Pipelines and stages this contact currently belongs to.","items":{"type":"object","properties":{"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"stage_id":{"$ref":"#/components/schemas/StageId","nullable":true},"stage_name":{"type":"string","nullable":true},"status":{"type":"string"},"added_at":{"$ref":"#/components/schemas/Timestamp"},"last_updated_at":{"$ref":"#/components/schemas/Timestamp"}}}},"lifecycle_stage":{"type":"string","nullable":true,"description":"Stage label stored in `accountinfo.type`. The values in real data are `member`, `prospect`, `past` and `non-member`, plus raw labels integrations pass through in their own case (`Kid`, `Parent`, `Individual`, …). Not enforced; `filter[lifecycle_stage]` matches case-insensitively. Writing `member` (or `customer`) also sets `accountinfo.member: 1`; anything other than member/former sets `accountinfo.prospect: 1`.\n"},"last_seen_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp","description":"Last change by any writer — the later of v3's own stamp and the `last_updated_on` the integrations and dashboard maintain. `sort=updated_at` orders by `last_updated_on`."},"deleted_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Set if this contact was soft-deleted. Soft-deleted contacts are hidden from all list endpoints, the dashboard and every send by default; include `?filter[deleted]=true` to see them. Merged-away contacts also carry it."},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"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"},"Email":{"type":"string","format":"email"},"PhoneE164":{"type":"string","description":"E.164 international phone format.","pattern":"^\\+[1-9]\\d{1,14}$"},"Date":{"type":"string","format":"date","description":"Calendar date (no time), ISO 8601 `YYYY-MM-DD`."},"Locale":{"type":"string","description":"BCP 47 locale tag."},"Timezone":{"type":"string","description":"IANA timezone name."},"TagName":{"type":"string","description":"Tag name. Case-preserving, but case-insensitive on match. Whitespace preserved.","pattern":"^[^\\n\\r]{1,100}$"},"ContactMembership":{"type":"object","description":"A single membership/plan on a contact. Stored inline on `userdetails.memberships[]` (the segment DSL's `memberships.*` category queries this array via `$elemMatch`). Purchases live on events, but memberships live here because the segment engine needs cheap membership-status lookups without JOINing.\n","required":["id","name"],"properties":{"id":{"type":"string","description":"External identifier (from CRM / source system). Not a v3-prefixed ID."},"name":{"type":"string","description":"Plan name (e.g., \"Unlimited Monthly\", \"Class Pack — 10 sessions\")."},"type":{"type":"string","nullable":true,"description":"Optional plan type discriminator (e.g., \"monthly\", \"annual\", \"class_pack\")."},"status":{"type":"string","nullable":true,"description":"Current membership status. Common values: `active`, `on hold`, `cancelled`, `expired`, `pending cancel`. Free-form — call `GET /v3/segments/schema` to see `possible_values` observed in the current workroom. Mirrored to `member_status` on write.\n"},"member_status":{"type":"string","nullable":true,"description":"Segment-engine mirror of `status`. If you only set `status`, this is auto-populated (and vice versa) so segments querying either field find the contact."},"member_status_date":{"type":"string","format":"date-time","nullable":true,"description":"When the status was last set (used for tenure segments)."},"price":{"type":"number","nullable":true,"description":"Plan price in the account's currency."},"total_sessions":{"type":"integer","nullable":true,"description":"For class-pack / punch-card style memberships — the total number of sessions the plan grants at start (e.g., \"10-Class Pack\" → 10). Segment engine reads `memberships.total_sessions` as Numeric.\n"},"sessions_remaining":{"type":"integer","nullable":true,"description":"For class-pack / punch-card style memberships — sessions the contact has left. Decrement client-side or via CRM sync when a class is attended. Segments commonly filter on `memberships.sessions_remaining <= 2` for \"sessions running low\" campaigns.\n"},"location_id":{"type":"string","nullable":true,"description":"External location identifier (e.g., a Mariana / CRM location ID). Not a v3 `loc_` prefixed ID."},"start_date":{"type":"string","format":"date-time","nullable":true},"begin_date":{"type":"string","format":"date-time","nullable":true,"description":"Alias of `start_date` in some source systems."},"renewal_date":{"type":"string","format":"date-time","nullable":true},"next_billing_date":{"type":"string","format":"date-time","nullable":true},"end_date":{"type":"string","format":"date-time","nullable":true},"expiration_date":{"type":"string","format":"date-time","nullable":true},"renewal_type":{"type":"string","nullable":true,"description":"How the plan renews. Common values: `monthly`, `annual`, `manual`."},"invoice_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"External invoice identifiers linked to this membership."}},"additionalProperties":true},"ConsentRecord":{"type":"object","required":["status"],"properties":{"status":{"$ref":"#/components/schemas/ConsentStatus"},"source":{"type":"string","description":"How consent was captured (`form_submission`, `import`, `api`, `admin_ui`, `double_opt_in_confirmed`).","nullable":true},"timestamp":{"$ref":"#/components/schemas/Timestamp","nullable":true},"source_ip":{"type":"string","nullable":true},"source_user_agent":{"type":"string","nullable":true}}},"ConsentStatus":{"type":"string","enum":["opted_in","opted_out","unknown","pending"],"description":"Consent state for a given channel. `opted_in` means the contact affirmatively consented (via form, import with proof, or explicit API call). `opted_out` means they revoked consent. `unknown` is the default for imported contacts without proof. `pending` means an opt-in confirmation was sent but not yet completed.\n"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"LocationId":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"},"UserId":{"type":"string","pattern":"^usr_[0-9A-HJKMNP-TV-Z]{26}$"},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"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":{"Unauthorized":{"description":"Missing or invalid credentials.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Forbidden":{"description":"Authenticated but not authorized (scope, role, or feature-flag mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/contacts/{id}":{"get":{"tags":["Contacts"],"operationId":"retrieveContact","summary":"Retrieve a contact.","description":"Get the full contact record by `id` or `external_id:<x>`. A soft-deleted contact returns 410 unless `?include_deleted=true`. For event history use `GET /v3/contacts/{id}/events`.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/FieldsParam"}],"responses":{"200":{"description":"The contact.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Update a contact.

> Partial update. Omitting a field means "don't change it"; \`null\` clears it. \`tags\` replaces the full tag set; \`add\_tags\`/\`remove\_tags\` mutate without touching others (mixing \`tags\` with \`add\_tags\`/\`remove\_tags\` returns 400 \`conflicting\_fields\`). \`custom\_fields\` is object-merge — send \`{"field\_x": null}\` to clear one, \`{}\` to no-op. For merges use \`POST /v3/contacts/{id}/merge\`; for opt-out use \`POST /v3/contacts/{id}/opt\_out\` (auditable).<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts: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":{"ContactUpdate":{"type":"object","description":"PATCH semantics: omitting a field means \"don't change it\"; sending `null` means \"clear it\".\nCannot change `id` or `object`. To change `external_id`, use PATCH with the new value — it must remain unique within the account.\n","properties":{"external_id":{"type":"string","nullable":true,"maxLength":200},"email":{"$ref":"#/components/schemas/Email","nullable":true},"phone":{"$ref":"#/components/schemas/PhoneE164","nullable":true},"first_name":{"type":"string","nullable":true,"maxLength":100},"last_name":{"type":"string","nullable":true,"maxLength":100},"date_of_birth":{"$ref":"#/components/schemas/Date","nullable":true},"locale":{"$ref":"#/components/schemas/Locale","nullable":true},"timezone":{"$ref":"#/components/schemas/Timezone","nullable":true},"tags":{"type":"array","items":{"$ref":"#/components/schemas/TagName"},"description":"Replaces the entire tag set. To add/remove individual tags without touching others, use `PATCH` with `add_tags` / `remove_tags` fields instead of `tags`.\n"},"add_tags":{"type":"array","items":{"$ref":"#/components/schemas/TagName"},"description":"Tags to add without touching others."},"remove_tags":{"type":"array","items":{"$ref":"#/components/schemas/TagName"},"description":"Tags to remove without touching others."},"custom_fields":{"type":"object","additionalProperties":true,"description":"Object-level merge. Send `{ \"field_x\": null }` to clear an individual custom field. Send `{}` to no-op.\n"},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/ContactMembership"},"description":"Full-replacement semantics — the array you send becomes the contact's complete membership set. To bump one membership, GET the contact, mutate the array client-side, and PATCH the full array back. Omit the field to leave memberships untouched.\n"},"consent":{"type":"object","properties":{"sms":{"$ref":"#/components/schemas/ConsentRecord"},"email":{"$ref":"#/components/schemas/ConsentRecord"}}},"primary_location_id":{"$ref":"#/components/schemas/LocationId","nullable":true},"owner_user_id":{"$ref":"#/components/schemas/UserId","nullable":true},"lifecycle_stage":{"type":"string","nullable":true,"maxLength":50},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"Email":{"type":"string","format":"email"},"PhoneE164":{"type":"string","description":"E.164 international phone format.","pattern":"^\\+[1-9]\\d{1,14}$"},"Date":{"type":"string","format":"date","description":"Calendar date (no time), ISO 8601 `YYYY-MM-DD`."},"Locale":{"type":"string","description":"BCP 47 locale tag."},"Timezone":{"type":"string","description":"IANA timezone name."},"TagName":{"type":"string","description":"Tag name. Case-preserving, but case-insensitive on match. Whitespace preserved.","pattern":"^[^\\n\\r]{1,100}$"},"ContactMembership":{"type":"object","description":"A single membership/plan on a contact. Stored inline on `userdetails.memberships[]` (the segment DSL's `memberships.*` category queries this array via `$elemMatch`). Purchases live on events, but memberships live here because the segment engine needs cheap membership-status lookups without JOINing.\n","required":["id","name"],"properties":{"id":{"type":"string","description":"External identifier (from CRM / source system). Not a v3-prefixed ID."},"name":{"type":"string","description":"Plan name (e.g., \"Unlimited Monthly\", \"Class Pack — 10 sessions\")."},"type":{"type":"string","nullable":true,"description":"Optional plan type discriminator (e.g., \"monthly\", \"annual\", \"class_pack\")."},"status":{"type":"string","nullable":true,"description":"Current membership status. Common values: `active`, `on hold`, `cancelled`, `expired`, `pending cancel`. Free-form — call `GET /v3/segments/schema` to see `possible_values` observed in the current workroom. Mirrored to `member_status` on write.\n"},"member_status":{"type":"string","nullable":true,"description":"Segment-engine mirror of `status`. If you only set `status`, this is auto-populated (and vice versa) so segments querying either field find the contact."},"member_status_date":{"type":"string","format":"date-time","nullable":true,"description":"When the status was last set (used for tenure segments)."},"price":{"type":"number","nullable":true,"description":"Plan price in the account's currency."},"total_sessions":{"type":"integer","nullable":true,"description":"For class-pack / punch-card style memberships — the total number of sessions the plan grants at start (e.g., \"10-Class Pack\" → 10). Segment engine reads `memberships.total_sessions` as Numeric.\n"},"sessions_remaining":{"type":"integer","nullable":true,"description":"For class-pack / punch-card style memberships — sessions the contact has left. Decrement client-side or via CRM sync when a class is attended. Segments commonly filter on `memberships.sessions_remaining <= 2` for \"sessions running low\" campaigns.\n"},"location_id":{"type":"string","nullable":true,"description":"External location identifier (e.g., a Mariana / CRM location ID). Not a v3 `loc_` prefixed ID."},"start_date":{"type":"string","format":"date-time","nullable":true},"begin_date":{"type":"string","format":"date-time","nullable":true,"description":"Alias of `start_date` in some source systems."},"renewal_date":{"type":"string","format":"date-time","nullable":true},"next_billing_date":{"type":"string","format":"date-time","nullable":true},"end_date":{"type":"string","format":"date-time","nullable":true},"expiration_date":{"type":"string","format":"date-time","nullable":true},"renewal_type":{"type":"string","nullable":true,"description":"How the plan renews. Common values: `monthly`, `annual`, `manual`."},"invoice_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"External invoice identifiers linked to this membership."}},"additionalProperties":true},"ConsentRecord":{"type":"object","required":["status"],"properties":{"status":{"$ref":"#/components/schemas/ConsentStatus"},"source":{"type":"string","description":"How consent was captured (`form_submission`, `import`, `api`, `admin_ui`, `double_opt_in_confirmed`).","nullable":true},"timestamp":{"$ref":"#/components/schemas/Timestamp","nullable":true},"source_ip":{"type":"string","nullable":true},"source_user_agent":{"type":"string","nullable":true}}},"ConsentStatus":{"type":"string","enum":["opted_in","opted_out","unknown","pending"],"description":"Consent state for a given channel. `opted_in` means the contact affirmatively consented (via form, import with proof, or explicit API call). `opted_out` means they revoked consent. `unknown` is the default for imported contacts without proof. `pending` means an opt-in confirmation was sent but not yet completed.\n"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"LocationId":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"},"UserId":{"type":"string","pattern":"^usr_[0-9A-HJKMNP-TV-Z]{26}$"},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"Contact":{"type":"object","description":"A person record. Central to almost every other resource in Gleantap.\nContacts have an internal id (`con_<24-hex>`) and optionally an external ID (`external_id`) you set from your own system. Both can be used to look up the record.\n","required":["id","object","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/ContactId"},"object":{"type":"string","const":"contact"},"external_id":{"type":"string","nullable":true,"description":"Your system's ID for this contact. Unique within the account. For contacts synced by an integration this is the member id the integration stores in `user_id` (returned when `external_id` itself is unset and `user_id` is not just the email/phone). `filter[external_id]` and `GET /v3/contacts/external_id:<x>` match either field, as string or integer."},"email":{"$ref":"#/components/schemas/Email","nullable":true},"phone":{"$ref":"#/components/schemas/PhoneE164","nullable":true,"description":"Stored the way every Gleantap writer stores it (formatPhone) — a `+` number is kept, a national number gets the account's country code (US/CA +1, GB +44, AU +61 with the trunk 0 dropped, NL, DK, LB, AE). Writes accept either form."},"first_name":{"type":"string","nullable":true,"maxLength":100},"last_name":{"type":"string","nullable":true,"maxLength":100},"date_of_birth":{"$ref":"#/components/schemas/Date","nullable":true,"description":"Stored as `personalinfo.dob` (date) + `personalinfo.birthday` (day of year), the pair birthday segments, campaigns and loyalty birthday rewards match on; `data.dob` is kept in step."},"locale":{"$ref":"#/components/schemas/Locale","nullable":true},"timezone":{"$ref":"#/components/schemas/Timezone","nullable":true},"tags":{"type":"array","items":{"$ref":"#/components/schemas/TagName"},"description":"All tags currently applied to this contact (`sales.tags`, the list the dashboard shows)."},"custom_fields":{"type":"object","additionalProperties":true,"description":"Account-defined custom fields. Schema is per-workroom (see `/v3/custom_fields`). Values are coerced to the declared type on write, as the dashboard CSV import does: date → stored date (a bare `YYYY-MM-DD` is midnight in the account timezone), number → integer/decimal, boolean → true/false. Dates are returned as ISO-8601 strings.\n"},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/ContactMembership"},"description":"The contact's memberships/plans. Segment engine reads `memberships.status` / `memberships.type` / `memberships.renewal_date` / etc. directly off this array. Populated by CRM syncs (Mariana etc.) or by direct API writes.\n"},"consent":{"type":"object","description":"Per-channel consent records. Server-enforced on all marketing sends.","properties":{"sms":{"$ref":"#/components/schemas/ConsentRecord"},"email":{"$ref":"#/components/schemas/ConsentRecord"}}},"primary_location_id":{"$ref":"#/components/schemas/LocationId","nullable":true,"description":"Not populated yet (no Location resource). Use `location` / `location_id`."},"location":{"type":"string","nullable":true,"description":"The contact's location/club name as the integration or CSV import recorded it (`accountinfo.location`, else `data.location` / `data.location_name`). Numeric on some accounts; always returned as a string. Same value `filter[location]` matches."},"location_id":{"type":"string","nullable":true,"description":"The integration's location id (`accountinfo.location_id`, else `data.location_id`)."},"member_status":{"type":"string","nullable":true,"description":"Membership/account status as synced (`accountinfo.status`), e.g. `active`, `inactive`, `cancelled`. Vocabulary is the integration's."},"owner_user_id":{"$ref":"#/components/schemas/UserId","nullable":true},"segments":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Segment IDs this contact is currently a member of. Eventually consistent (up to minutes of lag from an underlying data change)."},"pipelines":{"type":"array","description":"Pipelines and stages this contact currently belongs to.","items":{"type":"object","properties":{"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"stage_id":{"$ref":"#/components/schemas/StageId","nullable":true},"stage_name":{"type":"string","nullable":true},"status":{"type":"string"},"added_at":{"$ref":"#/components/schemas/Timestamp"},"last_updated_at":{"$ref":"#/components/schemas/Timestamp"}}}},"lifecycle_stage":{"type":"string","nullable":true,"description":"Stage label stored in `accountinfo.type`. The values in real data are `member`, `prospect`, `past` and `non-member`, plus raw labels integrations pass through in their own case (`Kid`, `Parent`, `Individual`, …). Not enforced; `filter[lifecycle_stage]` matches case-insensitively. Writing `member` (or `customer`) also sets `accountinfo.member: 1`; anything other than member/former sets `accountinfo.prospect: 1`.\n"},"last_seen_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp","description":"Last change by any writer — the later of v3's own stamp and the `last_updated_on` the integrations and dashboard maintain. `sort=updated_at` orders by `last_updated_on`."},"deleted_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Set if this contact was soft-deleted. Soft-deleted contacts are hidden from all list endpoints, the dashboard and every send by default; include `?filter[deleted]=true` to see them. Merged-away contacts also carry it."},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"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"},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"StageId":{"type":"string","pattern":"^stg_[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":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"Missing or invalid credentials.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Forbidden":{"description":"Authenticated but not authorized (scope, role, or feature-flag mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Conflict":{"description":"Idempotency conflict, version conflict (`If-Match`), or state conflict.","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":{"/contacts/{id}":{"patch":{"tags":["Contacts"],"operationId":"updateContact","summary":"Update a contact.","description":"Partial update. Omitting a field means \"don't change it\"; `null` clears it. `tags` replaces the full tag set; `add_tags`/`remove_tags` mutate without touching others (mixing `tags` with `add_tags`/`remove_tags` returns 400 `conflicting_fields`). `custom_fields` is object-merge — send `{\"field_x\": null}` to clear one, `{}` to no-op. For merges use `POST /v3/contacts/{id}/merge`; for opt-out use `POST /v3/contacts/{id}/opt_out` (auditable).\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/ContactUpdate"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## Delete a contact (soft by default).

> Soft delete by default — the contact leaves its workroom the way the integrations retire contacts (it stops appearing in the dashboard, segments and every send), and is restorable via \`PATCH\` with \`deleted\_at: null\`. Pass \`?hard=true\` for permanent delete (requires \`contacts:delete\_hard\` scope, irreversible) — use for GDPR/CCPA erasure; the contact's tasks and appointments are deleted with it, as the dashboard's delete does. To stop marketing sends without losing history, use \`POST /v3/contacts/{id}/opt\_out\` with \`channel: "all"\` instead.\
> \
> \*\*\`?hard=true\` is permanent.\*\* There is no undo and no trash to restore from. Anything that references the deleted record is affected too.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts:write","contacts:delete_hard"]}],"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":{"Unauthorized":{"description":"Missing or invalid credentials.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Forbidden":{"description":"Authenticated but not authorized (scope, role, or feature-flag mismatch).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"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":{"/contacts/{id}":{"delete":{"tags":["Contacts"],"operationId":"deleteContact","summary":"Delete a contact (soft by default).","description":"Soft delete by default — the contact leaves its workroom the way the integrations retire contacts (it stops appearing in the dashboard, segments and every send), and is restorable via `PATCH` with `deleted_at: null`. Pass `?hard=true` for permanent delete (requires `contacts:delete_hard` scope, irreversible) — use for GDPR/CCPA erasure; the contact's tasks and appointments are deleted with it, as the dashboard's delete does. To stop marketing sends without losing history, use `POST /v3/contacts/{id}/opt_out` with `channel: \"all\"` instead.\n\n**`?hard=true` is permanent.** There is no undo and no trash to restore from. 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"},{"name":"hard","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"If true, permanently delete instead of soft-delete. Requires `contacts:delete_hard` scope. Irreversible."}],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Merge another contact into this one.

> Merge \`source\_id\` into the URL contact — the same merge the dashboard and integrations use. URL contact survives; \`source\_id\` is retired (it leaves the workroom, carries \`merged\_to\_user\_id\`, and the destination records it in \`mergehistory\`). Profile fields the destination lacks are filled from the source; tags, CRM tasks/appointments/pipelines/notes, memberships, segment membership, form submissions, flow and campaign history and purchase/visit summaries are unioned. The source's messages, conversations, calls, notes, flow enrolments, campaign sends, tasks, appointments and events are re-pointed to the destination (a campaign/flow the destination already has is left on the source, so nobody is messaged twice). By default (\`prefer\_destination\`) the destination's non-empty values are kept; \`prefer\_source\` / \`most\_recent\` let the source's identity and profile fields (email, phone, name, external\_id, custom fields, date of birth, lifecycle) win. Both contacts must be in the same workroom (422 otherwise). Returns 422 \`compliance\_block\_merge\` if conflicting opt-out states would be silently overridden — resolve consent explicitly first.\
> \
> \*\*Irreversible.\*\* Merging folds one contact's history into another and the source cannot be restored.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts: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":{"ContactMerge":{"type":"object","required":["source_id"],"properties":{"source_id":{"$ref":"#/components/schemas/ContactId","description":"The contact to merge INTO the current one. `source_id`'s data is folded into the URL contact; then `source_id` is retired the way the legacy merge retires it (not restorable). Must be in the same workroom."},"conflict_strategy":{"type":"string","enum":["prefer_destination","prefer_source","most_recent"],"default":"prefer_destination","description":"Which record wins on field conflicts:\n  - `prefer_destination` (default): URL-referenced contact wins.\n  - `prefer_source`: `source_id`'s value wins where non-null.\n  - `most_recent`: the value from whichever record has the later `updated_at`.\nTags, events, memberships, appointments, opportunities, notes, and conversations are always unioned regardless of strategy.\n"}}},"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"},"Contact":{"type":"object","description":"A person record. Central to almost every other resource in Gleantap.\nContacts have an internal id (`con_<24-hex>`) and optionally an external ID (`external_id`) you set from your own system. Both can be used to look up the record.\n","required":["id","object","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/ContactId"},"object":{"type":"string","const":"contact"},"external_id":{"type":"string","nullable":true,"description":"Your system's ID for this contact. Unique within the account. For contacts synced by an integration this is the member id the integration stores in `user_id` (returned when `external_id` itself is unset and `user_id` is not just the email/phone). `filter[external_id]` and `GET /v3/contacts/external_id:<x>` match either field, as string or integer."},"email":{"$ref":"#/components/schemas/Email","nullable":true},"phone":{"$ref":"#/components/schemas/PhoneE164","nullable":true,"description":"Stored the way every Gleantap writer stores it (formatPhone) — a `+` number is kept, a national number gets the account's country code (US/CA +1, GB +44, AU +61 with the trunk 0 dropped, NL, DK, LB, AE). Writes accept either form."},"first_name":{"type":"string","nullable":true,"maxLength":100},"last_name":{"type":"string","nullable":true,"maxLength":100},"date_of_birth":{"$ref":"#/components/schemas/Date","nullable":true,"description":"Stored as `personalinfo.dob` (date) + `personalinfo.birthday` (day of year), the pair birthday segments, campaigns and loyalty birthday rewards match on; `data.dob` is kept in step."},"locale":{"$ref":"#/components/schemas/Locale","nullable":true},"timezone":{"$ref":"#/components/schemas/Timezone","nullable":true},"tags":{"type":"array","items":{"$ref":"#/components/schemas/TagName"},"description":"All tags currently applied to this contact (`sales.tags`, the list the dashboard shows)."},"custom_fields":{"type":"object","additionalProperties":true,"description":"Account-defined custom fields. Schema is per-workroom (see `/v3/custom_fields`). Values are coerced to the declared type on write, as the dashboard CSV import does: date → stored date (a bare `YYYY-MM-DD` is midnight in the account timezone), number → integer/decimal, boolean → true/false. Dates are returned as ISO-8601 strings.\n"},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/ContactMembership"},"description":"The contact's memberships/plans. Segment engine reads `memberships.status` / `memberships.type` / `memberships.renewal_date` / etc. directly off this array. Populated by CRM syncs (Mariana etc.) or by direct API writes.\n"},"consent":{"type":"object","description":"Per-channel consent records. Server-enforced on all marketing sends.","properties":{"sms":{"$ref":"#/components/schemas/ConsentRecord"},"email":{"$ref":"#/components/schemas/ConsentRecord"}}},"primary_location_id":{"$ref":"#/components/schemas/LocationId","nullable":true,"description":"Not populated yet (no Location resource). Use `location` / `location_id`."},"location":{"type":"string","nullable":true,"description":"The contact's location/club name as the integration or CSV import recorded it (`accountinfo.location`, else `data.location` / `data.location_name`). Numeric on some accounts; always returned as a string. Same value `filter[location]` matches."},"location_id":{"type":"string","nullable":true,"description":"The integration's location id (`accountinfo.location_id`, else `data.location_id`)."},"member_status":{"type":"string","nullable":true,"description":"Membership/account status as synced (`accountinfo.status`), e.g. `active`, `inactive`, `cancelled`. Vocabulary is the integration's."},"owner_user_id":{"$ref":"#/components/schemas/UserId","nullable":true},"segments":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Segment IDs this contact is currently a member of. Eventually consistent (up to minutes of lag from an underlying data change)."},"pipelines":{"type":"array","description":"Pipelines and stages this contact currently belongs to.","items":{"type":"object","properties":{"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"stage_id":{"$ref":"#/components/schemas/StageId","nullable":true},"stage_name":{"type":"string","nullable":true},"status":{"type":"string"},"added_at":{"$ref":"#/components/schemas/Timestamp"},"last_updated_at":{"$ref":"#/components/schemas/Timestamp"}}}},"lifecycle_stage":{"type":"string","nullable":true,"description":"Stage label stored in `accountinfo.type`. The values in real data are `member`, `prospect`, `past` and `non-member`, plus raw labels integrations pass through in their own case (`Kid`, `Parent`, `Individual`, …). Not enforced; `filter[lifecycle_stage]` matches case-insensitively. Writing `member` (or `customer`) also sets `accountinfo.member: 1`; anything other than member/former sets `accountinfo.prospect: 1`.\n"},"last_seen_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp","description":"Last change by any writer — the later of v3's own stamp and the `last_updated_on` the integrations and dashboard maintain. `sort=updated_at` orders by `last_updated_on`."},"deleted_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Set if this contact was soft-deleted. Soft-deleted contacts are hidden from all list endpoints, the dashboard and every send by default; include `?filter[deleted]=true` to see them. Merged-away contacts also carry it."},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"Email":{"type":"string","format":"email"},"PhoneE164":{"type":"string","description":"E.164 international phone format.","pattern":"^\\+[1-9]\\d{1,14}$"},"Date":{"type":"string","format":"date","description":"Calendar date (no time), ISO 8601 `YYYY-MM-DD`."},"Locale":{"type":"string","description":"BCP 47 locale tag."},"Timezone":{"type":"string","description":"IANA timezone name."},"TagName":{"type":"string","description":"Tag name. Case-preserving, but case-insensitive on match. Whitespace preserved.","pattern":"^[^\\n\\r]{1,100}$"},"ContactMembership":{"type":"object","description":"A single membership/plan on a contact. Stored inline on `userdetails.memberships[]` (the segment DSL's `memberships.*` category queries this array via `$elemMatch`). Purchases live on events, but memberships live here because the segment engine needs cheap membership-status lookups without JOINing.\n","required":["id","name"],"properties":{"id":{"type":"string","description":"External identifier (from CRM / source system). Not a v3-prefixed ID."},"name":{"type":"string","description":"Plan name (e.g., \"Unlimited Monthly\", \"Class Pack — 10 sessions\")."},"type":{"type":"string","nullable":true,"description":"Optional plan type discriminator (e.g., \"monthly\", \"annual\", \"class_pack\")."},"status":{"type":"string","nullable":true,"description":"Current membership status. Common values: `active`, `on hold`, `cancelled`, `expired`, `pending cancel`. Free-form — call `GET /v3/segments/schema` to see `possible_values` observed in the current workroom. Mirrored to `member_status` on write.\n"},"member_status":{"type":"string","nullable":true,"description":"Segment-engine mirror of `status`. If you only set `status`, this is auto-populated (and vice versa) so segments querying either field find the contact."},"member_status_date":{"type":"string","format":"date-time","nullable":true,"description":"When the status was last set (used for tenure segments)."},"price":{"type":"number","nullable":true,"description":"Plan price in the account's currency."},"total_sessions":{"type":"integer","nullable":true,"description":"For class-pack / punch-card style memberships — the total number of sessions the plan grants at start (e.g., \"10-Class Pack\" → 10). Segment engine reads `memberships.total_sessions` as Numeric.\n"},"sessions_remaining":{"type":"integer","nullable":true,"description":"For class-pack / punch-card style memberships — sessions the contact has left. Decrement client-side or via CRM sync when a class is attended. Segments commonly filter on `memberships.sessions_remaining <= 2` for \"sessions running low\" campaigns.\n"},"location_id":{"type":"string","nullable":true,"description":"External location identifier (e.g., a Mariana / CRM location ID). Not a v3 `loc_` prefixed ID."},"start_date":{"type":"string","format":"date-time","nullable":true},"begin_date":{"type":"string","format":"date-time","nullable":true,"description":"Alias of `start_date` in some source systems."},"renewal_date":{"type":"string","format":"date-time","nullable":true},"next_billing_date":{"type":"string","format":"date-time","nullable":true},"end_date":{"type":"string","format":"date-time","nullable":true},"expiration_date":{"type":"string","format":"date-time","nullable":true},"renewal_type":{"type":"string","nullable":true,"description":"How the plan renews. Common values: `monthly`, `annual`, `manual`."},"invoice_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"External invoice identifiers linked to this membership."}},"additionalProperties":true},"ConsentRecord":{"type":"object","required":["status"],"properties":{"status":{"$ref":"#/components/schemas/ConsentStatus"},"source":{"type":"string","description":"How consent was captured (`form_submission`, `import`, `api`, `admin_ui`, `double_opt_in_confirmed`).","nullable":true},"timestamp":{"$ref":"#/components/schemas/Timestamp","nullable":true},"source_ip":{"type":"string","nullable":true},"source_user_agent":{"type":"string","nullable":true}}},"ConsentStatus":{"type":"string","enum":["opted_in","opted_out","unknown","pending"],"description":"Consent state for a given channel. `opted_in` means the contact affirmatively consented (via form, import with proof, or explicit API call). `opted_out` means they revoked consent. `unknown` is the default for imported contacts without proof. `pending` means an opt-in confirmation was sent but not yet completed.\n"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"LocationId":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"},"UserId":{"type":"string","pattern":"^usr_[0-9A-HJKMNP-TV-Z]{26}$"},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"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"}}}},"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Conflict":{"description":"Idempotency conflict, version conflict (`If-Match`), or state conflict.","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":{"/contacts/{id}/merge":{"post":{"tags":["Contacts"],"operationId":"mergeContact","summary":"Merge another contact into this one.","description":"Merge `source_id` into the URL contact — the same merge the dashboard and integrations use. URL contact survives; `source_id` is retired (it leaves the workroom, carries `merged_to_user_id`, and the destination records it in `mergehistory`). Profile fields the destination lacks are filled from the source; tags, CRM tasks/appointments/pipelines/notes, memberships, segment membership, form submissions, flow and campaign history and purchase/visit summaries are unioned. The source's messages, conversations, calls, notes, flow enrolments, campaign sends, tasks, appointments and events are re-pointed to the destination (a campaign/flow the destination already has is left on the source, so nobody is messaged twice). By default (`prefer_destination`) the destination's non-empty values are kept; `prefer_source` / `most_recent` let the source's identity and profile fields (email, phone, name, external_id, custom fields, date of birth, lifecycle) win. Both contacts must be in the same workroom (422 otherwise). Returns 422 `compliance_block_merge` if conflicting opt-out states would be silently overridden — resolve consent explicitly first.\n\n**Irreversible.** Merging folds one contact's history into another and the source cannot be restored.\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/ContactMerge"}}}},"responses":{"200":{"description":"Merge complete. Returns the destination contact with unioned data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## Record affirmative consent for a channel.

> Compliance-of-record for marketing opt-in. Provide \`source\` and \`timestamp\` — the platform stores them on the contact's consent record and may need them for regulatory review. Transactional sends respect \`opted\_out\` but do not require \`opted\_in\`, so transactional intent alone is not a reason to opt someone in.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts: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":{"ContactOptIn":{"type":"object","required":["channel"],"description":"Record affirmative consent for a marketing channel.\nProviding `source` and `timestamp` is strongly recommended for compliance evidence — the platform stores these on the `ConsentRecord` and shows them on the contact profile.\n","properties":{"channel":{"type":"string","enum":["sms","email"]},"source":{"type":"string","description":"Where the consent came from. Examples: `form_submission`, `import_verified_source`, `api`, `admin_ui`, `double_opt_in_confirmed`."},"timestamp":{"$ref":"#/components/schemas/Timestamp","description":"When the consent was given. Defaults to server time if omitted."},"source_ip":{"type":"string"},"source_user_agent":{"type":"string"}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Contact":{"type":"object","description":"A person record. Central to almost every other resource in Gleantap.\nContacts have an internal id (`con_<24-hex>`) and optionally an external ID (`external_id`) you set from your own system. Both can be used to look up the record.\n","required":["id","object","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/ContactId"},"object":{"type":"string","const":"contact"},"external_id":{"type":"string","nullable":true,"description":"Your system's ID for this contact. Unique within the account. For contacts synced by an integration this is the member id the integration stores in `user_id` (returned when `external_id` itself is unset and `user_id` is not just the email/phone). `filter[external_id]` and `GET /v3/contacts/external_id:<x>` match either field, as string or integer."},"email":{"$ref":"#/components/schemas/Email","nullable":true},"phone":{"$ref":"#/components/schemas/PhoneE164","nullable":true,"description":"Stored the way every Gleantap writer stores it (formatPhone) — a `+` number is kept, a national number gets the account's country code (US/CA +1, GB +44, AU +61 with the trunk 0 dropped, NL, DK, LB, AE). Writes accept either form."},"first_name":{"type":"string","nullable":true,"maxLength":100},"last_name":{"type":"string","nullable":true,"maxLength":100},"date_of_birth":{"$ref":"#/components/schemas/Date","nullable":true,"description":"Stored as `personalinfo.dob` (date) + `personalinfo.birthday` (day of year), the pair birthday segments, campaigns and loyalty birthday rewards match on; `data.dob` is kept in step."},"locale":{"$ref":"#/components/schemas/Locale","nullable":true},"timezone":{"$ref":"#/components/schemas/Timezone","nullable":true},"tags":{"type":"array","items":{"$ref":"#/components/schemas/TagName"},"description":"All tags currently applied to this contact (`sales.tags`, the list the dashboard shows)."},"custom_fields":{"type":"object","additionalProperties":true,"description":"Account-defined custom fields. Schema is per-workroom (see `/v3/custom_fields`). Values are coerced to the declared type on write, as the dashboard CSV import does: date → stored date (a bare `YYYY-MM-DD` is midnight in the account timezone), number → integer/decimal, boolean → true/false. Dates are returned as ISO-8601 strings.\n"},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/ContactMembership"},"description":"The contact's memberships/plans. Segment engine reads `memberships.status` / `memberships.type` / `memberships.renewal_date` / etc. directly off this array. Populated by CRM syncs (Mariana etc.) or by direct API writes.\n"},"consent":{"type":"object","description":"Per-channel consent records. Server-enforced on all marketing sends.","properties":{"sms":{"$ref":"#/components/schemas/ConsentRecord"},"email":{"$ref":"#/components/schemas/ConsentRecord"}}},"primary_location_id":{"$ref":"#/components/schemas/LocationId","nullable":true,"description":"Not populated yet (no Location resource). Use `location` / `location_id`."},"location":{"type":"string","nullable":true,"description":"The contact's location/club name as the integration or CSV import recorded it (`accountinfo.location`, else `data.location` / `data.location_name`). Numeric on some accounts; always returned as a string. Same value `filter[location]` matches."},"location_id":{"type":"string","nullable":true,"description":"The integration's location id (`accountinfo.location_id`, else `data.location_id`)."},"member_status":{"type":"string","nullable":true,"description":"Membership/account status as synced (`accountinfo.status`), e.g. `active`, `inactive`, `cancelled`. Vocabulary is the integration's."},"owner_user_id":{"$ref":"#/components/schemas/UserId","nullable":true},"segments":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Segment IDs this contact is currently a member of. Eventually consistent (up to minutes of lag from an underlying data change)."},"pipelines":{"type":"array","description":"Pipelines and stages this contact currently belongs to.","items":{"type":"object","properties":{"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"stage_id":{"$ref":"#/components/schemas/StageId","nullable":true},"stage_name":{"type":"string","nullable":true},"status":{"type":"string"},"added_at":{"$ref":"#/components/schemas/Timestamp"},"last_updated_at":{"$ref":"#/components/schemas/Timestamp"}}}},"lifecycle_stage":{"type":"string","nullable":true,"description":"Stage label stored in `accountinfo.type`. The values in real data are `member`, `prospect`, `past` and `non-member`, plus raw labels integrations pass through in their own case (`Kid`, `Parent`, `Individual`, …). Not enforced; `filter[lifecycle_stage]` matches case-insensitively. Writing `member` (or `customer`) also sets `accountinfo.member: 1`; anything other than member/former sets `accountinfo.prospect: 1`.\n"},"last_seen_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp","description":"Last change by any writer — the later of v3's own stamp and the `last_updated_on` the integrations and dashboard maintain. `sort=updated_at` orders by `last_updated_on`."},"deleted_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Set if this contact was soft-deleted. Soft-deleted contacts are hidden from all list endpoints, the dashboard and every send by default; include `?filter[deleted]=true` to see them. Merged-away contacts also carry it."},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"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"},"Email":{"type":"string","format":"email"},"PhoneE164":{"type":"string","description":"E.164 international phone format.","pattern":"^\\+[1-9]\\d{1,14}$"},"Date":{"type":"string","format":"date","description":"Calendar date (no time), ISO 8601 `YYYY-MM-DD`."},"Locale":{"type":"string","description":"BCP 47 locale tag."},"Timezone":{"type":"string","description":"IANA timezone name."},"TagName":{"type":"string","description":"Tag name. Case-preserving, but case-insensitive on match. Whitespace preserved.","pattern":"^[^\\n\\r]{1,100}$"},"ContactMembership":{"type":"object","description":"A single membership/plan on a contact. Stored inline on `userdetails.memberships[]` (the segment DSL's `memberships.*` category queries this array via `$elemMatch`). Purchases live on events, but memberships live here because the segment engine needs cheap membership-status lookups without JOINing.\n","required":["id","name"],"properties":{"id":{"type":"string","description":"External identifier (from CRM / source system). Not a v3-prefixed ID."},"name":{"type":"string","description":"Plan name (e.g., \"Unlimited Monthly\", \"Class Pack — 10 sessions\")."},"type":{"type":"string","nullable":true,"description":"Optional plan type discriminator (e.g., \"monthly\", \"annual\", \"class_pack\")."},"status":{"type":"string","nullable":true,"description":"Current membership status. Common values: `active`, `on hold`, `cancelled`, `expired`, `pending cancel`. Free-form — call `GET /v3/segments/schema` to see `possible_values` observed in the current workroom. Mirrored to `member_status` on write.\n"},"member_status":{"type":"string","nullable":true,"description":"Segment-engine mirror of `status`. If you only set `status`, this is auto-populated (and vice versa) so segments querying either field find the contact."},"member_status_date":{"type":"string","format":"date-time","nullable":true,"description":"When the status was last set (used for tenure segments)."},"price":{"type":"number","nullable":true,"description":"Plan price in the account's currency."},"total_sessions":{"type":"integer","nullable":true,"description":"For class-pack / punch-card style memberships — the total number of sessions the plan grants at start (e.g., \"10-Class Pack\" → 10). Segment engine reads `memberships.total_sessions` as Numeric.\n"},"sessions_remaining":{"type":"integer","nullable":true,"description":"For class-pack / punch-card style memberships — sessions the contact has left. Decrement client-side or via CRM sync when a class is attended. Segments commonly filter on `memberships.sessions_remaining <= 2` for \"sessions running low\" campaigns.\n"},"location_id":{"type":"string","nullable":true,"description":"External location identifier (e.g., a Mariana / CRM location ID). Not a v3 `loc_` prefixed ID."},"start_date":{"type":"string","format":"date-time","nullable":true},"begin_date":{"type":"string","format":"date-time","nullable":true,"description":"Alias of `start_date` in some source systems."},"renewal_date":{"type":"string","format":"date-time","nullable":true},"next_billing_date":{"type":"string","format":"date-time","nullable":true},"end_date":{"type":"string","format":"date-time","nullable":true},"expiration_date":{"type":"string","format":"date-time","nullable":true},"renewal_type":{"type":"string","nullable":true,"description":"How the plan renews. Common values: `monthly`, `annual`, `manual`."},"invoice_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"External invoice identifiers linked to this membership."}},"additionalProperties":true},"ConsentRecord":{"type":"object","required":["status"],"properties":{"status":{"$ref":"#/components/schemas/ConsentStatus"},"source":{"type":"string","description":"How consent was captured (`form_submission`, `import`, `api`, `admin_ui`, `double_opt_in_confirmed`).","nullable":true},"timestamp":{"$ref":"#/components/schemas/Timestamp","nullable":true},"source_ip":{"type":"string","nullable":true},"source_user_agent":{"type":"string","nullable":true}}},"ConsentStatus":{"type":"string","enum":["opted_in","opted_out","unknown","pending"],"description":"Consent state for a given channel. `opted_in` means the contact affirmatively consented (via form, import with proof, or explicit API call). `opted_out` means they revoked consent. `unknown` is the default for imported contacts without proof. `pending` means an opt-in confirmation was sent but not yet completed.\n"},"LocationId":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"},"UserId":{"type":"string","pattern":"^usr_[0-9A-HJKMNP-TV-Z]{26}$"},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"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":{"/contacts/{id}/opt_in":{"post":{"tags":["Contacts"],"operationId":"contactOptIn","summary":"Record affirmative consent for a channel.","description":"Compliance-of-record for marketing opt-in. Provide `source` and `timestamp` — the platform stores them on the contact's consent record and may need them for regulatory review. Transactional sends respect `opted_out` but do not require `opted_in`, so transactional intent alone is not a reason to opt someone in.\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/ContactOptIn"}}}},"responses":{"200":{"description":"Consent recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Record opt-out from a channel.

> Idempotent. \`channel: "all"\` opts out of SMS and email at once. Subsequent \`POST /notifications/\*\` sends on an opted-out channel return 422 \`compliance\_block\` whatever their \`category\`, as in the dashboard. Active flows do NOT un-enroll — they skip send-message nodes on opted-out channels. Inbound STOP replies are auto-recorded; call this only for external channels.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts: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":{"ContactOptOut":{"type":"object","required":["channel"],"description":"Record opt-out from a channel. Idempotent — repeated calls are no-ops.\nUse `channel: \"all\"` to opt out of all marketing channels simultaneously (transactional messages continue to send).\n","properties":{"channel":{"type":"string","enum":["sms","email","all"]},"reason":{"type":"string","description":"Free-form reason. Not shown to the contact."},"timestamp":{"$ref":"#/components/schemas/Timestamp"}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Contact":{"type":"object","description":"A person record. Central to almost every other resource in Gleantap.\nContacts have an internal id (`con_<24-hex>`) and optionally an external ID (`external_id`) you set from your own system. Both can be used to look up the record.\n","required":["id","object","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/ContactId"},"object":{"type":"string","const":"contact"},"external_id":{"type":"string","nullable":true,"description":"Your system's ID for this contact. Unique within the account. For contacts synced by an integration this is the member id the integration stores in `user_id` (returned when `external_id` itself is unset and `user_id` is not just the email/phone). `filter[external_id]` and `GET /v3/contacts/external_id:<x>` match either field, as string or integer."},"email":{"$ref":"#/components/schemas/Email","nullable":true},"phone":{"$ref":"#/components/schemas/PhoneE164","nullable":true,"description":"Stored the way every Gleantap writer stores it (formatPhone) — a `+` number is kept, a national number gets the account's country code (US/CA +1, GB +44, AU +61 with the trunk 0 dropped, NL, DK, LB, AE). Writes accept either form."},"first_name":{"type":"string","nullable":true,"maxLength":100},"last_name":{"type":"string","nullable":true,"maxLength":100},"date_of_birth":{"$ref":"#/components/schemas/Date","nullable":true,"description":"Stored as `personalinfo.dob` (date) + `personalinfo.birthday` (day of year), the pair birthday segments, campaigns and loyalty birthday rewards match on; `data.dob` is kept in step."},"locale":{"$ref":"#/components/schemas/Locale","nullable":true},"timezone":{"$ref":"#/components/schemas/Timezone","nullable":true},"tags":{"type":"array","items":{"$ref":"#/components/schemas/TagName"},"description":"All tags currently applied to this contact (`sales.tags`, the list the dashboard shows)."},"custom_fields":{"type":"object","additionalProperties":true,"description":"Account-defined custom fields. Schema is per-workroom (see `/v3/custom_fields`). Values are coerced to the declared type on write, as the dashboard CSV import does: date → stored date (a bare `YYYY-MM-DD` is midnight in the account timezone), number → integer/decimal, boolean → true/false. Dates are returned as ISO-8601 strings.\n"},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/ContactMembership"},"description":"The contact's memberships/plans. Segment engine reads `memberships.status` / `memberships.type` / `memberships.renewal_date` / etc. directly off this array. Populated by CRM syncs (Mariana etc.) or by direct API writes.\n"},"consent":{"type":"object","description":"Per-channel consent records. Server-enforced on all marketing sends.","properties":{"sms":{"$ref":"#/components/schemas/ConsentRecord"},"email":{"$ref":"#/components/schemas/ConsentRecord"}}},"primary_location_id":{"$ref":"#/components/schemas/LocationId","nullable":true,"description":"Not populated yet (no Location resource). Use `location` / `location_id`."},"location":{"type":"string","nullable":true,"description":"The contact's location/club name as the integration or CSV import recorded it (`accountinfo.location`, else `data.location` / `data.location_name`). Numeric on some accounts; always returned as a string. Same value `filter[location]` matches."},"location_id":{"type":"string","nullable":true,"description":"The integration's location id (`accountinfo.location_id`, else `data.location_id`)."},"member_status":{"type":"string","nullable":true,"description":"Membership/account status as synced (`accountinfo.status`), e.g. `active`, `inactive`, `cancelled`. Vocabulary is the integration's."},"owner_user_id":{"$ref":"#/components/schemas/UserId","nullable":true},"segments":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Segment IDs this contact is currently a member of. Eventually consistent (up to minutes of lag from an underlying data change)."},"pipelines":{"type":"array","description":"Pipelines and stages this contact currently belongs to.","items":{"type":"object","properties":{"pipeline_id":{"$ref":"#/components/schemas/PipelineId"},"stage_id":{"$ref":"#/components/schemas/StageId","nullable":true},"stage_name":{"type":"string","nullable":true},"status":{"type":"string"},"added_at":{"$ref":"#/components/schemas/Timestamp"},"last_updated_at":{"$ref":"#/components/schemas/Timestamp"}}}},"lifecycle_stage":{"type":"string","nullable":true,"description":"Stage label stored in `accountinfo.type`. The values in real data are `member`, `prospect`, `past` and `non-member`, plus raw labels integrations pass through in their own case (`Kid`, `Parent`, `Individual`, …). Not enforced; `filter[lifecycle_stage]` matches case-insensitively. Writing `member` (or `customer`) also sets `accountinfo.member: 1`; anything other than member/former sets `accountinfo.prospect: 1`.\n"},"last_seen_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp","description":"Last change by any writer — the later of v3's own stamp and the `last_updated_on` the integrations and dashboard maintain. `sort=updated_at` orders by `last_updated_on`."},"deleted_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Set if this contact was soft-deleted. Soft-deleted contacts are hidden from all list endpoints, the dashboard and every send by default; include `?filter[deleted]=true` to see them. Merged-away contacts also carry it."},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"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"},"Email":{"type":"string","format":"email"},"PhoneE164":{"type":"string","description":"E.164 international phone format.","pattern":"^\\+[1-9]\\d{1,14}$"},"Date":{"type":"string","format":"date","description":"Calendar date (no time), ISO 8601 `YYYY-MM-DD`."},"Locale":{"type":"string","description":"BCP 47 locale tag."},"Timezone":{"type":"string","description":"IANA timezone name."},"TagName":{"type":"string","description":"Tag name. Case-preserving, but case-insensitive on match. Whitespace preserved.","pattern":"^[^\\n\\r]{1,100}$"},"ContactMembership":{"type":"object","description":"A single membership/plan on a contact. Stored inline on `userdetails.memberships[]` (the segment DSL's `memberships.*` category queries this array via `$elemMatch`). Purchases live on events, but memberships live here because the segment engine needs cheap membership-status lookups without JOINing.\n","required":["id","name"],"properties":{"id":{"type":"string","description":"External identifier (from CRM / source system). Not a v3-prefixed ID."},"name":{"type":"string","description":"Plan name (e.g., \"Unlimited Monthly\", \"Class Pack — 10 sessions\")."},"type":{"type":"string","nullable":true,"description":"Optional plan type discriminator (e.g., \"monthly\", \"annual\", \"class_pack\")."},"status":{"type":"string","nullable":true,"description":"Current membership status. Common values: `active`, `on hold`, `cancelled`, `expired`, `pending cancel`. Free-form — call `GET /v3/segments/schema` to see `possible_values` observed in the current workroom. Mirrored to `member_status` on write.\n"},"member_status":{"type":"string","nullable":true,"description":"Segment-engine mirror of `status`. If you only set `status`, this is auto-populated (and vice versa) so segments querying either field find the contact."},"member_status_date":{"type":"string","format":"date-time","nullable":true,"description":"When the status was last set (used for tenure segments)."},"price":{"type":"number","nullable":true,"description":"Plan price in the account's currency."},"total_sessions":{"type":"integer","nullable":true,"description":"For class-pack / punch-card style memberships — the total number of sessions the plan grants at start (e.g., \"10-Class Pack\" → 10). Segment engine reads `memberships.total_sessions` as Numeric.\n"},"sessions_remaining":{"type":"integer","nullable":true,"description":"For class-pack / punch-card style memberships — sessions the contact has left. Decrement client-side or via CRM sync when a class is attended. Segments commonly filter on `memberships.sessions_remaining <= 2` for \"sessions running low\" campaigns.\n"},"location_id":{"type":"string","nullable":true,"description":"External location identifier (e.g., a Mariana / CRM location ID). Not a v3 `loc_` prefixed ID."},"start_date":{"type":"string","format":"date-time","nullable":true},"begin_date":{"type":"string","format":"date-time","nullable":true,"description":"Alias of `start_date` in some source systems."},"renewal_date":{"type":"string","format":"date-time","nullable":true},"next_billing_date":{"type":"string","format":"date-time","nullable":true},"end_date":{"type":"string","format":"date-time","nullable":true},"expiration_date":{"type":"string","format":"date-time","nullable":true},"renewal_type":{"type":"string","nullable":true,"description":"How the plan renews. Common values: `monthly`, `annual`, `manual`."},"invoice_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"External invoice identifiers linked to this membership."}},"additionalProperties":true},"ConsentRecord":{"type":"object","required":["status"],"properties":{"status":{"$ref":"#/components/schemas/ConsentStatus"},"source":{"type":"string","description":"How consent was captured (`form_submission`, `import`, `api`, `admin_ui`, `double_opt_in_confirmed`).","nullable":true},"timestamp":{"$ref":"#/components/schemas/Timestamp","nullable":true},"source_ip":{"type":"string","nullable":true},"source_user_agent":{"type":"string","nullable":true}}},"ConsentStatus":{"type":"string","enum":["opted_in","opted_out","unknown","pending"],"description":"Consent state for a given channel. `opted_in` means the contact affirmatively consented (via form, import with proof, or explicit API call). `opted_out` means they revoked consent. `unknown` is the default for imported contacts without proof. `pending` means an opt-in confirmation was sent but not yet completed.\n"},"LocationId":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"},"UserId":{"type":"string","pattern":"^usr_[0-9A-HJKMNP-TV-Z]{26}$"},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"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":{"/contacts/{id}/opt_out":{"post":{"tags":["Contacts"],"operationId":"contactOptOut","summary":"Record opt-out from a channel.","description":"Idempotent. `channel: \"all\"` opts out of SMS and email at once. Subsequent `POST /notifications/*` sends on an opted-out channel return 422 `compliance_block` whatever their `category`, as in the dashboard. Active flows do NOT un-enroll — they skip send-message nodes on opted-out channels. Inbound STOP replies are auto-recorded; call this only for external channels.\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/ContactOptOut"}}}},"responses":{"200":{"description":"Opt-out recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## List events for a contact.

> Paginated events for one contact, most recent first by \`occurred\_at\`. Equivalent to \`GET /v3/events?filter\[contact\_id]=...\` but cheaper (no join). Common filters: \`?filter\[name]=purchase.completed\`, \`?filter\[occurred\_at]\[gte]=...\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"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."},"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":{"/contacts/{id}/events":{"get":{"tags":["Contacts"],"operationId":"listContactEvents","summary":"List events for a contact.","description":"Paginated events for one contact, most recent first by `occurred_at`. Equivalent to `GET /v3/events?filter[contact_id]=...` but cheaper (no join). Common filters: `?filter[name]=purchase.completed`, `?filter[occurred_at][gte]=...`.\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"}}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## List the contact's unified activity feed (events + messages + appointments + tasks).

> Time-DESC merge across externalevents, inboundtext, inboundemails, pushmessagessms, pushmessagesemail, phonecalls, appointments, and tasks — filtered by this contact. Use this when you want a chronological narrative for a contact ("what has happened with X?") rather than one specific dimension. \`filter\[type]\` narrows to one or more of \`event\`, \`message\`, \`appointment\`, \`task\` (comma-separated). \`filter\[since]\` and \`filter\[until]\` are ISO datetimes. No cursor — the merge is bounded by \`limit\` (default 50, max 500); if you need more, narrow by \`type\` or \`since\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}},"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`."}}},"ContactActivity":{"type":"object","description":"One row in the merged activity feed returned by `GET /contacts/{id}/activity`. Same shape regardless of which source collection the row came from — `type` tells you what it is.\n","properties":{"id":{"type":"string","description":"Prefixed id of the source record (`evt_...`, `msg_...`, `apt_...`, `tsk_...`)."},"object":{"type":"string","enum":["activity"]},"type":{"type":"string","enum":["event","message","appointment","task"]},"title":{"type":"string","description":"One-line label meant for humans."},"detail":{"type":"string","description":"One-line detail — may include a truncated body/description."},"timestamp":{"$ref":"#/components/schemas/Timestamp"},"channel":{"type":"string","nullable":true,"enum":["sms","email","voice",null],"description":"Only set for `type=message`."},"direction":{"type":"string","nullable":true,"enum":["inbound","outbound",null],"description":"Only set for `type=message`."},"status":{"type":"string","nullable":true},"reference":{"type":"object","description":"Where to look for the full record.","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["event","message","appointment","task"]},"url":{"type":"string","description":"Relative v3 URL that resolves to the source resource."}}},"source_collection":{"type":"string","description":"Provenance — the underlying Mongo collection."}}},"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":{"/contacts/{id}/activity":{"get":{"tags":["Contacts"],"operationId":"listContactActivity","summary":"List the contact's unified activity feed (events + messages + appointments + tasks).","description":"Time-DESC merge across externalevents, inboundtext, inboundemails, pushmessagessms, pushmessagesemail, phonecalls, appointments, and tasks — filtered by this contact. Use this when you want a chronological narrative for a contact (\"what has happened with X?\") rather than one specific dimension. `filter[type]` narrows to one or more of `event`, `message`, `appointment`, `task` (comma-separated). `filter[since]` and `filter[until]` are ISO datetimes. No cursor — the merge is bounded by `limit` (default 50, max 500); if you need more, narrow by `type` or `since`.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/LimitParam"},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"type":"object","properties":{"type":{"type":"string","description":"One of `event`, `message`, `appointment`, `task` — or comma-separated list."},"since":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"}}}}],"responses":{"200":{"description":"Merged activity items, most recent first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContactActivity"}}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Bulk create/update/upsert/delete contacts.

> Up to 10,000 contacts per request. Runs inline and returns the finished \`job\` (status \`completed\`; per-row failures in \`errors\`). For <50 records use \`POST /v3/contacts\`; for CSV imports with per-row error visibility use \`POST /v3/imports\`. \`Idempotency-Key\` is required. Rate limit bucket: \`bulk\` (10 req/min default).\
> \
> \*\*Can delete in bulk.\*\* With \`operation: "delete"\` this removes every matched contact permanently.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts: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":{"ContactBulkOperation":{"type":"object","required":["operation","data"],"description":"Bulk contact operation. Max 10,000 records per request. Runs inline: the returned `job` is already `completed`, with per-row `errors`. There is no job-status endpoint to poll.\n","properties":{"operation":{"type":"string","enum":["upsert","create","update","delete"],"description":"- `upsert`: create if not found, update if found (see `match_on`).\n- `create`: always create; error on duplicate match.\n- `update`: only update; skip records that don't match.\n- `delete`: soft-delete records that match.\n"},"match_on":{"type":"string","enum":["email","phone","external_id","id"],"default":"email","description":"Field to use for finding existing records."},"data":{"type":"array","maxItems":10000,"items":{"$ref":"#/components/schemas/ContactCreate"}}}},"ContactCreate":{"type":"object","description":"Body for creating or upserting a contact.\n- If you pass an `email`, `phone`, or `external_id` that matches an existing contact in this account, the existing record is updated (upsert).\n- Provide `match_on` in the request to control which field is used for matching (default: `email` if provided, else `phone`, else `external_id`).\n- `consent` is optional but recommended for any contact that may receive marketing messages — sending to a contact without opted-in consent returns 422 `compliance_block`.\n","anyOf":[{"required":["email"]},{"required":["phone"]},{"required":["external_id"]},{"required":["match_on"]}],"properties":{"external_id":{"type":"string","maxLength":200},"email":{"$ref":"#/components/schemas/Email"},"phone":{"$ref":"#/components/schemas/PhoneE164"},"first_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":100},"date_of_birth":{"$ref":"#/components/schemas/Date"},"locale":{"$ref":"#/components/schemas/Locale"},"timezone":{"$ref":"#/components/schemas/Timezone"},"tags":{"type":"array","items":{"$ref":"#/components/schemas/TagName"}},"custom_fields":{"type":"object","additionalProperties":true},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/ContactMembership"},"description":"Optional. Set the contact's memberships/plans in one shot. Full replacement — pass the complete current set (this is how CRM syncs write). To bump a single membership use PATCH with the updated array.\n"},"consent":{"type":"object","properties":{"sms":{"$ref":"#/components/schemas/ConsentRecord"},"email":{"$ref":"#/components/schemas/ConsentRecord"}}},"primary_location_id":{"$ref":"#/components/schemas/LocationId"},"owner_user_id":{"$ref":"#/components/schemas/UserId"},"lifecycle_stage":{"type":"string","maxLength":50},"metadata":{"$ref":"#/components/schemas/Metadata"},"match_on":{"type":"string","enum":["email","phone","external_id","id","none"],"description":"Which field to use for upsert matching. Default heuristic: `email` if provided, else `phone`, else `external_id`. Set `none` to always create a new record (no upsert).\n"}}},"Email":{"type":"string","format":"email"},"PhoneE164":{"type":"string","description":"E.164 international phone format.","pattern":"^\\+[1-9]\\d{1,14}$"},"Date":{"type":"string","format":"date","description":"Calendar date (no time), ISO 8601 `YYYY-MM-DD`."},"Locale":{"type":"string","description":"BCP 47 locale tag."},"Timezone":{"type":"string","description":"IANA timezone name."},"TagName":{"type":"string","description":"Tag name. Case-preserving, but case-insensitive on match. Whitespace preserved.","pattern":"^[^\\n\\r]{1,100}$"},"ContactMembership":{"type":"object","description":"A single membership/plan on a contact. Stored inline on `userdetails.memberships[]` (the segment DSL's `memberships.*` category queries this array via `$elemMatch`). Purchases live on events, but memberships live here because the segment engine needs cheap membership-status lookups without JOINing.\n","required":["id","name"],"properties":{"id":{"type":"string","description":"External identifier (from CRM / source system). Not a v3-prefixed ID."},"name":{"type":"string","description":"Plan name (e.g., \"Unlimited Monthly\", \"Class Pack — 10 sessions\")."},"type":{"type":"string","nullable":true,"description":"Optional plan type discriminator (e.g., \"monthly\", \"annual\", \"class_pack\")."},"status":{"type":"string","nullable":true,"description":"Current membership status. Common values: `active`, `on hold`, `cancelled`, `expired`, `pending cancel`. Free-form — call `GET /v3/segments/schema` to see `possible_values` observed in the current workroom. Mirrored to `member_status` on write.\n"},"member_status":{"type":"string","nullable":true,"description":"Segment-engine mirror of `status`. If you only set `status`, this is auto-populated (and vice versa) so segments querying either field find the contact."},"member_status_date":{"type":"string","format":"date-time","nullable":true,"description":"When the status was last set (used for tenure segments)."},"price":{"type":"number","nullable":true,"description":"Plan price in the account's currency."},"total_sessions":{"type":"integer","nullable":true,"description":"For class-pack / punch-card style memberships — the total number of sessions the plan grants at start (e.g., \"10-Class Pack\" → 10). Segment engine reads `memberships.total_sessions` as Numeric.\n"},"sessions_remaining":{"type":"integer","nullable":true,"description":"For class-pack / punch-card style memberships — sessions the contact has left. Decrement client-side or via CRM sync when a class is attended. Segments commonly filter on `memberships.sessions_remaining <= 2` for \"sessions running low\" campaigns.\n"},"location_id":{"type":"string","nullable":true,"description":"External location identifier (e.g., a Mariana / CRM location ID). Not a v3 `loc_` prefixed ID."},"start_date":{"type":"string","format":"date-time","nullable":true},"begin_date":{"type":"string","format":"date-time","nullable":true,"description":"Alias of `start_date` in some source systems."},"renewal_date":{"type":"string","format":"date-time","nullable":true},"next_billing_date":{"type":"string","format":"date-time","nullable":true},"end_date":{"type":"string","format":"date-time","nullable":true},"expiration_date":{"type":"string","format":"date-time","nullable":true},"renewal_type":{"type":"string","nullable":true,"description":"How the plan renews. Common values: `monthly`, `annual`, `manual`."},"invoice_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"External invoice identifiers linked to this membership."}},"additionalProperties":true},"ConsentRecord":{"type":"object","required":["status"],"properties":{"status":{"$ref":"#/components/schemas/ConsentStatus"},"source":{"type":"string","description":"How consent was captured (`form_submission`, `import`, `api`, `admin_ui`, `double_opt_in_confirmed`).","nullable":true},"timestamp":{"$ref":"#/components/schemas/Timestamp","nullable":true},"source_ip":{"type":"string","nullable":true},"source_user_agent":{"type":"string","nullable":true}}},"ConsentStatus":{"type":"string","enum":["opted_in","opted_out","unknown","pending"],"description":"Consent state for a given channel. `opted_in` means the contact affirmatively consented (via form, import with proof, or explicit API call). `opted_out` means they revoked consent. `unknown` is the default for imported contacts without proof. `pending` means an opt-in confirmation was sent but not yet completed.\n"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"LocationId":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"},"UserId":{"type":"string","pattern":"^usr_[0-9A-HJKMNP-TV-Z]{26}$"},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"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}$"},"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"},"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":{"/contacts/bulk":{"post":{"tags":["Contacts"],"operationId":"bulkContacts","summary":"Bulk create/update/upsert/delete contacts.","description":"Up to 10,000 contacts per request. Runs inline and returns the finished `job` (status `completed`; per-row failures in `errors`). For <50 records use `POST /v3/contacts`; for CSV imports with per-row error visibility use `POST /v3/imports`. `Idempotency-Key` is required. Rate limit bucket: `bulk` (10 req/min default).\n\n**Can delete in bulk.** With `operation: \"delete\"` this removes every matched contact permanently.\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/ContactBulkOperation"}}}},"responses":{"202":{"description":"Job accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```

## Count contacts matching filters.

> Total count for the given filters. Accepts the same \`?filter\[...]\` params as \`GET /v3/contacts\`. For segment-scoped counts, \`GET /v3/segments/{id}\` returns \`size\` inline. Rate limit bucket: \`read\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts: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"}}}},"paths":{"/contacts/count":{"get":{"tags":["Contacts"],"operationId":"countContacts","summary":"Count contacts matching filters.","description":"Total count for the given filters. Accepts the same `?filter[...]` params as `GET /v3/contacts`. For segment-scoped counts, `GET /v3/segments/{id}` returns `size` inline. Rate limit bucket: `read`.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"name":"filter","in":"query","style":"deepObject","description":"Filterable fields. Anything outside this list is REJECTED, not ignored — a dropped filter would return the unfiltered total, which reads as an answer rather than as the mistake it is.\n\n`email` (case-insensitive), `external_id` (also matches the integration member id in `user_id`), `phone` (national numbers are formatted with the account's country code, as stored), `lifecycle_stage` (case-insensitive), `tags`, `deleted`, `created_at` (with `gte`/`gt`/`lte`/`lt`), `location` (exact, case-insensitive, matches numeric locations), `has_email`, `has_phone`, `subscribed_email`, `subscribed_sms`, `reachable_email`, `reachable_sms`, `consent.email.status`, `consent.sms.status` (`opted_out` or `opted_in`), `suppression` (`sms_unsubscribes`, `email_unsubscribes`, `email_bounces`, `sms_bounces`, `email_complaints`, `email_inactive`), `suppressed_email`, `suppressed_sms`.\n\nThe two `subscribed_*` filters are consent only: they read the opt-out flag, where an absent flag means subscribed — so `subscribed_email=false` finds contacts who actively opted out, not contacts with no preference recorded. A subscribed contact can still be undeliverable.\n\nThe two `reachable_*` filters are what a send would actually reach — the dashboard's email/SMS member counts and the send path's own checks: subscribed AND an address on file AND not suppressed as invalid (`reachable_email` excludes bounced, complained and inactive addresses — `invalid_email` 2/3/4; `reachable_sms` excludes failed numbers — `invalid_phone` 1). Use these to size an audience.\n\n`consent.<channel>.status=opted_out` is the same test as `subscribed_<channel>=false`. SMS opt-outs match the dashboard's SMS unsubscribe list (contacts unsubscribed by STOP replies, imports and integrations as well as through this API). To pull a complete list, page with `cursor` until `has_more` is false.\n","explode":true,"schema":{"type":"object","additionalProperties":{"type":"string"}}}],"responses":{"200":{"description":"The count.","content":{"application/json":{"schema":{"type":"object","required":["count"],"properties":{"object":{"type":"string","const":"count"},"count":{"type":"integer","minimum":0},"filter_snapshot":{"type":"object","description":"The filter set the count was computed against (for debugging)."}}}}}}}}}}}
```

## List notes on a contact.

> Notes are stored on \`userdetails.salesactivity\[]\` with \`action='noteadded'\` — the same feed the dashboard's activity tab reads. Ordered most-recent first.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts: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":{"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`."}}},"ContactNote":{"type":"object","properties":{"object":{"type":"string","const":"contact_note"},"body":{"type":"string","nullable":true},"added_by":{"type":"string","nullable":true,"description":"Staff ID (usr_...) or the literal `api_key` when created by an API-key call."},"added_by_email":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true}}},"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":{"/contacts/{id}/notes":{"get":{"tags":["Contacts"],"operationId":"listContactNotes","summary":"List notes on a contact.","description":"Notes are stored on `userdetails.salesactivity[]` with `action='noteadded'` — the same feed the dashboard's activity tab reads. Ordered most-recent first.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"List of notes (all-in-one; no pagination).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContactNote"}}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Add a note to a contact.

> Writes to \`userdetails.salesactivity\[]\`. \`added\_by\` is derived from the auth context — OAuth tokens carry a user\_id; API-key writes are tagged \`added\_by='api\_key'\` so the dashboard's activity feed can distinguish human vs machine notes.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts: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":{"ContactNoteCreate":{"type":"object","required":["note"],"properties":{"note":{"type":"string","minLength":1,"description":"The note text. (The legacy field name `body` is still accepted but deprecated — avoid it, as a request-body property literally named `body` collides with the HTTP request body in some generators.)"}}},"ContactNote":{"type":"object","properties":{"object":{"type":"string","const":"contact_note"},"body":{"type":"string","nullable":true},"added_by":{"type":"string","nullable":true,"description":"Staff ID (usr_...) or the literal `api_key` when created by an API-key call."},"added_by_email":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true}}},"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":{"/contacts/{id}/notes":{"post":{"tags":["Contacts"],"operationId":"addContactNote","summary":"Add a note to a contact.","description":"Writes to `userdetails.salesactivity[]`. `added_by` is derived from the auth context — OAuth tokens carry a user_id; API-key writes are tagged `added_by='api_key'` so the dashboard's activity feed can distinguish human vs machine notes.\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/ContactNoteCreate"}}}},"responses":{"201":{"description":"Note created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactNote"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## List staff assigned as responsible for a contact.

> Backed by \`userdetails.sales.responsible\[]\`. Also exposed as \`owner\_user\_ids\[]\` on the Contact resource.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts: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":{"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`."}}},"ContactResponsible":{"type":"object","properties":{"object":{"type":"string","const":"contact_responsible"},"user_id":{"$ref":"#/components/schemas/StaffId"},"email":{"type":"string","nullable":true}}},"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."},"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":{"/contacts/{id}/responsible":{"get":{"tags":["Contacts"],"operationId":"listContactResponsible","summary":"List staff assigned as responsible for a contact.","description":"Backed by `userdetails.sales.responsible[]`. Also exposed as `owner_user_ids[]` on the Contact resource.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"Assigned staff.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContactResponsible"}}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Assign a staff user to a contact.

> Idempotent — assigning an already-assigned user returns 200 with the same shape (no salesactivity entry emitted). New assignments push a \`responsible\_added\` entry to \`salesactivity\` for the dashboard's activity feed.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts: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":{"ContactResponsibleAdd":{"type":"object","required":["user_id"],"properties":{"user_id":{"$ref":"#/components/schemas/StaffId"}}},"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."},"ContactResponsible":{"type":"object","properties":{"object":{"type":"string","const":"contact_responsible"},"user_id":{"$ref":"#/components/schemas/StaffId"},"email":{"type":"string","nullable":true}}},"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":{"/contacts/{id}/responsible":{"post":{"tags":["Contacts"],"operationId":"addContactResponsible","summary":"Assign a staff user to a contact.","description":"Idempotent — assigning an already-assigned user returns 200 with the same shape (no salesactivity entry emitted). New assignments push a `responsible_added` entry to `salesactivity` for the dashboard's activity feed.\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/ContactResponsibleAdd"}}}},"responses":{"201":{"description":"Assignment created (or already existed).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactResponsible"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## Unassign a staff user from a contact.

> Idempotent — removing an unassigned user returns 204 without side effects. Removal logs a \`responsible\_removed\` salesactivity entry.\
> \
> \*\*Permanent.\*\* There is no undo and no trash to restore from. Anything that references the deleted record is affected too.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts: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":{"/contacts/{id}/responsible/{user_id}":{"delete":{"tags":["Contacts"],"operationId":"removeContactResponsible","summary":"Unassign a staff user from a contact.","description":"Idempotent — removing an unassigned user returns 204 without side effects. Removal logs a `responsible_removed` salesactivity entry.\n\n**Permanent.** There is no undo and no trash to restore from. 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":"Removed (or was already unassigned)."},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Add a contact to a static segment.

> Static segments only. Dynamic segments derive membership from their query — 422 \`wrong\_segment\_type\` is returned if the segment is dynamic. Mirror of \`POST /segments/{seg\_id}/contacts\` scoped to one contact.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts:write","segments: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":{"Segment":{"type":"object","description":"A named collection of contacts. Either static (hand-managed list) or dynamic (query-defined). Discriminated by the `type` field, which is immutable after creation.\n","required":["id","object","type","name","size","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/SegmentId"},"object":{"type":"string","const":"segment"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom that owns this segment. A flow can only be triggered by segments in its own workroom — compare against `Flow.workroom_id`."},"type":{"$ref":"#/components/schemas/SegmentType"},"name":{"type":"string","maxLength":200},"description":{"type":"string","nullable":true,"maxLength":2000},"query":{"$ref":"#/components/schemas/SegmentQuery","nullable":true,"description":"The segment's criteria. **Present on BOTH static and dynamic segments** — a \"static\" segment only means the engine doesn't auto-refresh membership; the criteria that defined the initial membership list is still stored and returned. When diagnosing \"why did this contact match this segment?\", read `query.segment_users` (+ `with_or_segment_users` and `exclude_segment_users`). May be `null` only on segments imported without criteria or created empty.\n"},"size":{"type":"integer","minimum":0,"description":"Current member count. Eventually consistent — up to minutes of lag on dynamic segments."},"email_count":{"type":"integer","minimum":0,"description":"Members with a non-empty, non-invalid email."},"phone_count":{"type":"integer","minimum":0,"description":"Members with a non-empty, non-invalid phone."},"last_evaluated_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"When this dynamic segment was last recomputed. Null on static."},"folder_id":{"$ref":"#/components/schemas/SegmentFolderId","nullable":true,"description":"The segment folder this segment currently belongs to, or `null` if unfoldered."},"segment_summary":{"type":"string","nullable":true,"description":"AI-generated narrative summary of the segment's criteria. Populated on demand via `POST /v3/segments/{id}/summary`."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"SegmentType":{"type":"string","enum":["static","dynamic"],"description":"`static` — hand-managed member list. Contacts are added/removed explicitly.\n`dynamic` — query-defined membership. Auto-evaluated; membership changes as contact data changes.\nImmutable after creation.\n"},"SegmentQuery":{"type":"object","description":"The segment criteria. **Present on BOTH `static` and `dynamic` segments** — \"static\" only means the engine doesn't auto-refresh membership; the criteria that defined the segment is still on the doc, and diagnostic tools (like \"why did this contact match this segment?\") MUST read it here.\n\nFull match logic:\n\n  (all `segment_users` ANDed together)\n  OR (all conditions in `with_or_segment_users[0]` ANDed)\n  OR (all conditions in `with_or_segment_users[1]` ANDed)\n  OR ...\n  MINUS contacts removed by `exclude_segment_users` (all ANDed) — self-match or shared-copy match per the account setting below\n\nHow `exclude_segment_users` matches depends on the account's `shared_contact_status` (surfaced as `shared_contacts_enabled` on `GET /segments/schema`). When shared contacts are ENABLED it is the dashboard's \"exclude shared contacts\" rule: a contact is removed when one of its linked copies in another workroom (`shared_contacts[]`) matches these conditions, NOT when the contact itself matches. When shared contacts are OFF it is a plain self-subtraction: the contact is removed when its OWN fields match. The exclusion can be any condition (attribute match, event done, tag, form filled — just the positive form of what to exclude). Either way the segment must keep at least one primary condition in `segment_users`; an exclude-only (or `with_or`-only) query is rejected. To exclude by a contact's own attributes regardless of the account setting, you can also use a negative condition in `segment_users` (e.g. `Is Not One Of`, `Has not Filled a Form`, `Does Not Contain`).\n\nConditions are stored in the exact tokens the dashboard's segment engine evaluates: friendly category names are rewritten on write (`Custom`/`attributes` → `Attributes`, `email_engagement` → `EmailCampaigns`, `salesattributes` → `sales`, …), and an absolute-date `<`/`>` on a Date field is stored as `Before`/`After` with an `MM-DD-YYYY` value. A retrieved segment therefore shows the stored (engine) form.\n\nThere is no additional `all/any/none` grouping. Express further OR via multi-value operators (`Is One Of`, `Segments` with an array).\n","properties":{"segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Base inclusion conditions. All ANDed. A contact must satisfy every one to be included via this group."},"with_or_segment_users":{"type":"array","description":"Alternate inclusion groups. Each inner array is a set of conditions that are ANDed together; the outer array is OR-joined with `segment_users` and each other inner array. Use this to build \"criteria A OR criteria B\" queries without touching the top-level `segment_users`.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"exclude_segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Exclusion conditions, ANDed. How they match depends on the account's `shared_contact_status` — shared-copy match when shared contacts are ON (a contact is removed when a linked copy in another workroom, `shared_contacts[]`, matches all of them), self-match when OFF (removed when the contact's own fields match all of them). Same condition shape as `segment_users`. Cannot stand alone — `segment_users` must be non-empty. See the match logic above."}}},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"SegmentFolderId":{"type":"string","pattern":"^sfd_[0-9a-fA-F]{24}$","description":"Segment folder ID."},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"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":{"/contacts/{id}/segments/{seg_id}":{"post":{"tags":["Contacts"],"operationId":"addContactToSegment","summary":"Add a contact to a static segment.","description":"Static segments only. Dynamic segments derive membership from their query — 422 `wrong_segment_type` is returned if the segment is dynamic. Mirror of `POST /segments/{seg_id}/contacts` scoped to one contact.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"Segment (updated size).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## Remove a contact from a static segment.

> Static segments only. For dynamic segments, edit the query. Marks membership as \`value: 0\` to preserve "was in" history for \`Is Not In Segment\` queries.\
> \
> \*\*Permanent.\*\* There is no undo and no trash to restore from. Anything that references the deleted record is affected too.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Contacts","description":"The central person record. Includes CRUD, merge, opt-in/opt-out, sub-resource listing, bulk upsert, and count."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["contacts:write","segments: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"}}}},"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"}}}}},"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":{"/contacts/{id}/segments/{seg_id}":{"delete":{"tags":["Contacts"],"operationId":"removeContactFromSegment","summary":"Remove a contact from a static segment.","description":"Static segments only. For dynamic segments, edit the query. Marks membership as `value: 0` to preserve \"was in\" history for `Is Not In Segment` queries.\n\n**Permanent.** There is no undo and no trash to restore from. 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":"Removed."},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```
