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

# Forms

Web forms that turn visitors into contacts. Form definitions include the field schema, custom CSS, tracking-code slots, and design settings. Public submissions are authenticated with a per-form `submission_token` (rotatable, with a 24-hour grace window) — the only unauthenticated write in the v3 API.

## GET /forms

> List forms for the account.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Forms","description":"Web forms — public capture surface for turning anonymous visitors into contacts. Definitions carry field schema, custom CSS, tracking-code slots (head/body/on-submit), and design settings. Public submission is authenticated by a per-form `submission_token` (rotatable with a 24h grace window) — the only unauthenticated write surface in v3."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["forms:manage"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}}},"schemas":{"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"Form":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/FormId"},"object":{"type":"string","enum":["form"]},"name":{"type":"string","description":"Internal name (dashboard label)."},"title":{"type":"string","description":"Rendered heading shown to submitters."},"subtitle":{"type":"string"},"slug":{"type":"string","description":"URL-safe identifier auto-generated from name if omitted."},"status":{"$ref":"#/components/schemas/FormStatus"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FormField"}},"action":{"type":"string","enum":["thankyou","redirect","message"],"description":"What happens after the submitter clicks submit."},"action_value":{"type":"string","description":"Companion to `action` — redirect URL, thank-you message text, etc."},"custom_css":{"type":"string","description":"Raw CSS injected into the form's `<style>` block on render. Legacy column: `additional_css`."},"tracking_codes":{"$ref":"#/components/schemas/FormTrackingCodes"},"design":{"$ref":"#/components/schemas/FormDesign"},"internal_notification":{"$ref":"#/components/schemas/FormInternalNotification"},"embed":{"$ref":"#/components/schemas/FormEmbed"},"submission_count":{"type":"integer","description":"Total submissions to date."},"submission_token_last4":{"type":"string","nullable":true,"description":"Last 4 chars of the current `submission_token`. Full plaintext is returned ONLY at publish and rotate."},"submission_token":{"type":"string","description":"Full plaintext submission_token. Returned ONLY as a one-shot on:\n  - `POST /forms` (create), when the request set `is_published: true` — a form created already-published gets a token minted immediately, the same as if it had been published separately right after.\n  - `POST /forms/{id}/publish` (first publish)\n  - `POST /forms/{id}/rotate_submission_token`\nStore it immediately; you cannot retrieve it again. If lost, rotate.\n"},"previous_submission_token_valid_until":{"type":"string","format":"date-time","description":"Rotate response only — timestamp at which the previously-issued token stops accepting submissions (default 24h grace)."},"last_submission_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true}}},"FormId":{"type":"string","pattern":"^fom_[0-9a-f]{24}$"},"FormStatus":{"type":"string","enum":["draft","published","archived"],"description":"Lifecycle. Newly-created forms start `draft`; `POST /forms/{id}/publish` moves them to `published` (and mints the `submission_token` on first publish). `DELETE /forms/{id}` is a genuine hard delete — the form is gone, not archived. `archived` is a legacy status that can still appear on forms deleted before this behavior shipped; it is never produced by any current action and has no path back to `draft`/`published`.\n"},"FormField":{"type":"object","description":"A single input in the form's field schema. Stored verbatim under the legacy `data` JSON blob so the dashboard editor round-trips it. Extra keys are preserved — don't rely on this being a closed shape.\n\n**Naming:** each field has a `name` (the key that shows up in submission `values`). Known names like `email`, `phone`, `first_name`, `last_name`, `dob` are auto-mapped to standard contact fields on submit; anything else lands in `contact.data.<name>` as a custom field.\n\n**Consent (`optin` / `opt_in`):** two field names are recognized on submission, scoped to `POST /forms/{id}/submissions` only:\n  - `optin` (no underscore) — a `checkbox-group` field with independent `sms`/`email` options (the shape every dashboard-built form actually uses). Submitted as an array of whichever options were checked, e.g. `[\"email\"]`, `[\"sms\",\"email\"]`, or `[]`. Each checked channel sets that channel's consent to `opted_in` — but only when its contact value was submitted too (`sms` checked without a phone, or `email` without an email, writes nothing). As in the dashboard's own submit, a form submission **never opts anyone out**: an unchecked channel, `[]`, or omitting `optin` leaves the contact's existing consent untouched. To record an opt-out use `POST /contacts/{id}/opt_out`.\n  - `opt_in` (underscore) — a single `checkbox`, kept for backward compatibility. Covers email only: checked (with an email submitted) sets `consent.email.status` to `opted_in`; unchecked writes nothing. If a submission somehow includes both, `optin` wins.\n\n  `optin` follows the dashboard's own form submit (opt-in only, gated on the contact value being present); `opt_in` is v3-only.\n","required":["type"],"properties":{"type":{"type":"string","enum":["text","textarea","number","date","select","checkbox","checkbox-group","radio","radio-group","autocomplete","hidden","file","signature","starRating","payment","card","button","header","paragraph"],"description":"Input type — must match a value the dashboard renderer knows how to draw.\n\n**Phone and email fields:** there is no dedicated `phone` or `email` type. Use `type: \"text\"` with `subtype: \"tel\"` (phone) or `subtype: \"email\"` — exactly what the dashboard's own field templates save. A literal top-level `phone`/`email` type is normalized automatically to `type: \"text\"` with the matching `subtype`, not rejected — the dashboard's edit-screen widget has no control registered for either raw type, so storing one as-is would make the field unrenderable there.\n\n**Input fields** (produce a submission value):\n  - `text`, `textarea`, `number`, `date`, `hidden` — standard scalar inputs. Use `subtype` on `text` for `tel`/`email`/`password`/etc.\n  - `select` — dropdown. Provide `values[]`. Add `multiple: true` for multi-select.\n  - `checkbox-group`, `radio-group` — group of options. Provide `values[]`. `inline: true` renders horizontally.\n  - `checkbox`, `radio` — single option (rarely used; prefer the -group variants).\n  - `autocomplete` — typeahead. Provide `values[]`. Set `requireValidOption: true` to force the user to pick from the list.\n  - `file` — file upload. Optional `subtype: \"file\"|\"image\"`, `multiple: true` for many files.\n  - `signature` — SVG signature capture. Stored as a base64 image string on submit.\n  - `starRating` — star widget. Optional `stars: 5` (default 5).\n  - `payment`, `card` — Stripe payment/card capture. Requires the workroom to have a payment integration configured.\n\n**Non-input fields** (layout only, no submission value):\n  - `header` — section heading text (from `label`).\n  - `paragraph` — static paragraph text (from `label`).\n  - `button` — a button. `subtype: \"submit\"` for the form submit button.\n"},"name":{"type":"string","description":"The key used in submission `values`. Also the storage key on the contact. Prefer human-readable snake_case (`first_name`, `company`). The dashboard auto-generates `<type>-<timestamp>-<n>` if you omit it — pass an explicit `name` to keep submissions readable.\n"},"label":{"type":"string","description":"Visible label rendered above the input."},"required":{"type":"boolean","default":false},"placeholder":{"type":"string","description":"Placeholder / helper text inside empty inputs."},"className":{"type":"string","description":"Extra CSS classes applied when rendered (e.g. `form-control`, `w-50`). Applied via the dashboard renderer."},"subtype":{"type":"string","description":"Fine-grained variant of the base `type`. Applies to a few types:\n  - `button` → `submit` | `button` | `reset`\n  - `file` → `file` | `image`\n  - `text` → `tel` (phone), `email`, `password`, or omitted for plain text\n"},"multiple":{"type":"boolean","default":false,"description":"For `select` (multi-select dropdown) and `file` (multi-file upload)."},"inline":{"type":"boolean","default":false,"description":"For `radio-group` / `checkbox-group` — render options horizontally instead of stacked."},"toggle":{"type":"boolean","default":false,"description":"For `checkbox-group` — render as toggle switches instead of checkboxes."},"other":{"type":"boolean","default":false,"description":"For `radio-group` / `checkbox-group` — render an extra \"Other\" free-text input alongside the group."},"requireValidOption":{"type":"boolean","default":false,"description":"For `autocomplete` — reject submissions where the value is not one of the listed `values[]`."},"style":{"type":"string","description":"For `button` — visual style. Values: `default`, `primary`, `success`, `warning`, `danger`."},"value":{"type":"string","description":"For `button`, `hidden`, and inputs with a default — the pre-filled or fixed value."},"stars":{"type":"integer","minimum":1,"maximum":10,"default":5,"description":"For `starRating` — number of stars to render."},"access":{"type":"boolean","default":false,"description":"Legacy access-control flag. Almost always `false`. Only set for internal / staff-only fields the dashboard hides from the public form.\n"},"values":{"type":"array","description":"Option list for `select`, `checkbox-group`, `radio-group`, and `autocomplete` fields. Each item has `label`, `value`, and optional `selected` (default option). This is the legacy shape — do NOT use the deprecated `options[]` field.\n","items":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string","description":"Text shown to the user."},"value":{"type":"string","description":"Value submitted when this option is chosen."},"selected":{"type":"boolean","default":false,"description":"Marks this option as the default (pre-selected)."}}}}}},"FormTrackingCodes":{"type":"object","description":"Third-party tracking snippets. Injected verbatim by the dashboard's embed\nrenderer — `head` before `</head>`, `body` immediately after `<body>`,\n`form_submission` on successful client-side submit (for GTM/Meta Pixel/GA4).\n","properties":{"head":{"type":"string","description":"Raw HTML/JS injected before `</head>`. Typical use: Meta Pixel init, GTM container."},"body":{"type":"string","description":"Raw HTML/JS injected after `<body>`. Typical use: GTM noscript iframe."},"form_submission":{"type":"string","description":"JS fired on successful submit. Typical use: `gtag(\"event\",\"generate_lead\")`."}}},"FormDesign":{"type":"object","description":"Visual settings honored by the dashboard's embed renderer.","properties":{"background_type":{"type":"string","enum":["solid","image"],"description":"Solid color or image background."},"background_color":{"type":"string","description":"CSS hex/rgb string."},"form_color":{"type":"string","description":"Form panel background."},"text_color":{"type":"string"},"border_color":{"type":"string"},"logo_url":{"type":"string","format":"uri","description":"Absolute URL to a logo image (typically S3)."},"background_image_url":{"type":"string","format":"uri","description":"Absolute URL to a background image."}}},"FormInternalNotification":{"type":"object","description":"Notify internal staff by email whenever the form is submitted. Configured\nin the dashboard under the form's gear icon → Workflows tab. Legacy Mongo\ncolumns: `enable_notification` (int 0/1), `notification_email` (comma-joined\nrecipient list). At submit time the notification is dispatched by the\nlegacy `handlePostFormAction` worker if `notification_email` is non-empty.\n","properties":{"enabled":{"type":"boolean","description":"Whether the internal notification is turned on."},"recipient_emails":{"type":"array","items":{"type":"string","format":"email"},"description":"Staff email addresses to notify. Stored as a comma-joined string in the legacy field."}}},"FormEmbed":{"type":"object","description":"Copy-paste embed helpers. Server-generated URLs point at the dashboard's\nexisting form-render endpoints (`/form/embedView/{id}` for the iframe-friendly\nfull page, `/form/embedHtmlView/{id}` for the bare HTML variant). Renderer\nbase URL is env-configured via `GLEANTAP_DASHBOARD_BASE_URL`.\n","properties":{"iframe_url":{"type":"string","format":"uri"},"html_url":{"type":"string","format":"uri"},"iframe_snippet":{"type":"string","description":"Ready-to-paste `<iframe>` tag."},"script_snippet":{"type":"string","description":"Ready-to-paste `<div>` + `<script>` tag pair — for embedded rendering."}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."}}},"paths":{"/forms":{"get":{"tags":["Forms"],"operationId":"listForms","summary":"List forms for the account.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"type":"object","properties":{"status":{"type":"string","enum":["draft","published","archived"]},"name":{"type":"string","description":"Case-insensitive substring match on `name`."}}}}],"responses":{"200":{"description":"A page of forms.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Form"}}}}]}}}}}}}}}
```

## Create a form.

> Newly-created forms default to \`draft\` unless \`is\_published: true\` is supplied, in which case the form is immediately live — viewable and accepting submissions through the dashboard embed — with no separate publish call needed. Either way, no \`submission\_token\` is minted at create time; that only happens on \`POST /forms/{id}/publish\` (or rotate), so v3's own \`POST /forms/{id}/submissions\` endpoint stays unusable until you publish, even for a form created with \`is\_published: true\`.\
> \
> Requires the name and which fields it should collect. 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":"Forms","description":"Web forms — public capture surface for turning anonymous visitors into contacts. Definitions carry field schema, custom CSS, tracking-code slots (head/body/on-submit), and design settings. Public submission is authenticated by a per-form `submission_token` (rotatable with a 24h grace window) — the only unauthenticated write surface in v3."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["forms:manage"]}],"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":{"FormCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"},"slug":{"type":"string","description":"Auto-generated from name if omitted."},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FormField"}},"action":{"type":"string","enum":["thankyou","redirect","message"],"description":"What happens after a successful submission. **Ask the user which of these they want — do not silently default without asking:**\n  - `thankyou` — a generic built-in thank-you screen. The default if `action` is omitted entirely; no `action_value` needed.\n  - `message` — a custom confirmation message. Provide `action_value` with the text; if you omit `action_value`, a generic default (\"Thank you for your submission!\") is used, so it's safe to fall back to this if the user doesn't specify wording — but still confirm they want a message, not a redirect.\n  - `redirect` — send the visitor to a URL after submitting. Provide `action_value` with the destination URL.\n"},"action_value":{"type":"string","description":"The confirmation message text (when `action: message`) or the redirect URL (when `action: redirect`). Unused when `action: thankyou`.\n\n**If the user chooses `redirect`, do not leave this blank — ask for the destination URL specifically.** Unlike `message` (which falls back to a friendly generic default when `action_value` is omitted), there is no default redirect URL; an empty `action_value` with `action: redirect` saves a form that redirects nowhere.\n"},"custom_css":{"type":"string"},"tracking_codes":{"$ref":"#/components/schemas/FormTrackingCodes"},"design":{"$ref":"#/components/schemas/FormDesign"},"internal_notification":{"$ref":"#/components/schemas/FormInternalNotification"},"is_published":{"type":"boolean","description":"Publish immediately if true. Defaults to false (draft)."}}},"FormField":{"type":"object","description":"A single input in the form's field schema. Stored verbatim under the legacy `data` JSON blob so the dashboard editor round-trips it. Extra keys are preserved — don't rely on this being a closed shape.\n\n**Naming:** each field has a `name` (the key that shows up in submission `values`). Known names like `email`, `phone`, `first_name`, `last_name`, `dob` are auto-mapped to standard contact fields on submit; anything else lands in `contact.data.<name>` as a custom field.\n\n**Consent (`optin` / `opt_in`):** two field names are recognized on submission, scoped to `POST /forms/{id}/submissions` only:\n  - `optin` (no underscore) — a `checkbox-group` field with independent `sms`/`email` options (the shape every dashboard-built form actually uses). Submitted as an array of whichever options were checked, e.g. `[\"email\"]`, `[\"sms\",\"email\"]`, or `[]`. Each checked channel sets that channel's consent to `opted_in` — but only when its contact value was submitted too (`sms` checked without a phone, or `email` without an email, writes nothing). As in the dashboard's own submit, a form submission **never opts anyone out**: an unchecked channel, `[]`, or omitting `optin` leaves the contact's existing consent untouched. To record an opt-out use `POST /contacts/{id}/opt_out`.\n  - `opt_in` (underscore) — a single `checkbox`, kept for backward compatibility. Covers email only: checked (with an email submitted) sets `consent.email.status` to `opted_in`; unchecked writes nothing. If a submission somehow includes both, `optin` wins.\n\n  `optin` follows the dashboard's own form submit (opt-in only, gated on the contact value being present); `opt_in` is v3-only.\n","required":["type"],"properties":{"type":{"type":"string","enum":["text","textarea","number","date","select","checkbox","checkbox-group","radio","radio-group","autocomplete","hidden","file","signature","starRating","payment","card","button","header","paragraph"],"description":"Input type — must match a value the dashboard renderer knows how to draw.\n\n**Phone and email fields:** there is no dedicated `phone` or `email` type. Use `type: \"text\"` with `subtype: \"tel\"` (phone) or `subtype: \"email\"` — exactly what the dashboard's own field templates save. A literal top-level `phone`/`email` type is normalized automatically to `type: \"text\"` with the matching `subtype`, not rejected — the dashboard's edit-screen widget has no control registered for either raw type, so storing one as-is would make the field unrenderable there.\n\n**Input fields** (produce a submission value):\n  - `text`, `textarea`, `number`, `date`, `hidden` — standard scalar inputs. Use `subtype` on `text` for `tel`/`email`/`password`/etc.\n  - `select` — dropdown. Provide `values[]`. Add `multiple: true` for multi-select.\n  - `checkbox-group`, `radio-group` — group of options. Provide `values[]`. `inline: true` renders horizontally.\n  - `checkbox`, `radio` — single option (rarely used; prefer the -group variants).\n  - `autocomplete` — typeahead. Provide `values[]`. Set `requireValidOption: true` to force the user to pick from the list.\n  - `file` — file upload. Optional `subtype: \"file\"|\"image\"`, `multiple: true` for many files.\n  - `signature` — SVG signature capture. Stored as a base64 image string on submit.\n  - `starRating` — star widget. Optional `stars: 5` (default 5).\n  - `payment`, `card` — Stripe payment/card capture. Requires the workroom to have a payment integration configured.\n\n**Non-input fields** (layout only, no submission value):\n  - `header` — section heading text (from `label`).\n  - `paragraph` — static paragraph text (from `label`).\n  - `button` — a button. `subtype: \"submit\"` for the form submit button.\n"},"name":{"type":"string","description":"The key used in submission `values`. Also the storage key on the contact. Prefer human-readable snake_case (`first_name`, `company`). The dashboard auto-generates `<type>-<timestamp>-<n>` if you omit it — pass an explicit `name` to keep submissions readable.\n"},"label":{"type":"string","description":"Visible label rendered above the input."},"required":{"type":"boolean","default":false},"placeholder":{"type":"string","description":"Placeholder / helper text inside empty inputs."},"className":{"type":"string","description":"Extra CSS classes applied when rendered (e.g. `form-control`, `w-50`). Applied via the dashboard renderer."},"subtype":{"type":"string","description":"Fine-grained variant of the base `type`. Applies to a few types:\n  - `button` → `submit` | `button` | `reset`\n  - `file` → `file` | `image`\n  - `text` → `tel` (phone), `email`, `password`, or omitted for plain text\n"},"multiple":{"type":"boolean","default":false,"description":"For `select` (multi-select dropdown) and `file` (multi-file upload)."},"inline":{"type":"boolean","default":false,"description":"For `radio-group` / `checkbox-group` — render options horizontally instead of stacked."},"toggle":{"type":"boolean","default":false,"description":"For `checkbox-group` — render as toggle switches instead of checkboxes."},"other":{"type":"boolean","default":false,"description":"For `radio-group` / `checkbox-group` — render an extra \"Other\" free-text input alongside the group."},"requireValidOption":{"type":"boolean","default":false,"description":"For `autocomplete` — reject submissions where the value is not one of the listed `values[]`."},"style":{"type":"string","description":"For `button` — visual style. Values: `default`, `primary`, `success`, `warning`, `danger`."},"value":{"type":"string","description":"For `button`, `hidden`, and inputs with a default — the pre-filled or fixed value."},"stars":{"type":"integer","minimum":1,"maximum":10,"default":5,"description":"For `starRating` — number of stars to render."},"access":{"type":"boolean","default":false,"description":"Legacy access-control flag. Almost always `false`. Only set for internal / staff-only fields the dashboard hides from the public form.\n"},"values":{"type":"array","description":"Option list for `select`, `checkbox-group`, `radio-group`, and `autocomplete` fields. Each item has `label`, `value`, and optional `selected` (default option). This is the legacy shape — do NOT use the deprecated `options[]` field.\n","items":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string","description":"Text shown to the user."},"value":{"type":"string","description":"Value submitted when this option is chosen."},"selected":{"type":"boolean","default":false,"description":"Marks this option as the default (pre-selected)."}}}}}},"FormTrackingCodes":{"type":"object","description":"Third-party tracking snippets. Injected verbatim by the dashboard's embed\nrenderer — `head` before `</head>`, `body` immediately after `<body>`,\n`form_submission` on successful client-side submit (for GTM/Meta Pixel/GA4).\n","properties":{"head":{"type":"string","description":"Raw HTML/JS injected before `</head>`. Typical use: Meta Pixel init, GTM container."},"body":{"type":"string","description":"Raw HTML/JS injected after `<body>`. Typical use: GTM noscript iframe."},"form_submission":{"type":"string","description":"JS fired on successful submit. Typical use: `gtag(\"event\",\"generate_lead\")`."}}},"FormDesign":{"type":"object","description":"Visual settings honored by the dashboard's embed renderer.","properties":{"background_type":{"type":"string","enum":["solid","image"],"description":"Solid color or image background."},"background_color":{"type":"string","description":"CSS hex/rgb string."},"form_color":{"type":"string","description":"Form panel background."},"text_color":{"type":"string"},"border_color":{"type":"string"},"logo_url":{"type":"string","format":"uri","description":"Absolute URL to a logo image (typically S3)."},"background_image_url":{"type":"string","format":"uri","description":"Absolute URL to a background image."}}},"FormInternalNotification":{"type":"object","description":"Notify internal staff by email whenever the form is submitted. Configured\nin the dashboard under the form's gear icon → Workflows tab. Legacy Mongo\ncolumns: `enable_notification` (int 0/1), `notification_email` (comma-joined\nrecipient list). At submit time the notification is dispatched by the\nlegacy `handlePostFormAction` worker if `notification_email` is non-empty.\n","properties":{"enabled":{"type":"boolean","description":"Whether the internal notification is turned on."},"recipient_emails":{"type":"array","items":{"type":"string","format":"email"},"description":"Staff email addresses to notify. Stored as a comma-joined string in the legacy field."}}},"Form":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/FormId"},"object":{"type":"string","enum":["form"]},"name":{"type":"string","description":"Internal name (dashboard label)."},"title":{"type":"string","description":"Rendered heading shown to submitters."},"subtitle":{"type":"string"},"slug":{"type":"string","description":"URL-safe identifier auto-generated from name if omitted."},"status":{"$ref":"#/components/schemas/FormStatus"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FormField"}},"action":{"type":"string","enum":["thankyou","redirect","message"],"description":"What happens after the submitter clicks submit."},"action_value":{"type":"string","description":"Companion to `action` — redirect URL, thank-you message text, etc."},"custom_css":{"type":"string","description":"Raw CSS injected into the form's `<style>` block on render. Legacy column: `additional_css`."},"tracking_codes":{"$ref":"#/components/schemas/FormTrackingCodes"},"design":{"$ref":"#/components/schemas/FormDesign"},"internal_notification":{"$ref":"#/components/schemas/FormInternalNotification"},"embed":{"$ref":"#/components/schemas/FormEmbed"},"submission_count":{"type":"integer","description":"Total submissions to date."},"submission_token_last4":{"type":"string","nullable":true,"description":"Last 4 chars of the current `submission_token`. Full plaintext is returned ONLY at publish and rotate."},"submission_token":{"type":"string","description":"Full plaintext submission_token. Returned ONLY as a one-shot on:\n  - `POST /forms` (create), when the request set `is_published: true` — a form created already-published gets a token minted immediately, the same as if it had been published separately right after.\n  - `POST /forms/{id}/publish` (first publish)\n  - `POST /forms/{id}/rotate_submission_token`\nStore it immediately; you cannot retrieve it again. If lost, rotate.\n"},"previous_submission_token_valid_until":{"type":"string","format":"date-time","description":"Rotate response only — timestamp at which the previously-issued token stops accepting submissions (default 24h grace)."},"last_submission_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true}}},"FormId":{"type":"string","pattern":"^fom_[0-9a-f]{24}$"},"FormStatus":{"type":"string","enum":["draft","published","archived"],"description":"Lifecycle. Newly-created forms start `draft`; `POST /forms/{id}/publish` moves them to `published` (and mints the `submission_token` on first publish). `DELETE /forms/{id}` is a genuine hard delete — the form is gone, not archived. `archived` is a legacy status that can still appear on forms deleted before this behavior shipped; it is never produced by any current action and has no path back to `draft`/`published`.\n"},"FormEmbed":{"type":"object","description":"Copy-paste embed helpers. Server-generated URLs point at the dashboard's\nexisting form-render endpoints (`/form/embedView/{id}` for the iframe-friendly\nfull page, `/form/embedHtmlView/{id}` for the bare HTML variant). Renderer\nbase URL is env-configured via `GLEANTAP_DASHBOARD_BASE_URL`.\n","properties":{"iframe_url":{"type":"string","format":"uri"},"html_url":{"type":"string","format":"uri"},"iframe_snippet":{"type":"string","description":"Ready-to-paste `<iframe>` tag."},"script_snippet":{"type":"string","description":"Ready-to-paste `<div>` + `<script>` tag pair — for embedded rendering."}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"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":{"/forms":{"post":{"tags":["Forms"],"operationId":"createForm","summary":"Create a form.","description":"Newly-created forms default to `draft` unless `is_published: true` is supplied, in which case the form is immediately live — viewable and accepting submissions through the dashboard embed — with no separate publish call needed. Either way, no `submission_token` is minted at create time; that only happens on `POST /forms/{id}/publish` (or rotate), so v3's own `POST /forms/{id}/submissions` endpoint stays unusable until you publish, even for a form created with `is_published: true`.\n\nRequires the name and which fields it should collect. 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/FormCreate"}}}},"responses":{"201":{"description":"Form created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Form"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## Retrieve a form.

> One form with its full definition: the fields it collects, what happens on submit (a confirmation message or a redirect), its publish state, and its hosted URL once published. Use it to see what a form asks for before directing people to it, or to check why submissions are not arriving.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Forms","description":"Web forms — public capture surface for turning anonymous visitors into contacts. Definitions carry field schema, custom CSS, tracking-code slots (head/body/on-submit), and design settings. Public submission is authenticated by a per-form `submission_token` (rotatable with a 24h grace window) — the only unauthenticated write surface in v3."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["forms:manage"]}],"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":{"Form":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/FormId"},"object":{"type":"string","enum":["form"]},"name":{"type":"string","description":"Internal name (dashboard label)."},"title":{"type":"string","description":"Rendered heading shown to submitters."},"subtitle":{"type":"string"},"slug":{"type":"string","description":"URL-safe identifier auto-generated from name if omitted."},"status":{"$ref":"#/components/schemas/FormStatus"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FormField"}},"action":{"type":"string","enum":["thankyou","redirect","message"],"description":"What happens after the submitter clicks submit."},"action_value":{"type":"string","description":"Companion to `action` — redirect URL, thank-you message text, etc."},"custom_css":{"type":"string","description":"Raw CSS injected into the form's `<style>` block on render. Legacy column: `additional_css`."},"tracking_codes":{"$ref":"#/components/schemas/FormTrackingCodes"},"design":{"$ref":"#/components/schemas/FormDesign"},"internal_notification":{"$ref":"#/components/schemas/FormInternalNotification"},"embed":{"$ref":"#/components/schemas/FormEmbed"},"submission_count":{"type":"integer","description":"Total submissions to date."},"submission_token_last4":{"type":"string","nullable":true,"description":"Last 4 chars of the current `submission_token`. Full plaintext is returned ONLY at publish and rotate."},"submission_token":{"type":"string","description":"Full plaintext submission_token. Returned ONLY as a one-shot on:\n  - `POST /forms` (create), when the request set `is_published: true` — a form created already-published gets a token minted immediately, the same as if it had been published separately right after.\n  - `POST /forms/{id}/publish` (first publish)\n  - `POST /forms/{id}/rotate_submission_token`\nStore it immediately; you cannot retrieve it again. If lost, rotate.\n"},"previous_submission_token_valid_until":{"type":"string","format":"date-time","description":"Rotate response only — timestamp at which the previously-issued token stops accepting submissions (default 24h grace)."},"last_submission_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true}}},"FormId":{"type":"string","pattern":"^fom_[0-9a-f]{24}$"},"FormStatus":{"type":"string","enum":["draft","published","archived"],"description":"Lifecycle. Newly-created forms start `draft`; `POST /forms/{id}/publish` moves them to `published` (and mints the `submission_token` on first publish). `DELETE /forms/{id}` is a genuine hard delete — the form is gone, not archived. `archived` is a legacy status that can still appear on forms deleted before this behavior shipped; it is never produced by any current action and has no path back to `draft`/`published`.\n"},"FormField":{"type":"object","description":"A single input in the form's field schema. Stored verbatim under the legacy `data` JSON blob so the dashboard editor round-trips it. Extra keys are preserved — don't rely on this being a closed shape.\n\n**Naming:** each field has a `name` (the key that shows up in submission `values`). Known names like `email`, `phone`, `first_name`, `last_name`, `dob` are auto-mapped to standard contact fields on submit; anything else lands in `contact.data.<name>` as a custom field.\n\n**Consent (`optin` / `opt_in`):** two field names are recognized on submission, scoped to `POST /forms/{id}/submissions` only:\n  - `optin` (no underscore) — a `checkbox-group` field with independent `sms`/`email` options (the shape every dashboard-built form actually uses). Submitted as an array of whichever options were checked, e.g. `[\"email\"]`, `[\"sms\",\"email\"]`, or `[]`. Each checked channel sets that channel's consent to `opted_in` — but only when its contact value was submitted too (`sms` checked without a phone, or `email` without an email, writes nothing). As in the dashboard's own submit, a form submission **never opts anyone out**: an unchecked channel, `[]`, or omitting `optin` leaves the contact's existing consent untouched. To record an opt-out use `POST /contacts/{id}/opt_out`.\n  - `opt_in` (underscore) — a single `checkbox`, kept for backward compatibility. Covers email only: checked (with an email submitted) sets `consent.email.status` to `opted_in`; unchecked writes nothing. If a submission somehow includes both, `optin` wins.\n\n  `optin` follows the dashboard's own form submit (opt-in only, gated on the contact value being present); `opt_in` is v3-only.\n","required":["type"],"properties":{"type":{"type":"string","enum":["text","textarea","number","date","select","checkbox","checkbox-group","radio","radio-group","autocomplete","hidden","file","signature","starRating","payment","card","button","header","paragraph"],"description":"Input type — must match a value the dashboard renderer knows how to draw.\n\n**Phone and email fields:** there is no dedicated `phone` or `email` type. Use `type: \"text\"` with `subtype: \"tel\"` (phone) or `subtype: \"email\"` — exactly what the dashboard's own field templates save. A literal top-level `phone`/`email` type is normalized automatically to `type: \"text\"` with the matching `subtype`, not rejected — the dashboard's edit-screen widget has no control registered for either raw type, so storing one as-is would make the field unrenderable there.\n\n**Input fields** (produce a submission value):\n  - `text`, `textarea`, `number`, `date`, `hidden` — standard scalar inputs. Use `subtype` on `text` for `tel`/`email`/`password`/etc.\n  - `select` — dropdown. Provide `values[]`. Add `multiple: true` for multi-select.\n  - `checkbox-group`, `radio-group` — group of options. Provide `values[]`. `inline: true` renders horizontally.\n  - `checkbox`, `radio` — single option (rarely used; prefer the -group variants).\n  - `autocomplete` — typeahead. Provide `values[]`. Set `requireValidOption: true` to force the user to pick from the list.\n  - `file` — file upload. Optional `subtype: \"file\"|\"image\"`, `multiple: true` for many files.\n  - `signature` — SVG signature capture. Stored as a base64 image string on submit.\n  - `starRating` — star widget. Optional `stars: 5` (default 5).\n  - `payment`, `card` — Stripe payment/card capture. Requires the workroom to have a payment integration configured.\n\n**Non-input fields** (layout only, no submission value):\n  - `header` — section heading text (from `label`).\n  - `paragraph` — static paragraph text (from `label`).\n  - `button` — a button. `subtype: \"submit\"` for the form submit button.\n"},"name":{"type":"string","description":"The key used in submission `values`. Also the storage key on the contact. Prefer human-readable snake_case (`first_name`, `company`). The dashboard auto-generates `<type>-<timestamp>-<n>` if you omit it — pass an explicit `name` to keep submissions readable.\n"},"label":{"type":"string","description":"Visible label rendered above the input."},"required":{"type":"boolean","default":false},"placeholder":{"type":"string","description":"Placeholder / helper text inside empty inputs."},"className":{"type":"string","description":"Extra CSS classes applied when rendered (e.g. `form-control`, `w-50`). Applied via the dashboard renderer."},"subtype":{"type":"string","description":"Fine-grained variant of the base `type`. Applies to a few types:\n  - `button` → `submit` | `button` | `reset`\n  - `file` → `file` | `image`\n  - `text` → `tel` (phone), `email`, `password`, or omitted for plain text\n"},"multiple":{"type":"boolean","default":false,"description":"For `select` (multi-select dropdown) and `file` (multi-file upload)."},"inline":{"type":"boolean","default":false,"description":"For `radio-group` / `checkbox-group` — render options horizontally instead of stacked."},"toggle":{"type":"boolean","default":false,"description":"For `checkbox-group` — render as toggle switches instead of checkboxes."},"other":{"type":"boolean","default":false,"description":"For `radio-group` / `checkbox-group` — render an extra \"Other\" free-text input alongside the group."},"requireValidOption":{"type":"boolean","default":false,"description":"For `autocomplete` — reject submissions where the value is not one of the listed `values[]`."},"style":{"type":"string","description":"For `button` — visual style. Values: `default`, `primary`, `success`, `warning`, `danger`."},"value":{"type":"string","description":"For `button`, `hidden`, and inputs with a default — the pre-filled or fixed value."},"stars":{"type":"integer","minimum":1,"maximum":10,"default":5,"description":"For `starRating` — number of stars to render."},"access":{"type":"boolean","default":false,"description":"Legacy access-control flag. Almost always `false`. Only set for internal / staff-only fields the dashboard hides from the public form.\n"},"values":{"type":"array","description":"Option list for `select`, `checkbox-group`, `radio-group`, and `autocomplete` fields. Each item has `label`, `value`, and optional `selected` (default option). This is the legacy shape — do NOT use the deprecated `options[]` field.\n","items":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string","description":"Text shown to the user."},"value":{"type":"string","description":"Value submitted when this option is chosen."},"selected":{"type":"boolean","default":false,"description":"Marks this option as the default (pre-selected)."}}}}}},"FormTrackingCodes":{"type":"object","description":"Third-party tracking snippets. Injected verbatim by the dashboard's embed\nrenderer — `head` before `</head>`, `body` immediately after `<body>`,\n`form_submission` on successful client-side submit (for GTM/Meta Pixel/GA4).\n","properties":{"head":{"type":"string","description":"Raw HTML/JS injected before `</head>`. Typical use: Meta Pixel init, GTM container."},"body":{"type":"string","description":"Raw HTML/JS injected after `<body>`. Typical use: GTM noscript iframe."},"form_submission":{"type":"string","description":"JS fired on successful submit. Typical use: `gtag(\"event\",\"generate_lead\")`."}}},"FormDesign":{"type":"object","description":"Visual settings honored by the dashboard's embed renderer.","properties":{"background_type":{"type":"string","enum":["solid","image"],"description":"Solid color or image background."},"background_color":{"type":"string","description":"CSS hex/rgb string."},"form_color":{"type":"string","description":"Form panel background."},"text_color":{"type":"string"},"border_color":{"type":"string"},"logo_url":{"type":"string","format":"uri","description":"Absolute URL to a logo image (typically S3)."},"background_image_url":{"type":"string","format":"uri","description":"Absolute URL to a background image."}}},"FormInternalNotification":{"type":"object","description":"Notify internal staff by email whenever the form is submitted. Configured\nin the dashboard under the form's gear icon → Workflows tab. Legacy Mongo\ncolumns: `enable_notification` (int 0/1), `notification_email` (comma-joined\nrecipient list). At submit time the notification is dispatched by the\nlegacy `handlePostFormAction` worker if `notification_email` is non-empty.\n","properties":{"enabled":{"type":"boolean","description":"Whether the internal notification is turned on."},"recipient_emails":{"type":"array","items":{"type":"string","format":"email"},"description":"Staff email addresses to notify. Stored as a comma-joined string in the legacy field."}}},"FormEmbed":{"type":"object","description":"Copy-paste embed helpers. Server-generated URLs point at the dashboard's\nexisting form-render endpoints (`/form/embedView/{id}` for the iframe-friendly\nfull page, `/form/embedHtmlView/{id}` for the bare HTML variant). Renderer\nbase URL is env-configured via `GLEANTAP_DASHBOARD_BASE_URL`.\n","properties":{"iframe_url":{"type":"string","format":"uri"},"html_url":{"type":"string","format":"uri"},"iframe_snippet":{"type":"string","description":"Ready-to-paste `<iframe>` tag."},"script_snippet":{"type":"string","description":"Ready-to-paste `<div>` + `<script>` tag pair — for embedded rendering."}}},"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":{"/forms/{id}":{"get":{"tags":["Forms"],"operationId":"retrieveForm","summary":"Retrieve a form.","description":"One form with its full definition: the fields it collects, what happens on submit (a confirmation message or a redirect), its publish state, and its hosted URL once published. Use it to see what a form asks for before directing people to it, or to check why submissions are not arriving.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"Form.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Form"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Update a form.

> Partial patch. \`tracking\_codes\` and \`design\` are merged per-key — supply only the values to change.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Forms","description":"Web forms — public capture surface for turning anonymous visitors into contacts. Definitions carry field schema, custom CSS, tracking-code slots (head/body/on-submit), and design settings. Public submission is authenticated by a per-form `submission_token` (rotatable with a 24h grace window) — the only unauthenticated write surface in v3."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["forms:manage"]}],"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":{"FormUpdate":{"type":"object","description":"PATCH — supply only the fields to change. Partial `tracking_codes` and `design` are merged.","properties":{"name":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"},"slug":{"type":"string"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FormField"}},"action":{"type":"string","enum":["thankyou","redirect","message"]},"action_value":{"type":"string"},"custom_css":{"type":"string"},"tracking_codes":{"$ref":"#/components/schemas/FormTrackingCodes"},"design":{"$ref":"#/components/schemas/FormDesign"},"internal_notification":{"$ref":"#/components/schemas/FormInternalNotification"}}},"FormField":{"type":"object","description":"A single input in the form's field schema. Stored verbatim under the legacy `data` JSON blob so the dashboard editor round-trips it. Extra keys are preserved — don't rely on this being a closed shape.\n\n**Naming:** each field has a `name` (the key that shows up in submission `values`). Known names like `email`, `phone`, `first_name`, `last_name`, `dob` are auto-mapped to standard contact fields on submit; anything else lands in `contact.data.<name>` as a custom field.\n\n**Consent (`optin` / `opt_in`):** two field names are recognized on submission, scoped to `POST /forms/{id}/submissions` only:\n  - `optin` (no underscore) — a `checkbox-group` field with independent `sms`/`email` options (the shape every dashboard-built form actually uses). Submitted as an array of whichever options were checked, e.g. `[\"email\"]`, `[\"sms\",\"email\"]`, or `[]`. Each checked channel sets that channel's consent to `opted_in` — but only when its contact value was submitted too (`sms` checked without a phone, or `email` without an email, writes nothing). As in the dashboard's own submit, a form submission **never opts anyone out**: an unchecked channel, `[]`, or omitting `optin` leaves the contact's existing consent untouched. To record an opt-out use `POST /contacts/{id}/opt_out`.\n  - `opt_in` (underscore) — a single `checkbox`, kept for backward compatibility. Covers email only: checked (with an email submitted) sets `consent.email.status` to `opted_in`; unchecked writes nothing. If a submission somehow includes both, `optin` wins.\n\n  `optin` follows the dashboard's own form submit (opt-in only, gated on the contact value being present); `opt_in` is v3-only.\n","required":["type"],"properties":{"type":{"type":"string","enum":["text","textarea","number","date","select","checkbox","checkbox-group","radio","radio-group","autocomplete","hidden","file","signature","starRating","payment","card","button","header","paragraph"],"description":"Input type — must match a value the dashboard renderer knows how to draw.\n\n**Phone and email fields:** there is no dedicated `phone` or `email` type. Use `type: \"text\"` with `subtype: \"tel\"` (phone) or `subtype: \"email\"` — exactly what the dashboard's own field templates save. A literal top-level `phone`/`email` type is normalized automatically to `type: \"text\"` with the matching `subtype`, not rejected — the dashboard's edit-screen widget has no control registered for either raw type, so storing one as-is would make the field unrenderable there.\n\n**Input fields** (produce a submission value):\n  - `text`, `textarea`, `number`, `date`, `hidden` — standard scalar inputs. Use `subtype` on `text` for `tel`/`email`/`password`/etc.\n  - `select` — dropdown. Provide `values[]`. Add `multiple: true` for multi-select.\n  - `checkbox-group`, `radio-group` — group of options. Provide `values[]`. `inline: true` renders horizontally.\n  - `checkbox`, `radio` — single option (rarely used; prefer the -group variants).\n  - `autocomplete` — typeahead. Provide `values[]`. Set `requireValidOption: true` to force the user to pick from the list.\n  - `file` — file upload. Optional `subtype: \"file\"|\"image\"`, `multiple: true` for many files.\n  - `signature` — SVG signature capture. Stored as a base64 image string on submit.\n  - `starRating` — star widget. Optional `stars: 5` (default 5).\n  - `payment`, `card` — Stripe payment/card capture. Requires the workroom to have a payment integration configured.\n\n**Non-input fields** (layout only, no submission value):\n  - `header` — section heading text (from `label`).\n  - `paragraph` — static paragraph text (from `label`).\n  - `button` — a button. `subtype: \"submit\"` for the form submit button.\n"},"name":{"type":"string","description":"The key used in submission `values`. Also the storage key on the contact. Prefer human-readable snake_case (`first_name`, `company`). The dashboard auto-generates `<type>-<timestamp>-<n>` if you omit it — pass an explicit `name` to keep submissions readable.\n"},"label":{"type":"string","description":"Visible label rendered above the input."},"required":{"type":"boolean","default":false},"placeholder":{"type":"string","description":"Placeholder / helper text inside empty inputs."},"className":{"type":"string","description":"Extra CSS classes applied when rendered (e.g. `form-control`, `w-50`). Applied via the dashboard renderer."},"subtype":{"type":"string","description":"Fine-grained variant of the base `type`. Applies to a few types:\n  - `button` → `submit` | `button` | `reset`\n  - `file` → `file` | `image`\n  - `text` → `tel` (phone), `email`, `password`, or omitted for plain text\n"},"multiple":{"type":"boolean","default":false,"description":"For `select` (multi-select dropdown) and `file` (multi-file upload)."},"inline":{"type":"boolean","default":false,"description":"For `radio-group` / `checkbox-group` — render options horizontally instead of stacked."},"toggle":{"type":"boolean","default":false,"description":"For `checkbox-group` — render as toggle switches instead of checkboxes."},"other":{"type":"boolean","default":false,"description":"For `radio-group` / `checkbox-group` — render an extra \"Other\" free-text input alongside the group."},"requireValidOption":{"type":"boolean","default":false,"description":"For `autocomplete` — reject submissions where the value is not one of the listed `values[]`."},"style":{"type":"string","description":"For `button` — visual style. Values: `default`, `primary`, `success`, `warning`, `danger`."},"value":{"type":"string","description":"For `button`, `hidden`, and inputs with a default — the pre-filled or fixed value."},"stars":{"type":"integer","minimum":1,"maximum":10,"default":5,"description":"For `starRating` — number of stars to render."},"access":{"type":"boolean","default":false,"description":"Legacy access-control flag. Almost always `false`. Only set for internal / staff-only fields the dashboard hides from the public form.\n"},"values":{"type":"array","description":"Option list for `select`, `checkbox-group`, `radio-group`, and `autocomplete` fields. Each item has `label`, `value`, and optional `selected` (default option). This is the legacy shape — do NOT use the deprecated `options[]` field.\n","items":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string","description":"Text shown to the user."},"value":{"type":"string","description":"Value submitted when this option is chosen."},"selected":{"type":"boolean","default":false,"description":"Marks this option as the default (pre-selected)."}}}}}},"FormTrackingCodes":{"type":"object","description":"Third-party tracking snippets. Injected verbatim by the dashboard's embed\nrenderer — `head` before `</head>`, `body` immediately after `<body>`,\n`form_submission` on successful client-side submit (for GTM/Meta Pixel/GA4).\n","properties":{"head":{"type":"string","description":"Raw HTML/JS injected before `</head>`. Typical use: Meta Pixel init, GTM container."},"body":{"type":"string","description":"Raw HTML/JS injected after `<body>`. Typical use: GTM noscript iframe."},"form_submission":{"type":"string","description":"JS fired on successful submit. Typical use: `gtag(\"event\",\"generate_lead\")`."}}},"FormDesign":{"type":"object","description":"Visual settings honored by the dashboard's embed renderer.","properties":{"background_type":{"type":"string","enum":["solid","image"],"description":"Solid color or image background."},"background_color":{"type":"string","description":"CSS hex/rgb string."},"form_color":{"type":"string","description":"Form panel background."},"text_color":{"type":"string"},"border_color":{"type":"string"},"logo_url":{"type":"string","format":"uri","description":"Absolute URL to a logo image (typically S3)."},"background_image_url":{"type":"string","format":"uri","description":"Absolute URL to a background image."}}},"FormInternalNotification":{"type":"object","description":"Notify internal staff by email whenever the form is submitted. Configured\nin the dashboard under the form's gear icon → Workflows tab. Legacy Mongo\ncolumns: `enable_notification` (int 0/1), `notification_email` (comma-joined\nrecipient list). At submit time the notification is dispatched by the\nlegacy `handlePostFormAction` worker if `notification_email` is non-empty.\n","properties":{"enabled":{"type":"boolean","description":"Whether the internal notification is turned on."},"recipient_emails":{"type":"array","items":{"type":"string","format":"email"},"description":"Staff email addresses to notify. Stored as a comma-joined string in the legacy field."}}},"Form":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/FormId"},"object":{"type":"string","enum":["form"]},"name":{"type":"string","description":"Internal name (dashboard label)."},"title":{"type":"string","description":"Rendered heading shown to submitters."},"subtitle":{"type":"string"},"slug":{"type":"string","description":"URL-safe identifier auto-generated from name if omitted."},"status":{"$ref":"#/components/schemas/FormStatus"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FormField"}},"action":{"type":"string","enum":["thankyou","redirect","message"],"description":"What happens after the submitter clicks submit."},"action_value":{"type":"string","description":"Companion to `action` — redirect URL, thank-you message text, etc."},"custom_css":{"type":"string","description":"Raw CSS injected into the form's `<style>` block on render. Legacy column: `additional_css`."},"tracking_codes":{"$ref":"#/components/schemas/FormTrackingCodes"},"design":{"$ref":"#/components/schemas/FormDesign"},"internal_notification":{"$ref":"#/components/schemas/FormInternalNotification"},"embed":{"$ref":"#/components/schemas/FormEmbed"},"submission_count":{"type":"integer","description":"Total submissions to date."},"submission_token_last4":{"type":"string","nullable":true,"description":"Last 4 chars of the current `submission_token`. Full plaintext is returned ONLY at publish and rotate."},"submission_token":{"type":"string","description":"Full plaintext submission_token. Returned ONLY as a one-shot on:\n  - `POST /forms` (create), when the request set `is_published: true` — a form created already-published gets a token minted immediately, the same as if it had been published separately right after.\n  - `POST /forms/{id}/publish` (first publish)\n  - `POST /forms/{id}/rotate_submission_token`\nStore it immediately; you cannot retrieve it again. If lost, rotate.\n"},"previous_submission_token_valid_until":{"type":"string","format":"date-time","description":"Rotate response only — timestamp at which the previously-issued token stops accepting submissions (default 24h grace)."},"last_submission_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true}}},"FormId":{"type":"string","pattern":"^fom_[0-9a-f]{24}$"},"FormStatus":{"type":"string","enum":["draft","published","archived"],"description":"Lifecycle. Newly-created forms start `draft`; `POST /forms/{id}/publish` moves them to `published` (and mints the `submission_token` on first publish). `DELETE /forms/{id}` is a genuine hard delete — the form is gone, not archived. `archived` is a legacy status that can still appear on forms deleted before this behavior shipped; it is never produced by any current action and has no path back to `draft`/`published`.\n"},"FormEmbed":{"type":"object","description":"Copy-paste embed helpers. Server-generated URLs point at the dashboard's\nexisting form-render endpoints (`/form/embedView/{id}` for the iframe-friendly\nfull page, `/form/embedHtmlView/{id}` for the bare HTML variant). Renderer\nbase URL is env-configured via `GLEANTAP_DASHBOARD_BASE_URL`.\n","properties":{"iframe_url":{"type":"string","format":"uri"},"html_url":{"type":"string","format":"uri"},"iframe_snippet":{"type":"string","description":"Ready-to-paste `<iframe>` tag."},"script_snippet":{"type":"string","description":"Ready-to-paste `<div>` + `<script>` tag pair — for embedded rendering."}}},"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":{"/forms/{id}":{"patch":{"tags":["Forms"],"operationId":"updateForm","summary":"Update a form.","description":"Partial patch. `tracking_codes` and `design` are merged per-key — supply only the values to change.","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/FormUpdate"}}}},"responses":{"200":{"description":"Updated form.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Form"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Delete a form.

> Genuine, irreversible hard delete — the form document is removed entirely. An internal audit copy is retained for support/recovery purposes but is not restorable via this API; there is no undelete/unarchive action.\
> \
> Existing submissions are unaffected and remain fully listable and retrievable via \`GET /forms/{id}/submissions\` and \`GET /form\_submissions/{id}\` even after the form itself is gone — they don't depend on the form document existing. The form's own embed/preview URLs and public submission endpoint stop working immediately, since there's no form left to serve or accept against.\
> \
> \*\*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":"Forms","description":"Web forms — public capture surface for turning anonymous visitors into contacts. Definitions carry field schema, custom CSS, tracking-code slots (head/body/on-submit), and design settings. Public submission is authenticated by a per-form `submission_token` (rotatable with a 24h grace window) — the only unauthenticated write surface in v3."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["forms:manage"]}],"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":{"/forms/{id}":{"delete":{"tags":["Forms"],"operationId":"deleteForm","summary":"Delete a form.","description":"Genuine, irreversible hard delete — the form document is removed entirely. An internal audit copy is retained for support/recovery purposes but is not restorable via this API; there is no undelete/unarchive action.\n\nExisting submissions are unaffected and remain fully listable and retrievable via `GET /forms/{id}/submissions` and `GET /form_submissions/{id}` even after the form itself is gone — they don't depend on the form document existing. The form's own embed/preview URLs and public submission endpoint stop working immediately, since there's no form left to serve or accept against.\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":"Archived."},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Publish a form.

> Sets status to \`published\`. On FIRST publish, mints a \`submission\_token\` and returns its plaintext in the response — store it immediately, you cannot retrieve it again. Subsequent publishes do not rotate the token. Use \`rotate\_submission\_token\` for that.\
> \
> \*\*Goes live.\*\* Once live it keeps reaching real contacts on its own, with no further call.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Forms","description":"Web forms — public capture surface for turning anonymous visitors into contacts. Definitions carry field schema, custom CSS, tracking-code slots (head/body/on-submit), and design settings. Public submission is authenticated by a per-form `submission_token` (rotatable with a 24h grace window) — the only unauthenticated write surface in v3."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["forms:manage"]}],"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":{"Form":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/FormId"},"object":{"type":"string","enum":["form"]},"name":{"type":"string","description":"Internal name (dashboard label)."},"title":{"type":"string","description":"Rendered heading shown to submitters."},"subtitle":{"type":"string"},"slug":{"type":"string","description":"URL-safe identifier auto-generated from name if omitted."},"status":{"$ref":"#/components/schemas/FormStatus"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FormField"}},"action":{"type":"string","enum":["thankyou","redirect","message"],"description":"What happens after the submitter clicks submit."},"action_value":{"type":"string","description":"Companion to `action` — redirect URL, thank-you message text, etc."},"custom_css":{"type":"string","description":"Raw CSS injected into the form's `<style>` block on render. Legacy column: `additional_css`."},"tracking_codes":{"$ref":"#/components/schemas/FormTrackingCodes"},"design":{"$ref":"#/components/schemas/FormDesign"},"internal_notification":{"$ref":"#/components/schemas/FormInternalNotification"},"embed":{"$ref":"#/components/schemas/FormEmbed"},"submission_count":{"type":"integer","description":"Total submissions to date."},"submission_token_last4":{"type":"string","nullable":true,"description":"Last 4 chars of the current `submission_token`. Full plaintext is returned ONLY at publish and rotate."},"submission_token":{"type":"string","description":"Full plaintext submission_token. Returned ONLY as a one-shot on:\n  - `POST /forms` (create), when the request set `is_published: true` — a form created already-published gets a token minted immediately, the same as if it had been published separately right after.\n  - `POST /forms/{id}/publish` (first publish)\n  - `POST /forms/{id}/rotate_submission_token`\nStore it immediately; you cannot retrieve it again. If lost, rotate.\n"},"previous_submission_token_valid_until":{"type":"string","format":"date-time","description":"Rotate response only — timestamp at which the previously-issued token stops accepting submissions (default 24h grace)."},"last_submission_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true}}},"FormId":{"type":"string","pattern":"^fom_[0-9a-f]{24}$"},"FormStatus":{"type":"string","enum":["draft","published","archived"],"description":"Lifecycle. Newly-created forms start `draft`; `POST /forms/{id}/publish` moves them to `published` (and mints the `submission_token` on first publish). `DELETE /forms/{id}` is a genuine hard delete — the form is gone, not archived. `archived` is a legacy status that can still appear on forms deleted before this behavior shipped; it is never produced by any current action and has no path back to `draft`/`published`.\n"},"FormField":{"type":"object","description":"A single input in the form's field schema. Stored verbatim under the legacy `data` JSON blob so the dashboard editor round-trips it. Extra keys are preserved — don't rely on this being a closed shape.\n\n**Naming:** each field has a `name` (the key that shows up in submission `values`). Known names like `email`, `phone`, `first_name`, `last_name`, `dob` are auto-mapped to standard contact fields on submit; anything else lands in `contact.data.<name>` as a custom field.\n\n**Consent (`optin` / `opt_in`):** two field names are recognized on submission, scoped to `POST /forms/{id}/submissions` only:\n  - `optin` (no underscore) — a `checkbox-group` field with independent `sms`/`email` options (the shape every dashboard-built form actually uses). Submitted as an array of whichever options were checked, e.g. `[\"email\"]`, `[\"sms\",\"email\"]`, or `[]`. Each checked channel sets that channel's consent to `opted_in` — but only when its contact value was submitted too (`sms` checked without a phone, or `email` without an email, writes nothing). As in the dashboard's own submit, a form submission **never opts anyone out**: an unchecked channel, `[]`, or omitting `optin` leaves the contact's existing consent untouched. To record an opt-out use `POST /contacts/{id}/opt_out`.\n  - `opt_in` (underscore) — a single `checkbox`, kept for backward compatibility. Covers email only: checked (with an email submitted) sets `consent.email.status` to `opted_in`; unchecked writes nothing. If a submission somehow includes both, `optin` wins.\n\n  `optin` follows the dashboard's own form submit (opt-in only, gated on the contact value being present); `opt_in` is v3-only.\n","required":["type"],"properties":{"type":{"type":"string","enum":["text","textarea","number","date","select","checkbox","checkbox-group","radio","radio-group","autocomplete","hidden","file","signature","starRating","payment","card","button","header","paragraph"],"description":"Input type — must match a value the dashboard renderer knows how to draw.\n\n**Phone and email fields:** there is no dedicated `phone` or `email` type. Use `type: \"text\"` with `subtype: \"tel\"` (phone) or `subtype: \"email\"` — exactly what the dashboard's own field templates save. A literal top-level `phone`/`email` type is normalized automatically to `type: \"text\"` with the matching `subtype`, not rejected — the dashboard's edit-screen widget has no control registered for either raw type, so storing one as-is would make the field unrenderable there.\n\n**Input fields** (produce a submission value):\n  - `text`, `textarea`, `number`, `date`, `hidden` — standard scalar inputs. Use `subtype` on `text` for `tel`/`email`/`password`/etc.\n  - `select` — dropdown. Provide `values[]`. Add `multiple: true` for multi-select.\n  - `checkbox-group`, `radio-group` — group of options. Provide `values[]`. `inline: true` renders horizontally.\n  - `checkbox`, `radio` — single option (rarely used; prefer the -group variants).\n  - `autocomplete` — typeahead. Provide `values[]`. Set `requireValidOption: true` to force the user to pick from the list.\n  - `file` — file upload. Optional `subtype: \"file\"|\"image\"`, `multiple: true` for many files.\n  - `signature` — SVG signature capture. Stored as a base64 image string on submit.\n  - `starRating` — star widget. Optional `stars: 5` (default 5).\n  - `payment`, `card` — Stripe payment/card capture. Requires the workroom to have a payment integration configured.\n\n**Non-input fields** (layout only, no submission value):\n  - `header` — section heading text (from `label`).\n  - `paragraph` — static paragraph text (from `label`).\n  - `button` — a button. `subtype: \"submit\"` for the form submit button.\n"},"name":{"type":"string","description":"The key used in submission `values`. Also the storage key on the contact. Prefer human-readable snake_case (`first_name`, `company`). The dashboard auto-generates `<type>-<timestamp>-<n>` if you omit it — pass an explicit `name` to keep submissions readable.\n"},"label":{"type":"string","description":"Visible label rendered above the input."},"required":{"type":"boolean","default":false},"placeholder":{"type":"string","description":"Placeholder / helper text inside empty inputs."},"className":{"type":"string","description":"Extra CSS classes applied when rendered (e.g. `form-control`, `w-50`). Applied via the dashboard renderer."},"subtype":{"type":"string","description":"Fine-grained variant of the base `type`. Applies to a few types:\n  - `button` → `submit` | `button` | `reset`\n  - `file` → `file` | `image`\n  - `text` → `tel` (phone), `email`, `password`, or omitted for plain text\n"},"multiple":{"type":"boolean","default":false,"description":"For `select` (multi-select dropdown) and `file` (multi-file upload)."},"inline":{"type":"boolean","default":false,"description":"For `radio-group` / `checkbox-group` — render options horizontally instead of stacked."},"toggle":{"type":"boolean","default":false,"description":"For `checkbox-group` — render as toggle switches instead of checkboxes."},"other":{"type":"boolean","default":false,"description":"For `radio-group` / `checkbox-group` — render an extra \"Other\" free-text input alongside the group."},"requireValidOption":{"type":"boolean","default":false,"description":"For `autocomplete` — reject submissions where the value is not one of the listed `values[]`."},"style":{"type":"string","description":"For `button` — visual style. Values: `default`, `primary`, `success`, `warning`, `danger`."},"value":{"type":"string","description":"For `button`, `hidden`, and inputs with a default — the pre-filled or fixed value."},"stars":{"type":"integer","minimum":1,"maximum":10,"default":5,"description":"For `starRating` — number of stars to render."},"access":{"type":"boolean","default":false,"description":"Legacy access-control flag. Almost always `false`. Only set for internal / staff-only fields the dashboard hides from the public form.\n"},"values":{"type":"array","description":"Option list for `select`, `checkbox-group`, `radio-group`, and `autocomplete` fields. Each item has `label`, `value`, and optional `selected` (default option). This is the legacy shape — do NOT use the deprecated `options[]` field.\n","items":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string","description":"Text shown to the user."},"value":{"type":"string","description":"Value submitted when this option is chosen."},"selected":{"type":"boolean","default":false,"description":"Marks this option as the default (pre-selected)."}}}}}},"FormTrackingCodes":{"type":"object","description":"Third-party tracking snippets. Injected verbatim by the dashboard's embed\nrenderer — `head` before `</head>`, `body` immediately after `<body>`,\n`form_submission` on successful client-side submit (for GTM/Meta Pixel/GA4).\n","properties":{"head":{"type":"string","description":"Raw HTML/JS injected before `</head>`. Typical use: Meta Pixel init, GTM container."},"body":{"type":"string","description":"Raw HTML/JS injected after `<body>`. Typical use: GTM noscript iframe."},"form_submission":{"type":"string","description":"JS fired on successful submit. Typical use: `gtag(\"event\",\"generate_lead\")`."}}},"FormDesign":{"type":"object","description":"Visual settings honored by the dashboard's embed renderer.","properties":{"background_type":{"type":"string","enum":["solid","image"],"description":"Solid color or image background."},"background_color":{"type":"string","description":"CSS hex/rgb string."},"form_color":{"type":"string","description":"Form panel background."},"text_color":{"type":"string"},"border_color":{"type":"string"},"logo_url":{"type":"string","format":"uri","description":"Absolute URL to a logo image (typically S3)."},"background_image_url":{"type":"string","format":"uri","description":"Absolute URL to a background image."}}},"FormInternalNotification":{"type":"object","description":"Notify internal staff by email whenever the form is submitted. Configured\nin the dashboard under the form's gear icon → Workflows tab. Legacy Mongo\ncolumns: `enable_notification` (int 0/1), `notification_email` (comma-joined\nrecipient list). At submit time the notification is dispatched by the\nlegacy `handlePostFormAction` worker if `notification_email` is non-empty.\n","properties":{"enabled":{"type":"boolean","description":"Whether the internal notification is turned on."},"recipient_emails":{"type":"array","items":{"type":"string","format":"email"},"description":"Staff email addresses to notify. Stored as a comma-joined string in the legacy field."}}},"FormEmbed":{"type":"object","description":"Copy-paste embed helpers. Server-generated URLs point at the dashboard's\nexisting form-render endpoints (`/form/embedView/{id}` for the iframe-friendly\nfull page, `/form/embedHtmlView/{id}` for the bare HTML variant). Renderer\nbase URL is env-configured via `GLEANTAP_DASHBOARD_BASE_URL`.\n","properties":{"iframe_url":{"type":"string","format":"uri"},"html_url":{"type":"string","format":"uri"},"iframe_snippet":{"type":"string","description":"Ready-to-paste `<iframe>` tag."},"script_snippet":{"type":"string","description":"Ready-to-paste `<div>` + `<script>` tag pair — for embedded rendering."}}},"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":{"/forms/{id}/publish":{"post":{"tags":["Forms"],"operationId":"publishForm","summary":"Publish a form.","description":"Sets status to `published`. On FIRST publish, mints a `submission_token` and returns its plaintext in the response — store it immediately, you cannot retrieve it again. Subsequent publishes do not rotate the token. Use `rotate_submission_token` for that.\n\n**Goes live.** Once live it keeps reaching real contacts on its own, with no further call.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"Published. `submission_token` present ONLY on first publish.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Form"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Unpublish (return to draft).

> New public submissions are rejected with 401 while unpublished. The submission\_token is retained (not rotated) so publishing again resumes with the same token.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Forms","description":"Web forms — public capture surface for turning anonymous visitors into contacts. Definitions carry field schema, custom CSS, tracking-code slots (head/body/on-submit), and design settings. Public submission is authenticated by a per-form `submission_token` (rotatable with a 24h grace window) — the only unauthenticated write surface in v3."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["forms:manage"]}],"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":{"Form":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/FormId"},"object":{"type":"string","enum":["form"]},"name":{"type":"string","description":"Internal name (dashboard label)."},"title":{"type":"string","description":"Rendered heading shown to submitters."},"subtitle":{"type":"string"},"slug":{"type":"string","description":"URL-safe identifier auto-generated from name if omitted."},"status":{"$ref":"#/components/schemas/FormStatus"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FormField"}},"action":{"type":"string","enum":["thankyou","redirect","message"],"description":"What happens after the submitter clicks submit."},"action_value":{"type":"string","description":"Companion to `action` — redirect URL, thank-you message text, etc."},"custom_css":{"type":"string","description":"Raw CSS injected into the form's `<style>` block on render. Legacy column: `additional_css`."},"tracking_codes":{"$ref":"#/components/schemas/FormTrackingCodes"},"design":{"$ref":"#/components/schemas/FormDesign"},"internal_notification":{"$ref":"#/components/schemas/FormInternalNotification"},"embed":{"$ref":"#/components/schemas/FormEmbed"},"submission_count":{"type":"integer","description":"Total submissions to date."},"submission_token_last4":{"type":"string","nullable":true,"description":"Last 4 chars of the current `submission_token`. Full plaintext is returned ONLY at publish and rotate."},"submission_token":{"type":"string","description":"Full plaintext submission_token. Returned ONLY as a one-shot on:\n  - `POST /forms` (create), when the request set `is_published: true` — a form created already-published gets a token minted immediately, the same as if it had been published separately right after.\n  - `POST /forms/{id}/publish` (first publish)\n  - `POST /forms/{id}/rotate_submission_token`\nStore it immediately; you cannot retrieve it again. If lost, rotate.\n"},"previous_submission_token_valid_until":{"type":"string","format":"date-time","description":"Rotate response only — timestamp at which the previously-issued token stops accepting submissions (default 24h grace)."},"last_submission_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true}}},"FormId":{"type":"string","pattern":"^fom_[0-9a-f]{24}$"},"FormStatus":{"type":"string","enum":["draft","published","archived"],"description":"Lifecycle. Newly-created forms start `draft`; `POST /forms/{id}/publish` moves them to `published` (and mints the `submission_token` on first publish). `DELETE /forms/{id}` is a genuine hard delete — the form is gone, not archived. `archived` is a legacy status that can still appear on forms deleted before this behavior shipped; it is never produced by any current action and has no path back to `draft`/`published`.\n"},"FormField":{"type":"object","description":"A single input in the form's field schema. Stored verbatim under the legacy `data` JSON blob so the dashboard editor round-trips it. Extra keys are preserved — don't rely on this being a closed shape.\n\n**Naming:** each field has a `name` (the key that shows up in submission `values`). Known names like `email`, `phone`, `first_name`, `last_name`, `dob` are auto-mapped to standard contact fields on submit; anything else lands in `contact.data.<name>` as a custom field.\n\n**Consent (`optin` / `opt_in`):** two field names are recognized on submission, scoped to `POST /forms/{id}/submissions` only:\n  - `optin` (no underscore) — a `checkbox-group` field with independent `sms`/`email` options (the shape every dashboard-built form actually uses). Submitted as an array of whichever options were checked, e.g. `[\"email\"]`, `[\"sms\",\"email\"]`, or `[]`. Each checked channel sets that channel's consent to `opted_in` — but only when its contact value was submitted too (`sms` checked without a phone, or `email` without an email, writes nothing). As in the dashboard's own submit, a form submission **never opts anyone out**: an unchecked channel, `[]`, or omitting `optin` leaves the contact's existing consent untouched. To record an opt-out use `POST /contacts/{id}/opt_out`.\n  - `opt_in` (underscore) — a single `checkbox`, kept for backward compatibility. Covers email only: checked (with an email submitted) sets `consent.email.status` to `opted_in`; unchecked writes nothing. If a submission somehow includes both, `optin` wins.\n\n  `optin` follows the dashboard's own form submit (opt-in only, gated on the contact value being present); `opt_in` is v3-only.\n","required":["type"],"properties":{"type":{"type":"string","enum":["text","textarea","number","date","select","checkbox","checkbox-group","radio","radio-group","autocomplete","hidden","file","signature","starRating","payment","card","button","header","paragraph"],"description":"Input type — must match a value the dashboard renderer knows how to draw.\n\n**Phone and email fields:** there is no dedicated `phone` or `email` type. Use `type: \"text\"` with `subtype: \"tel\"` (phone) or `subtype: \"email\"` — exactly what the dashboard's own field templates save. A literal top-level `phone`/`email` type is normalized automatically to `type: \"text\"` with the matching `subtype`, not rejected — the dashboard's edit-screen widget has no control registered for either raw type, so storing one as-is would make the field unrenderable there.\n\n**Input fields** (produce a submission value):\n  - `text`, `textarea`, `number`, `date`, `hidden` — standard scalar inputs. Use `subtype` on `text` for `tel`/`email`/`password`/etc.\n  - `select` — dropdown. Provide `values[]`. Add `multiple: true` for multi-select.\n  - `checkbox-group`, `radio-group` — group of options. Provide `values[]`. `inline: true` renders horizontally.\n  - `checkbox`, `radio` — single option (rarely used; prefer the -group variants).\n  - `autocomplete` — typeahead. Provide `values[]`. Set `requireValidOption: true` to force the user to pick from the list.\n  - `file` — file upload. Optional `subtype: \"file\"|\"image\"`, `multiple: true` for many files.\n  - `signature` — SVG signature capture. Stored as a base64 image string on submit.\n  - `starRating` — star widget. Optional `stars: 5` (default 5).\n  - `payment`, `card` — Stripe payment/card capture. Requires the workroom to have a payment integration configured.\n\n**Non-input fields** (layout only, no submission value):\n  - `header` — section heading text (from `label`).\n  - `paragraph` — static paragraph text (from `label`).\n  - `button` — a button. `subtype: \"submit\"` for the form submit button.\n"},"name":{"type":"string","description":"The key used in submission `values`. Also the storage key on the contact. Prefer human-readable snake_case (`first_name`, `company`). The dashboard auto-generates `<type>-<timestamp>-<n>` if you omit it — pass an explicit `name` to keep submissions readable.\n"},"label":{"type":"string","description":"Visible label rendered above the input."},"required":{"type":"boolean","default":false},"placeholder":{"type":"string","description":"Placeholder / helper text inside empty inputs."},"className":{"type":"string","description":"Extra CSS classes applied when rendered (e.g. `form-control`, `w-50`). Applied via the dashboard renderer."},"subtype":{"type":"string","description":"Fine-grained variant of the base `type`. Applies to a few types:\n  - `button` → `submit` | `button` | `reset`\n  - `file` → `file` | `image`\n  - `text` → `tel` (phone), `email`, `password`, or omitted for plain text\n"},"multiple":{"type":"boolean","default":false,"description":"For `select` (multi-select dropdown) and `file` (multi-file upload)."},"inline":{"type":"boolean","default":false,"description":"For `radio-group` / `checkbox-group` — render options horizontally instead of stacked."},"toggle":{"type":"boolean","default":false,"description":"For `checkbox-group` — render as toggle switches instead of checkboxes."},"other":{"type":"boolean","default":false,"description":"For `radio-group` / `checkbox-group` — render an extra \"Other\" free-text input alongside the group."},"requireValidOption":{"type":"boolean","default":false,"description":"For `autocomplete` — reject submissions where the value is not one of the listed `values[]`."},"style":{"type":"string","description":"For `button` — visual style. Values: `default`, `primary`, `success`, `warning`, `danger`."},"value":{"type":"string","description":"For `button`, `hidden`, and inputs with a default — the pre-filled or fixed value."},"stars":{"type":"integer","minimum":1,"maximum":10,"default":5,"description":"For `starRating` — number of stars to render."},"access":{"type":"boolean","default":false,"description":"Legacy access-control flag. Almost always `false`. Only set for internal / staff-only fields the dashboard hides from the public form.\n"},"values":{"type":"array","description":"Option list for `select`, `checkbox-group`, `radio-group`, and `autocomplete` fields. Each item has `label`, `value`, and optional `selected` (default option). This is the legacy shape — do NOT use the deprecated `options[]` field.\n","items":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string","description":"Text shown to the user."},"value":{"type":"string","description":"Value submitted when this option is chosen."},"selected":{"type":"boolean","default":false,"description":"Marks this option as the default (pre-selected)."}}}}}},"FormTrackingCodes":{"type":"object","description":"Third-party tracking snippets. Injected verbatim by the dashboard's embed\nrenderer — `head` before `</head>`, `body` immediately after `<body>`,\n`form_submission` on successful client-side submit (for GTM/Meta Pixel/GA4).\n","properties":{"head":{"type":"string","description":"Raw HTML/JS injected before `</head>`. Typical use: Meta Pixel init, GTM container."},"body":{"type":"string","description":"Raw HTML/JS injected after `<body>`. Typical use: GTM noscript iframe."},"form_submission":{"type":"string","description":"JS fired on successful submit. Typical use: `gtag(\"event\",\"generate_lead\")`."}}},"FormDesign":{"type":"object","description":"Visual settings honored by the dashboard's embed renderer.","properties":{"background_type":{"type":"string","enum":["solid","image"],"description":"Solid color or image background."},"background_color":{"type":"string","description":"CSS hex/rgb string."},"form_color":{"type":"string","description":"Form panel background."},"text_color":{"type":"string"},"border_color":{"type":"string"},"logo_url":{"type":"string","format":"uri","description":"Absolute URL to a logo image (typically S3)."},"background_image_url":{"type":"string","format":"uri","description":"Absolute URL to a background image."}}},"FormInternalNotification":{"type":"object","description":"Notify internal staff by email whenever the form is submitted. Configured\nin the dashboard under the form's gear icon → Workflows tab. Legacy Mongo\ncolumns: `enable_notification` (int 0/1), `notification_email` (comma-joined\nrecipient list). At submit time the notification is dispatched by the\nlegacy `handlePostFormAction` worker if `notification_email` is non-empty.\n","properties":{"enabled":{"type":"boolean","description":"Whether the internal notification is turned on."},"recipient_emails":{"type":"array","items":{"type":"string","format":"email"},"description":"Staff email addresses to notify. Stored as a comma-joined string in the legacy field."}}},"FormEmbed":{"type":"object","description":"Copy-paste embed helpers. Server-generated URLs point at the dashboard's\nexisting form-render endpoints (`/form/embedView/{id}` for the iframe-friendly\nfull page, `/form/embedHtmlView/{id}` for the bare HTML variant). Renderer\nbase URL is env-configured via `GLEANTAP_DASHBOARD_BASE_URL`.\n","properties":{"iframe_url":{"type":"string","format":"uri"},"html_url":{"type":"string","format":"uri"},"iframe_snippet":{"type":"string","description":"Ready-to-paste `<iframe>` tag."},"script_snippet":{"type":"string","description":"Ready-to-paste `<div>` + `<script>` tag pair — for embedded rendering."}}},"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":{"/forms/{id}/unpublish":{"post":{"tags":["Forms"],"operationId":"unpublishForm","summary":"Unpublish (return to draft).","description":"New public submissions are rejected with 401 while unpublished. The submission_token is retained (not rotated) so publishing again resumes with the same token.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"Now in draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Form"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Duplicate a form as a new draft.

> Copies fields, custom\_css, tracking\_codes, design. Does NOT copy the submission\_token or submission\_count — the duplicate starts fresh.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Forms","description":"Web forms — public capture surface for turning anonymous visitors into contacts. Definitions carry field schema, custom CSS, tracking-code slots (head/body/on-submit), and design settings. Public submission is authenticated by a per-form `submission_token` (rotatable with a 24h grace window) — the only unauthenticated write surface in v3."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["forms:manage"]}],"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":{"Form":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/FormId"},"object":{"type":"string","enum":["form"]},"name":{"type":"string","description":"Internal name (dashboard label)."},"title":{"type":"string","description":"Rendered heading shown to submitters."},"subtitle":{"type":"string"},"slug":{"type":"string","description":"URL-safe identifier auto-generated from name if omitted."},"status":{"$ref":"#/components/schemas/FormStatus"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FormField"}},"action":{"type":"string","enum":["thankyou","redirect","message"],"description":"What happens after the submitter clicks submit."},"action_value":{"type":"string","description":"Companion to `action` — redirect URL, thank-you message text, etc."},"custom_css":{"type":"string","description":"Raw CSS injected into the form's `<style>` block on render. Legacy column: `additional_css`."},"tracking_codes":{"$ref":"#/components/schemas/FormTrackingCodes"},"design":{"$ref":"#/components/schemas/FormDesign"},"internal_notification":{"$ref":"#/components/schemas/FormInternalNotification"},"embed":{"$ref":"#/components/schemas/FormEmbed"},"submission_count":{"type":"integer","description":"Total submissions to date."},"submission_token_last4":{"type":"string","nullable":true,"description":"Last 4 chars of the current `submission_token`. Full plaintext is returned ONLY at publish and rotate."},"submission_token":{"type":"string","description":"Full plaintext submission_token. Returned ONLY as a one-shot on:\n  - `POST /forms` (create), when the request set `is_published: true` — a form created already-published gets a token minted immediately, the same as if it had been published separately right after.\n  - `POST /forms/{id}/publish` (first publish)\n  - `POST /forms/{id}/rotate_submission_token`\nStore it immediately; you cannot retrieve it again. If lost, rotate.\n"},"previous_submission_token_valid_until":{"type":"string","format":"date-time","description":"Rotate response only — timestamp at which the previously-issued token stops accepting submissions (default 24h grace)."},"last_submission_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true}}},"FormId":{"type":"string","pattern":"^fom_[0-9a-f]{24}$"},"FormStatus":{"type":"string","enum":["draft","published","archived"],"description":"Lifecycle. Newly-created forms start `draft`; `POST /forms/{id}/publish` moves them to `published` (and mints the `submission_token` on first publish). `DELETE /forms/{id}` is a genuine hard delete — the form is gone, not archived. `archived` is a legacy status that can still appear on forms deleted before this behavior shipped; it is never produced by any current action and has no path back to `draft`/`published`.\n"},"FormField":{"type":"object","description":"A single input in the form's field schema. Stored verbatim under the legacy `data` JSON blob so the dashboard editor round-trips it. Extra keys are preserved — don't rely on this being a closed shape.\n\n**Naming:** each field has a `name` (the key that shows up in submission `values`). Known names like `email`, `phone`, `first_name`, `last_name`, `dob` are auto-mapped to standard contact fields on submit; anything else lands in `contact.data.<name>` as a custom field.\n\n**Consent (`optin` / `opt_in`):** two field names are recognized on submission, scoped to `POST /forms/{id}/submissions` only:\n  - `optin` (no underscore) — a `checkbox-group` field with independent `sms`/`email` options (the shape every dashboard-built form actually uses). Submitted as an array of whichever options were checked, e.g. `[\"email\"]`, `[\"sms\",\"email\"]`, or `[]`. Each checked channel sets that channel's consent to `opted_in` — but only when its contact value was submitted too (`sms` checked without a phone, or `email` without an email, writes nothing). As in the dashboard's own submit, a form submission **never opts anyone out**: an unchecked channel, `[]`, or omitting `optin` leaves the contact's existing consent untouched. To record an opt-out use `POST /contacts/{id}/opt_out`.\n  - `opt_in` (underscore) — a single `checkbox`, kept for backward compatibility. Covers email only: checked (with an email submitted) sets `consent.email.status` to `opted_in`; unchecked writes nothing. If a submission somehow includes both, `optin` wins.\n\n  `optin` follows the dashboard's own form submit (opt-in only, gated on the contact value being present); `opt_in` is v3-only.\n","required":["type"],"properties":{"type":{"type":"string","enum":["text","textarea","number","date","select","checkbox","checkbox-group","radio","radio-group","autocomplete","hidden","file","signature","starRating","payment","card","button","header","paragraph"],"description":"Input type — must match a value the dashboard renderer knows how to draw.\n\n**Phone and email fields:** there is no dedicated `phone` or `email` type. Use `type: \"text\"` with `subtype: \"tel\"` (phone) or `subtype: \"email\"` — exactly what the dashboard's own field templates save. A literal top-level `phone`/`email` type is normalized automatically to `type: \"text\"` with the matching `subtype`, not rejected — the dashboard's edit-screen widget has no control registered for either raw type, so storing one as-is would make the field unrenderable there.\n\n**Input fields** (produce a submission value):\n  - `text`, `textarea`, `number`, `date`, `hidden` — standard scalar inputs. Use `subtype` on `text` for `tel`/`email`/`password`/etc.\n  - `select` — dropdown. Provide `values[]`. Add `multiple: true` for multi-select.\n  - `checkbox-group`, `radio-group` — group of options. Provide `values[]`. `inline: true` renders horizontally.\n  - `checkbox`, `radio` — single option (rarely used; prefer the -group variants).\n  - `autocomplete` — typeahead. Provide `values[]`. Set `requireValidOption: true` to force the user to pick from the list.\n  - `file` — file upload. Optional `subtype: \"file\"|\"image\"`, `multiple: true` for many files.\n  - `signature` — SVG signature capture. Stored as a base64 image string on submit.\n  - `starRating` — star widget. Optional `stars: 5` (default 5).\n  - `payment`, `card` — Stripe payment/card capture. Requires the workroom to have a payment integration configured.\n\n**Non-input fields** (layout only, no submission value):\n  - `header` — section heading text (from `label`).\n  - `paragraph` — static paragraph text (from `label`).\n  - `button` — a button. `subtype: \"submit\"` for the form submit button.\n"},"name":{"type":"string","description":"The key used in submission `values`. Also the storage key on the contact. Prefer human-readable snake_case (`first_name`, `company`). The dashboard auto-generates `<type>-<timestamp>-<n>` if you omit it — pass an explicit `name` to keep submissions readable.\n"},"label":{"type":"string","description":"Visible label rendered above the input."},"required":{"type":"boolean","default":false},"placeholder":{"type":"string","description":"Placeholder / helper text inside empty inputs."},"className":{"type":"string","description":"Extra CSS classes applied when rendered (e.g. `form-control`, `w-50`). Applied via the dashboard renderer."},"subtype":{"type":"string","description":"Fine-grained variant of the base `type`. Applies to a few types:\n  - `button` → `submit` | `button` | `reset`\n  - `file` → `file` | `image`\n  - `text` → `tel` (phone), `email`, `password`, or omitted for plain text\n"},"multiple":{"type":"boolean","default":false,"description":"For `select` (multi-select dropdown) and `file` (multi-file upload)."},"inline":{"type":"boolean","default":false,"description":"For `radio-group` / `checkbox-group` — render options horizontally instead of stacked."},"toggle":{"type":"boolean","default":false,"description":"For `checkbox-group` — render as toggle switches instead of checkboxes."},"other":{"type":"boolean","default":false,"description":"For `radio-group` / `checkbox-group` — render an extra \"Other\" free-text input alongside the group."},"requireValidOption":{"type":"boolean","default":false,"description":"For `autocomplete` — reject submissions where the value is not one of the listed `values[]`."},"style":{"type":"string","description":"For `button` — visual style. Values: `default`, `primary`, `success`, `warning`, `danger`."},"value":{"type":"string","description":"For `button`, `hidden`, and inputs with a default — the pre-filled or fixed value."},"stars":{"type":"integer","minimum":1,"maximum":10,"default":5,"description":"For `starRating` — number of stars to render."},"access":{"type":"boolean","default":false,"description":"Legacy access-control flag. Almost always `false`. Only set for internal / staff-only fields the dashboard hides from the public form.\n"},"values":{"type":"array","description":"Option list for `select`, `checkbox-group`, `radio-group`, and `autocomplete` fields. Each item has `label`, `value`, and optional `selected` (default option). This is the legacy shape — do NOT use the deprecated `options[]` field.\n","items":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string","description":"Text shown to the user."},"value":{"type":"string","description":"Value submitted when this option is chosen."},"selected":{"type":"boolean","default":false,"description":"Marks this option as the default (pre-selected)."}}}}}},"FormTrackingCodes":{"type":"object","description":"Third-party tracking snippets. Injected verbatim by the dashboard's embed\nrenderer — `head` before `</head>`, `body` immediately after `<body>`,\n`form_submission` on successful client-side submit (for GTM/Meta Pixel/GA4).\n","properties":{"head":{"type":"string","description":"Raw HTML/JS injected before `</head>`. Typical use: Meta Pixel init, GTM container."},"body":{"type":"string","description":"Raw HTML/JS injected after `<body>`. Typical use: GTM noscript iframe."},"form_submission":{"type":"string","description":"JS fired on successful submit. Typical use: `gtag(\"event\",\"generate_lead\")`."}}},"FormDesign":{"type":"object","description":"Visual settings honored by the dashboard's embed renderer.","properties":{"background_type":{"type":"string","enum":["solid","image"],"description":"Solid color or image background."},"background_color":{"type":"string","description":"CSS hex/rgb string."},"form_color":{"type":"string","description":"Form panel background."},"text_color":{"type":"string"},"border_color":{"type":"string"},"logo_url":{"type":"string","format":"uri","description":"Absolute URL to a logo image (typically S3)."},"background_image_url":{"type":"string","format":"uri","description":"Absolute URL to a background image."}}},"FormInternalNotification":{"type":"object","description":"Notify internal staff by email whenever the form is submitted. Configured\nin the dashboard under the form's gear icon → Workflows tab. Legacy Mongo\ncolumns: `enable_notification` (int 0/1), `notification_email` (comma-joined\nrecipient list). At submit time the notification is dispatched by the\nlegacy `handlePostFormAction` worker if `notification_email` is non-empty.\n","properties":{"enabled":{"type":"boolean","description":"Whether the internal notification is turned on."},"recipient_emails":{"type":"array","items":{"type":"string","format":"email"},"description":"Staff email addresses to notify. Stored as a comma-joined string in the legacy field."}}},"FormEmbed":{"type":"object","description":"Copy-paste embed helpers. Server-generated URLs point at the dashboard's\nexisting form-render endpoints (`/form/embedView/{id}` for the iframe-friendly\nfull page, `/form/embedHtmlView/{id}` for the bare HTML variant). Renderer\nbase URL is env-configured via `GLEANTAP_DASHBOARD_BASE_URL`.\n","properties":{"iframe_url":{"type":"string","format":"uri"},"html_url":{"type":"string","format":"uri"},"iframe_snippet":{"type":"string","description":"Ready-to-paste `<iframe>` tag."},"script_snippet":{"type":"string","description":"Ready-to-paste `<div>` + `<script>` tag pair — for embedded rendering."}}},"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":{"/forms/{id}/duplicate":{"post":{"tags":["Forms"],"operationId":"duplicateForm","summary":"Duplicate a form as a new draft.","description":"Copies fields, custom_css, tracking_codes, design. Does NOT copy the submission_token or submission_count — the duplicate starts fresh.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name for the duplicate. Defaults to `{original name} (copy)`."}}}}}},"responses":{"201":{"description":"New draft form.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Form"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Rotate the form's submission\_token.

> Mints a new plaintext \`submission\_token\` and returns it once. The previous token stays valid for a 24-hour grace period — response includes \`previous\_submission\_token\_valid\_until\` to let callers coordinate a rolling switch.\
> \
> \*\*Breaks live integrations.\*\* Anything using the current secret stops working the moment this is called, until it is updated with the new one.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Forms","description":"Web forms — public capture surface for turning anonymous visitors into contacts. Definitions carry field schema, custom CSS, tracking-code slots (head/body/on-submit), and design settings. Public submission is authenticated by a per-form `submission_token` (rotatable with a 24h grace window) — the only unauthenticated write surface in v3."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["forms:manage"]}],"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":{"Form":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/FormId"},"object":{"type":"string","enum":["form"]},"name":{"type":"string","description":"Internal name (dashboard label)."},"title":{"type":"string","description":"Rendered heading shown to submitters."},"subtitle":{"type":"string"},"slug":{"type":"string","description":"URL-safe identifier auto-generated from name if omitted."},"status":{"$ref":"#/components/schemas/FormStatus"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/FormField"}},"action":{"type":"string","enum":["thankyou","redirect","message"],"description":"What happens after the submitter clicks submit."},"action_value":{"type":"string","description":"Companion to `action` — redirect URL, thank-you message text, etc."},"custom_css":{"type":"string","description":"Raw CSS injected into the form's `<style>` block on render. Legacy column: `additional_css`."},"tracking_codes":{"$ref":"#/components/schemas/FormTrackingCodes"},"design":{"$ref":"#/components/schemas/FormDesign"},"internal_notification":{"$ref":"#/components/schemas/FormInternalNotification"},"embed":{"$ref":"#/components/schemas/FormEmbed"},"submission_count":{"type":"integer","description":"Total submissions to date."},"submission_token_last4":{"type":"string","nullable":true,"description":"Last 4 chars of the current `submission_token`. Full plaintext is returned ONLY at publish and rotate."},"submission_token":{"type":"string","description":"Full plaintext submission_token. Returned ONLY as a one-shot on:\n  - `POST /forms` (create), when the request set `is_published: true` — a form created already-published gets a token minted immediately, the same as if it had been published separately right after.\n  - `POST /forms/{id}/publish` (first publish)\n  - `POST /forms/{id}/rotate_submission_token`\nStore it immediately; you cannot retrieve it again. If lost, rotate.\n"},"previous_submission_token_valid_until":{"type":"string","format":"date-time","description":"Rotate response only — timestamp at which the previously-issued token stops accepting submissions (default 24h grace)."},"last_submission_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true}}},"FormId":{"type":"string","pattern":"^fom_[0-9a-f]{24}$"},"FormStatus":{"type":"string","enum":["draft","published","archived"],"description":"Lifecycle. Newly-created forms start `draft`; `POST /forms/{id}/publish` moves them to `published` (and mints the `submission_token` on first publish). `DELETE /forms/{id}` is a genuine hard delete — the form is gone, not archived. `archived` is a legacy status that can still appear on forms deleted before this behavior shipped; it is never produced by any current action and has no path back to `draft`/`published`.\n"},"FormField":{"type":"object","description":"A single input in the form's field schema. Stored verbatim under the legacy `data` JSON blob so the dashboard editor round-trips it. Extra keys are preserved — don't rely on this being a closed shape.\n\n**Naming:** each field has a `name` (the key that shows up in submission `values`). Known names like `email`, `phone`, `first_name`, `last_name`, `dob` are auto-mapped to standard contact fields on submit; anything else lands in `contact.data.<name>` as a custom field.\n\n**Consent (`optin` / `opt_in`):** two field names are recognized on submission, scoped to `POST /forms/{id}/submissions` only:\n  - `optin` (no underscore) — a `checkbox-group` field with independent `sms`/`email` options (the shape every dashboard-built form actually uses). Submitted as an array of whichever options were checked, e.g. `[\"email\"]`, `[\"sms\",\"email\"]`, or `[]`. Each checked channel sets that channel's consent to `opted_in` — but only when its contact value was submitted too (`sms` checked without a phone, or `email` without an email, writes nothing). As in the dashboard's own submit, a form submission **never opts anyone out**: an unchecked channel, `[]`, or omitting `optin` leaves the contact's existing consent untouched. To record an opt-out use `POST /contacts/{id}/opt_out`.\n  - `opt_in` (underscore) — a single `checkbox`, kept for backward compatibility. Covers email only: checked (with an email submitted) sets `consent.email.status` to `opted_in`; unchecked writes nothing. If a submission somehow includes both, `optin` wins.\n\n  `optin` follows the dashboard's own form submit (opt-in only, gated on the contact value being present); `opt_in` is v3-only.\n","required":["type"],"properties":{"type":{"type":"string","enum":["text","textarea","number","date","select","checkbox","checkbox-group","radio","radio-group","autocomplete","hidden","file","signature","starRating","payment","card","button","header","paragraph"],"description":"Input type — must match a value the dashboard renderer knows how to draw.\n\n**Phone and email fields:** there is no dedicated `phone` or `email` type. Use `type: \"text\"` with `subtype: \"tel\"` (phone) or `subtype: \"email\"` — exactly what the dashboard's own field templates save. A literal top-level `phone`/`email` type is normalized automatically to `type: \"text\"` with the matching `subtype`, not rejected — the dashboard's edit-screen widget has no control registered for either raw type, so storing one as-is would make the field unrenderable there.\n\n**Input fields** (produce a submission value):\n  - `text`, `textarea`, `number`, `date`, `hidden` — standard scalar inputs. Use `subtype` on `text` for `tel`/`email`/`password`/etc.\n  - `select` — dropdown. Provide `values[]`. Add `multiple: true` for multi-select.\n  - `checkbox-group`, `radio-group` — group of options. Provide `values[]`. `inline: true` renders horizontally.\n  - `checkbox`, `radio` — single option (rarely used; prefer the -group variants).\n  - `autocomplete` — typeahead. Provide `values[]`. Set `requireValidOption: true` to force the user to pick from the list.\n  - `file` — file upload. Optional `subtype: \"file\"|\"image\"`, `multiple: true` for many files.\n  - `signature` — SVG signature capture. Stored as a base64 image string on submit.\n  - `starRating` — star widget. Optional `stars: 5` (default 5).\n  - `payment`, `card` — Stripe payment/card capture. Requires the workroom to have a payment integration configured.\n\n**Non-input fields** (layout only, no submission value):\n  - `header` — section heading text (from `label`).\n  - `paragraph` — static paragraph text (from `label`).\n  - `button` — a button. `subtype: \"submit\"` for the form submit button.\n"},"name":{"type":"string","description":"The key used in submission `values`. Also the storage key on the contact. Prefer human-readable snake_case (`first_name`, `company`). The dashboard auto-generates `<type>-<timestamp>-<n>` if you omit it — pass an explicit `name` to keep submissions readable.\n"},"label":{"type":"string","description":"Visible label rendered above the input."},"required":{"type":"boolean","default":false},"placeholder":{"type":"string","description":"Placeholder / helper text inside empty inputs."},"className":{"type":"string","description":"Extra CSS classes applied when rendered (e.g. `form-control`, `w-50`). Applied via the dashboard renderer."},"subtype":{"type":"string","description":"Fine-grained variant of the base `type`. Applies to a few types:\n  - `button` → `submit` | `button` | `reset`\n  - `file` → `file` | `image`\n  - `text` → `tel` (phone), `email`, `password`, or omitted for plain text\n"},"multiple":{"type":"boolean","default":false,"description":"For `select` (multi-select dropdown) and `file` (multi-file upload)."},"inline":{"type":"boolean","default":false,"description":"For `radio-group` / `checkbox-group` — render options horizontally instead of stacked."},"toggle":{"type":"boolean","default":false,"description":"For `checkbox-group` — render as toggle switches instead of checkboxes."},"other":{"type":"boolean","default":false,"description":"For `radio-group` / `checkbox-group` — render an extra \"Other\" free-text input alongside the group."},"requireValidOption":{"type":"boolean","default":false,"description":"For `autocomplete` — reject submissions where the value is not one of the listed `values[]`."},"style":{"type":"string","description":"For `button` — visual style. Values: `default`, `primary`, `success`, `warning`, `danger`."},"value":{"type":"string","description":"For `button`, `hidden`, and inputs with a default — the pre-filled or fixed value."},"stars":{"type":"integer","minimum":1,"maximum":10,"default":5,"description":"For `starRating` — number of stars to render."},"access":{"type":"boolean","default":false,"description":"Legacy access-control flag. Almost always `false`. Only set for internal / staff-only fields the dashboard hides from the public form.\n"},"values":{"type":"array","description":"Option list for `select`, `checkbox-group`, `radio-group`, and `autocomplete` fields. Each item has `label`, `value`, and optional `selected` (default option). This is the legacy shape — do NOT use the deprecated `options[]` field.\n","items":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string","description":"Text shown to the user."},"value":{"type":"string","description":"Value submitted when this option is chosen."},"selected":{"type":"boolean","default":false,"description":"Marks this option as the default (pre-selected)."}}}}}},"FormTrackingCodes":{"type":"object","description":"Third-party tracking snippets. Injected verbatim by the dashboard's embed\nrenderer — `head` before `</head>`, `body` immediately after `<body>`,\n`form_submission` on successful client-side submit (for GTM/Meta Pixel/GA4).\n","properties":{"head":{"type":"string","description":"Raw HTML/JS injected before `</head>`. Typical use: Meta Pixel init, GTM container."},"body":{"type":"string","description":"Raw HTML/JS injected after `<body>`. Typical use: GTM noscript iframe."},"form_submission":{"type":"string","description":"JS fired on successful submit. Typical use: `gtag(\"event\",\"generate_lead\")`."}}},"FormDesign":{"type":"object","description":"Visual settings honored by the dashboard's embed renderer.","properties":{"background_type":{"type":"string","enum":["solid","image"],"description":"Solid color or image background."},"background_color":{"type":"string","description":"CSS hex/rgb string."},"form_color":{"type":"string","description":"Form panel background."},"text_color":{"type":"string"},"border_color":{"type":"string"},"logo_url":{"type":"string","format":"uri","description":"Absolute URL to a logo image (typically S3)."},"background_image_url":{"type":"string","format":"uri","description":"Absolute URL to a background image."}}},"FormInternalNotification":{"type":"object","description":"Notify internal staff by email whenever the form is submitted. Configured\nin the dashboard under the form's gear icon → Workflows tab. Legacy Mongo\ncolumns: `enable_notification` (int 0/1), `notification_email` (comma-joined\nrecipient list). At submit time the notification is dispatched by the\nlegacy `handlePostFormAction` worker if `notification_email` is non-empty.\n","properties":{"enabled":{"type":"boolean","description":"Whether the internal notification is turned on."},"recipient_emails":{"type":"array","items":{"type":"string","format":"email"},"description":"Staff email addresses to notify. Stored as a comma-joined string in the legacy field."}}},"FormEmbed":{"type":"object","description":"Copy-paste embed helpers. Server-generated URLs point at the dashboard's\nexisting form-render endpoints (`/form/embedView/{id}` for the iframe-friendly\nfull page, `/form/embedHtmlView/{id}` for the bare HTML variant). Renderer\nbase URL is env-configured via `GLEANTAP_DASHBOARD_BASE_URL`.\n","properties":{"iframe_url":{"type":"string","format":"uri"},"html_url":{"type":"string","format":"uri"},"iframe_snippet":{"type":"string","description":"Ready-to-paste `<iframe>` tag."},"script_snippet":{"type":"string","description":"Ready-to-paste `<div>` + `<script>` tag pair — for embedded rendering."}}},"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":{"/forms/{id}/rotate_submission_token":{"post":{"tags":["Forms"],"operationId":"rotateFormSubmissionToken","summary":"Rotate the form's submission_token.","description":"Mints a new plaintext `submission_token` and returns it once. The previous token stays valid for a 24-hour grace period — response includes `previous_submission_token_valid_until` to let callers coordinate a rolling switch.\n\n**Breaks live integrations.** Anything using the current secret stops working the moment this is called, until it is updated with the new one.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"Rotated. Store the new plaintext immediately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Form"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## GET /forms/{id}/submissions

> List submissions for a form (authenticated).

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Forms","description":"Web forms — public capture surface for turning anonymous visitors into contacts. Definitions carry field schema, custom CSS, tracking-code slots (head/body/on-submit), and design settings. Public submission is authenticated by a per-form `submission_token` (rotatable with a 24h grace window) — the only unauthenticated write surface in v3."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["forms:manage"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}}},"schemas":{"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"},"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`."}}},"FormSubmission":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/FormSubmissionId"},"object":{"type":"string","enum":["form_submission"]},"form_id":{"$ref":"#/components/schemas/FormId","nullable":true,"description":"Null for a landing page's own (non-form) submit."},"page_id":{"$ref":"#/components/schemas/PageId","nullable":true,"description":"Set when submitted through a landing page (`POST /pages/{id}/submissions`)."},"contact_id":{"$ref":"#/components/schemas/ContactId"},"values":{"type":"object","description":"Raw submitted key→value map. Keys are `FormField.key`s.","additionalProperties":true},"ip":{"type":"string","nullable":true},"user_agent":{"type":"string","nullable":true},"referrer":{"type":"string","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"FormSubmissionId":{"type":"string","pattern":"^fsm_[0-9a-f]{24}(_[0-9]+)?$","description":"A v3 submission is fsm_<24-hex>. A submission made through the legacy dashboard submit (e.g. checkout pages) is fsm_<contact 24-hex>_<index>."},"FormId":{"type":"string","pattern":"^fom_[0-9a-f]{24}$"},"PageId":{"type":"string","pattern":"^pg_[0-9a-fA-F]{24}$","description":"Landing page ID."},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/forms/{id}/submissions":{"get":{"tags":["Forms"],"operationId":"listFormSubmissions","summary":"List submissions for a form (authenticated).","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"type":"object","properties":{"contact_id":{"$ref":"#/components/schemas/ContactId"}}}}],"responses":{"200":{"description":"A page of submissions.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FormSubmission"}}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Public: submit a form.

> The ONLY unauthenticated write surface in v3. Auth is via \`submission\_token\` — supply it in the query string (\`?submission\_token=...\`), \`X-Gleantap-Form-Token\` header, OR a \`submission\_token\` body field. Bearer auth is NOT accepted on this endpoint.\
> \
> On success, the same records the dashboard's own form submit writes: (a) the contact is matched in the form's workroom as the dashboard matches it — by email, then by phone, each also requiring the submitted first name (case-insensitive) when one is given — or created as a prospect (\`accountinfo.prospect: 1\`, \`member: 0\`, \`type: "prospect"\`; a matched contact with none of these set gets the same). \`gender\` / \`city\` / \`state\` values are also mirrored to \`personalinfo\`. Empty values never overwrite what the contact has; (b) \`userdetails.form\[]\` history row (with \`form\_name\`), \`data.source\` (\`"Custom Form"\` unless the submission carries \`source\` / \`utm\_source\`), \`data.form\_id\`, \`data.source\_form\_name\[]\` appended, and \`accountinfo.source\` merged; (c) the contact is added to the form's "Has Filled a Form" segment only if it also meets any extra conditions added to that segment; (d) when the contact is in that segment, the dashboard's per-contact follow-ups are triggered on the cron hosts: enrollment in ongoing flows that start from the segment, the segment's ongoing campaigns, pipeline stage criteria and sales automations; the form's \`lead\_count\` / \`last\_lead\_date\` are refreshed; (e) the form's enabled post-submit actions run before the response returns, each recorded as a \`formpostactions\` row (\`v3\_api: 1\`) with its outcome (\`status\` \`success\` / \`failed\`, \`error\`, \`processed\_at\`):\
> \
> \- \*\*internal notification\*\* — the dashboard's "New Form Submission" email (field labels and values, link to the leads list) to \`internal\_notification.recipient\_emails\`, from <support@gleantap.com>, Reply-To the submitted \`email\`;\
> \- \*\*auto-response\*\* — the configured email (workroom sender, merge tags rendered for the contact) or SMS (workroom default number; links become tracked short links, \`{field}\` filled from the contact) to the submitter, written to the inbox like the dashboard's. Skipped (\`failed\` with the reason) when the contact opted out of that channel, when the workroom only sends SMS to opted-in contacts and this one is not, or when SMS credits are exhausted;\
> \- \*\*webhook\*\* — the submitted fields plus \`\_id\` (contact id) to \`webhook\_url\`, as JSON or form-encoded POST or a GET query string, the dashboard's format; signatures and captcha tokens are not sent;\
> \- \*\*MINDBODY lead\*\* — a client created at the configured site/location with the mapped fields (plus the drawn signature as a client document).\
> \
> A failed action never fails the submission or the other actions. Network calls have short timeouts (webhook 6 s, MINDBODY 8 s); (f) the submission is written to \`v3\_form\_submissions\` and a \`form.submitted\` externalevent is emitted for flow triggers.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Forms","description":"Web forms — public capture surface for turning anonymous visitors into contacts. Definitions carry field schema, custom CSS, tracking-code slots (head/body/on-submit), and design settings. Public submission is authenticated by a per-form `submission_token` (rotatable with a 24h grace window) — the only unauthenticated write surface in v3."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[],"paths":{"/forms/{id}/submissions":{"post":{"tags":["Forms"],"operationId":"submitForm","summary":"Public: submit a form.","description":"The ONLY unauthenticated write surface in v3. Auth is via `submission_token` — supply it in the query string (`?submission_token=...`), `X-Gleantap-Form-Token` header, OR a `submission_token` body field. Bearer auth is NOT accepted on this endpoint.\n\nOn success, the same records the dashboard's own form submit writes: (a) the contact is matched in the form's workroom as the dashboard matches it — by email, then by phone, each also requiring the submitted first name (case-insensitive) when one is given — or created as a prospect (`accountinfo.prospect: 1`, `member: 0`, `type: \"prospect\"`; a matched contact with none of these set gets the same). `gender` / `city` / `state` values are also mirrored to `personalinfo`. Empty values never overwrite what the contact has; (b) `userdetails.form[]` history row (with `form_name`), `data.source` (`\"Custom Form\"` unless the submission carries `source` / `utm_source`), `data.form_id`, `data.source_form_name[]` appended, and `accountinfo.source` merged; (c) the contact is added to the form's \"Has Filled a Form\" segment only if it also meets any extra conditions added to that segment; (d) when the contact is in that segment, the dashboard's per-contact follow-ups are triggered on the cron hosts: enrollment in ongoing flows that start from the segment, the segment's ongoing campaigns, pipeline stage criteria and sales automations; the form's `lead_count` / `last_lead_date` are refreshed; (e) the form's enabled post-submit actions run before the response returns, each recorded as a `formpostactions` row (`v3_api: 1`) with its outcome (`status` `success` / `failed`, `error`, `processed_at`):\n\n- **internal notification** — the dashboard's \"New Form Submission\" email (field labels and values, link to the leads list) to `internal_notification.recipient_emails`, from support@gleantap.com, Reply-To the submitted `email`;\n- **auto-response** — the configured email (workroom sender, merge tags rendered for the contact) or SMS (workroom default number; links become tracked short links, `{field}` filled from the contact) to the submitter, written to the inbox like the dashboard's. Skipped (`failed` with the reason) when the contact opted out of that channel, when the workroom only sends SMS to opted-in contacts and this one is not, or when SMS credits are exhausted;\n- **webhook** — the submitted fields plus `_id` (contact id) to `webhook_url`, as JSON or form-encoded POST or a GET query string, the dashboard's format; signatures and captcha tokens are not sent;\n- **MINDBODY lead** — a client created at the configured site/location with the mapped fields (plus the drawn signature as a client document).\n\nA failed action never fails the submission or the other actions. Network calls have short timeouts (webhook 6 s, MINDBODY 8 s); (f) the submission is written to `v3_form_submissions` and a `form.submitted` externalevent is emitted for flow triggers.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"name":"submission_token","in":"query","required":false,"schema":{"type":"string"},"description":"The form's current submission_token. Preferred over header + body forms."},{"name":"X-Gleantap-Form-Token","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormSubmissionCreate"}}}},"responses":{"201":{"description":"Submission recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormSubmission"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Missing or invalid `submission_token`, or the form is unpublished. Deliberately does not disclose which — treat as \"cannot submit\".","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"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":{"FormSubmissionCreate":{"type":"object","description":"Public submission payload. Auth is via `submission_token` (query string\n`?submission_token=...`, `X-Gleantap-Form-Token` header, OR a\n`submission_token` body field). Bearer auth is NOT accepted on this endpoint.\n","properties":{"submission_token":{"type":"string","description":"The form's current submission_token. Prefer the query-string or header form; body form is a fallback for CORS-restricted clients."},"values":{"type":"object","description":"Field key → submitted value map. See `FormField`'s \"Consent (`optin` / `opt_in`)\" note for the reserved `optin`/`opt_in` keys.","additionalProperties":true}}},"FormSubmission":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/FormSubmissionId"},"object":{"type":"string","enum":["form_submission"]},"form_id":{"$ref":"#/components/schemas/FormId","nullable":true,"description":"Null for a landing page's own (non-form) submit."},"page_id":{"$ref":"#/components/schemas/PageId","nullable":true,"description":"Set when submitted through a landing page (`POST /pages/{id}/submissions`)."},"contact_id":{"$ref":"#/components/schemas/ContactId"},"values":{"type":"object","description":"Raw submitted key→value map. Keys are `FormField.key`s.","additionalProperties":true},"ip":{"type":"string","nullable":true},"user_agent":{"type":"string","nullable":true},"referrer":{"type":"string","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"FormSubmissionId":{"type":"string","pattern":"^fsm_[0-9a-f]{24}(_[0-9]+)?$","description":"A v3 submission is fsm_<24-hex>. A submission made through the legacy dashboard submit (e.g. checkout pages) is fsm_<contact 24-hex>_<index>."},"FormId":{"type":"string","pattern":"^fom_[0-9a-f]{24}$"},"PageId":{"type":"string","pattern":"^pg_[0-9a-fA-F]{24}$","description":"Landing page ID."},"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"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}
```

## GET /forms/{id}/sharing

> Read a form's sharing configuration.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Forms","description":"Web forms — public capture surface for turning anonymous visitors into contacts. Definitions carry field schema, custom CSS, tracking-code slots (head/body/on-submit), and design settings. Public submission is authenticated by a per-form `submission_token` (rotatable with a 24h grace window) — the only unauthenticated write surface in v3."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["forms:manage"]}],"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":{"FormSharing":{"type":"object","properties":{"object":{"type":"string","const":"form_sharing"},"form_id":{"$ref":"#/components/schemas/FormId"},"allowed_roles":{"type":"object","description":"Boolean map keyed by role. Accepted keys: `me`, `Admin`, `WorkroomAdmin`, `Marketing`, `Sales`, `Analyst`, `Other`. Unknown keys are dropped on write. Missing keys read as false.\n","additionalProperties":{"type":"boolean"}},"other_allowed_user_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"}},"role_updated_on":{"type":"string","format":"date-time","nullable":true}}},"FormId":{"type":"string","pattern":"^fom_[0-9a-f]{24}$"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"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":{"/forms/{id}/sharing":{"get":{"tags":["Forms"],"operationId":"retrieveFormSharing","summary":"Read a form's sharing configuration.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"Sharing config.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormSharing"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Replace a form's sharing configuration.

> Full-replace (matches the dashboard's checkbox POST — unchecked boxes just don't appear). Accepted role keys: \`me\`, \`Admin\`, \`WorkroomAdmin\`, \`Marketing\`, \`Sales\`, \`Analyst\`, \`Other\`. When \`Other\` is true, \`other\_allowed\_user\_ids\[]\` must contain at least one valid staff ID or 400 is returned.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Forms","description":"Web forms — public capture surface for turning anonymous visitors into contacts. Definitions carry field schema, custom CSS, tracking-code slots (head/body/on-submit), and design settings. Public submission is authenticated by a per-form `submission_token` (rotatable with a 24h grace window) — the only unauthenticated write surface in v3."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["forms:manage"]}],"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":{"FormSharingUpdate":{"type":"object","properties":{"allowed_roles":{"type":"object","additionalProperties":{"type":"boolean"}},"other_allowed_user_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"Required (non-empty) when `allowed_roles.Other` is true; otherwise ignored."}}},"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."},"FormSharing":{"type":"object","properties":{"object":{"type":"string","const":"form_sharing"},"form_id":{"$ref":"#/components/schemas/FormId"},"allowed_roles":{"type":"object","description":"Boolean map keyed by role. Accepted keys: `me`, `Admin`, `WorkroomAdmin`, `Marketing`, `Sales`, `Analyst`, `Other`. Unknown keys are dropped on write. Missing keys read as false.\n","additionalProperties":{"type":"boolean"}},"other_allowed_user_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"}},"role_updated_on":{"type":"string","format":"date-time","nullable":true}}},"FormId":{"type":"string","pattern":"^fom_[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"}}}},"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/forms/{id}/sharing":{"put":{"tags":["Forms"],"operationId":"updateFormSharing","summary":"Replace a form's sharing configuration.","description":"Full-replace (matches the dashboard's checkbox POST — unchecked boxes just don't appear). Accepted role keys: `me`, `Admin`, `WorkroomAdmin`, `Marketing`, `Sales`, `Analyst`, `Other`. When `Other` is true, `other_allowed_user_ids[]` must contain at least one valid staff ID or 400 is returned.\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/FormSharingUpdate"}}}},"responses":{"200":{"description":"Updated sharing config.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormSharing"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## GET /form\_submissions/{id}

> Retrieve a single form submission.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Forms","description":"Web forms — public capture surface for turning anonymous visitors into contacts. Definitions carry field schema, custom CSS, tracking-code slots (head/body/on-submit), and design settings. Public submission is authenticated by a per-form `submission_token` (rotatable with a 24h grace window) — the only unauthenticated write surface in v3."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["forms:manage"]}],"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":{"FormSubmission":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/FormSubmissionId"},"object":{"type":"string","enum":["form_submission"]},"form_id":{"$ref":"#/components/schemas/FormId","nullable":true,"description":"Null for a landing page's own (non-form) submit."},"page_id":{"$ref":"#/components/schemas/PageId","nullable":true,"description":"Set when submitted through a landing page (`POST /pages/{id}/submissions`)."},"contact_id":{"$ref":"#/components/schemas/ContactId"},"values":{"type":"object","description":"Raw submitted key→value map. Keys are `FormField.key`s.","additionalProperties":true},"ip":{"type":"string","nullable":true},"user_agent":{"type":"string","nullable":true},"referrer":{"type":"string","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"FormSubmissionId":{"type":"string","pattern":"^fsm_[0-9a-f]{24}(_[0-9]+)?$","description":"A v3 submission is fsm_<24-hex>. A submission made through the legacy dashboard submit (e.g. checkout pages) is fsm_<contact 24-hex>_<index>."},"FormId":{"type":"string","pattern":"^fom_[0-9a-f]{24}$"},"PageId":{"type":"string","pattern":"^pg_[0-9a-fA-F]{24}$","description":"Landing page ID."},"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"},"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":{"/form_submissions/{id}":{"get":{"tags":["Forms"],"operationId":"retrieveFormSubmission","summary":"Retrieve a single form submission.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"The submission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormSubmission"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
