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.
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.
Keys 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.
For per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.
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.
Page size. Default 25, max 100.
25Opaque 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.
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.
2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$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.
A 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.
Every 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=.
acc_59fca1e3d2a57d28a10b0442Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (wrm_<hex>), a raw 24-hex ID, or the literal all.
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.
The 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.
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.
Also settable via ?workroom= or a workroom body field (POST/PATCH only) β query wins over header wins over body.
G Test1A page of forms.
True if additional records exist beyond this page.
Opaque cursor for the next page. Null on the last page.
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.
GET /v3/forms HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
A page of forms.
{
"object": "text",
"data": [
{
"id": "fom_6a616204a33b04c59a01f7f2",
"object": "form",
"name": "text",
"title": "text",
"subtitle": "text",
"slug": "text",
"status": "draft",
"fields": [
{
"type": "text",
"name": "text",
"label": "text",
"required": false,
"placeholder": "text",
"className": "text",
"subtype": "text",
"multiple": false,
"inline": false,
"toggle": false,
"other": false,
"requireValidOption": false,
"style": "text",
"value": "text",
"stars": 5,
"access": false,
"values": [
{
"label": "text",
"value": "text",
"selected": false
}
]
}
],
"action": "thankyou",
"action_value": "text",
"custom_css": "text",
"tracking_codes": {
"head": "text",
"body": "text",
"form_submission": "text"
},
"design": {
"background_type": "solid",
"background_color": "text",
"form_color": "text",
"text_color": "text",
"border_color": "text",
"logo_url": "https://example.com",
"background_image_url": "https://example.com"
},
"internal_notification": {
"enabled": true,
"recipient_emails": [
"[email protected]"
]
},
"embed": {
"iframe_url": "https://example.com",
"html_url": "https://example.com",
"iframe_snippet": "text",
"script_snippet": "text"
},
"submission_count": 1,
"submission_token_last4": "text",
"submission_token": "text",
"previous_submission_token_valid_until": "2026-01-01T00:00:00.000Z",
"last_submission_at": "2026-05-27T14:23:11.482Z",
"created_at": "2026-05-27T14:23:11.482Z",
"updated_at": "2026-05-27T14:23:11.482Z",
"published_at": "2026-05-27T14:23:11.482Z"
}
],
"has_more": true,
"next_cursor": "text",
"prev_cursor": "text"
}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.
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.
Keys 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.
For per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.
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.
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.
2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$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.
A 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.
Every 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=.
acc_59fca1e3d2a57d28a10b0442Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (wrm_<hex>), a raw 24-hex ID, or the literal all.
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.
The 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.
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.
Also settable via ?workroom= or a workroom body field (POST/PATCH only) β query wins over header wins over body.
G Test1A 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.
8e3c7a90-7c4d-4f8e-8e3c-7a907c4d4f8eAuto-generated from name if omitted.
What happens after a successful submission. Ask the user which of these they want β do not silently default without asking:
thankyouβ a generic built-in thank-you screen. The default ifactionis omitted entirely; noaction_valueneeded.messageβ a custom confirmation message. Provideaction_valuewith the text; if you omitaction_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.redirectβ send the visitor to a URL after submitting. Provideaction_valuewith the destination URL.
The confirmation message text (when action: message) or the redirect URL (when action: redirect). Unused when action: thankyou.
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.
Publish immediately if true. Defaults to false (draft).
Form created.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$Internal name (dashboard label).
Rendered heading shown to submitters.
URL-safe identifier auto-generated from name if omitted.
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.
What happens after the submitter clicks submit.
Companion to action β redirect URL, thank-you message text, etc.
Raw CSS injected into the form's <style> block on render. Legacy column: additional_css.
Total submissions to date.
Last 4 chars of the current submission_token. Full plaintext is returned ONLY at publish and rotate.
Full plaintext submission_token. Returned ONLY as a one-shot on:
POST /forms(create), when the request setis_published: trueβ a form created already-published gets a token minted immediately, the same as if it had been published separately right after.POST /forms/{id}/publish(first publish)POST /forms/{id}/rotate_submission_tokenStore it immediately; you cannot retrieve it again. If lost, rotate.
Rotate response only β timestamp at which the previously-issued token stops accepting submissions (default 24h grace).
RFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRequest could not be parsed or failed validation.
Semantic validation failed β the request is well-formed but references an object in the wrong state (e.g., sending to an opted-out contact).
POST /v3/forms HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 831
{
"name": "text",
"title": "text",
"subtitle": "text",
"slug": "text",
"fields": [
{
"type": "text",
"name": "text",
"label": "text",
"required": false,
"placeholder": "text",
"className": "text",
"subtype": "text",
"multiple": false,
"inline": false,
"toggle": false,
"other": false,
"requireValidOption": false,
"style": "text",
"value": "text",
"stars": 5,
"access": false,
"values": [
{
"label": "text",
"value": "text",
"selected": false
}
]
}
],
"action": "thankyou",
"action_value": "text",
"custom_css": "text",
"tracking_codes": {
"head": "text",
"body": "text",
"form_submission": "text"
},
"design": {
"background_type": "solid",
"background_color": "text",
"form_color": "text",
"text_color": "text",
"border_color": "text",
"logo_url": "https://example.com",
"background_image_url": "https://example.com"
},
"internal_notification": {
"enabled": true,
"recipient_emails": [
"[email protected]"
]
},
"is_published": true
}{
"id": "fom_6a616204a33b04c59a01f7f2",
"object": "form",
"name": "text",
"title": "text",
"subtitle": "text",
"slug": "text",
"status": "draft",
"fields": [
{
"type": "text",
"name": "text",
"label": "text",
"required": false,
"placeholder": "text",
"className": "text",
"subtype": "text",
"multiple": false,
"inline": false,
"toggle": false,
"other": false,
"requireValidOption": false,
"style": "text",
"value": "text",
"stars": 5,
"access": false,
"values": [
{
"label": "text",
"value": "text",
"selected": false
}
]
}
],
"action": "thankyou",
"action_value": "text",
"custom_css": "text",
"tracking_codes": {
"head": "text",
"body": "text",
"form_submission": "text"
},
"design": {
"background_type": "solid",
"background_color": "text",
"form_color": "text",
"text_color": "text",
"border_color": "text",
"logo_url": "https://example.com",
"background_image_url": "https://example.com"
},
"internal_notification": {
"enabled": true,
"recipient_emails": [
"[email protected]"
]
},
"embed": {
"iframe_url": "https://example.com",
"html_url": "https://example.com",
"iframe_snippet": "text",
"script_snippet": "text"
},
"submission_count": 1,
"submission_token_last4": "text",
"submission_token": "text",
"previous_submission_token_valid_until": "2026-01-01T00:00:00.000Z",
"last_submission_at": "2026-05-27T14:23:11.482Z",
"created_at": "2026-05-27T14:23:11.482Z",
"updated_at": "2026-05-27T14:23:11.482Z",
"published_at": "2026-05-27T14:23:11.482Z"
}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.
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.
Keys 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.
For per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$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.
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.
2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$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.
A 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.
Every 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=.
acc_59fca1e3d2a57d28a10b0442Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (wrm_<hex>), a raw 24-hex ID, or the literal all.
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.
The 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.
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.
Also settable via ?workroom= or a workroom body field (POST/PATCH only) β query wins over header wins over body.
G Test1Form.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$Internal name (dashboard label).
Rendered heading shown to submitters.
URL-safe identifier auto-generated from name if omitted.
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.
What happens after the submitter clicks submit.
Companion to action β redirect URL, thank-you message text, etc.
Raw CSS injected into the form's <style> block on render. Legacy column: additional_css.
Total submissions to date.
Last 4 chars of the current submission_token. Full plaintext is returned ONLY at publish and rotate.
Full plaintext submission_token. Returned ONLY as a one-shot on:
POST /forms(create), when the request setis_published: trueβ a form created already-published gets a token minted immediately, the same as if it had been published separately right after.POST /forms/{id}/publish(first publish)POST /forms/{id}/rotate_submission_tokenStore it immediately; you cannot retrieve it again. If lost, rotate.
Rotate response only β timestamp at which the previously-issued token stops accepting submissions (default 24h grace).
RFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZThe resource doesn't exist or isn't visible to this caller.
GET /v3/forms/{id} HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "fom_6a616204a33b04c59a01f7f2",
"object": "form",
"name": "text",
"title": "text",
"subtitle": "text",
"slug": "text",
"status": "draft",
"fields": [
{
"type": "text",
"name": "text",
"label": "text",
"required": false,
"placeholder": "text",
"className": "text",
"subtype": "text",
"multiple": false,
"inline": false,
"toggle": false,
"other": false,
"requireValidOption": false,
"style": "text",
"value": "text",
"stars": 5,
"access": false,
"values": [
{
"label": "text",
"value": "text",
"selected": false
}
]
}
],
"action": "thankyou",
"action_value": "text",
"custom_css": "text",
"tracking_codes": {
"head": "text",
"body": "text",
"form_submission": "text"
},
"design": {
"background_type": "solid",
"background_color": "text",
"form_color": "text",
"text_color": "text",
"border_color": "text",
"logo_url": "https://example.com",
"background_image_url": "https://example.com"
},
"internal_notification": {
"enabled": true,
"recipient_emails": [
"[email protected]"
]
},
"embed": {
"iframe_url": "https://example.com",
"html_url": "https://example.com",
"iframe_snippet": "text",
"script_snippet": "text"
},
"submission_count": 1,
"submission_token_last4": "text",
"submission_token": "text",
"previous_submission_token_valid_until": "2026-01-01T00:00:00.000Z",
"last_submission_at": "2026-05-27T14:23:11.482Z",
"created_at": "2026-05-27T14:23:11.482Z",
"updated_at": "2026-05-27T14:23:11.482Z",
"published_at": "2026-05-27T14:23:11.482Z"
}Partial patch. tracking_codes and design are merged per-key β supply only the values to change.
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.
Keys 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.
For per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$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.
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.
2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$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.
A 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.
Every 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=.
acc_59fca1e3d2a57d28a10b0442Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (wrm_<hex>), a raw 24-hex ID, or the literal all.
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.
The 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.
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.
Also settable via ?workroom= or a workroom body field (POST/PATCH only) β query wins over header wins over body.
G Test1PATCH β supply only the fields to change. Partial tracking_codes and design are merged.
Updated form.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$Internal name (dashboard label).
Rendered heading shown to submitters.
URL-safe identifier auto-generated from name if omitted.
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.
What happens after the submitter clicks submit.
Companion to action β redirect URL, thank-you message text, etc.
Raw CSS injected into the form's <style> block on render. Legacy column: additional_css.
Total submissions to date.
Last 4 chars of the current submission_token. Full plaintext is returned ONLY at publish and rotate.
Full plaintext submission_token. Returned ONLY as a one-shot on:
POST /forms(create), when the request setis_published: trueβ a form created already-published gets a token minted immediately, the same as if it had been published separately right after.POST /forms/{id}/publish(first publish)POST /forms/{id}/rotate_submission_tokenStore it immediately; you cannot retrieve it again. If lost, rotate.
Rotate response only β timestamp at which the previously-issued token stops accepting submissions (default 24h grace).
RFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZThe resource doesn't exist or isn't visible to this caller.
PATCH /v3/forms/{id} HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 811
{
"name": "text",
"title": "text",
"subtitle": "text",
"slug": "text",
"fields": [
{
"type": "text",
"name": "text",
"label": "text",
"required": false,
"placeholder": "text",
"className": "text",
"subtype": "text",
"multiple": false,
"inline": false,
"toggle": false,
"other": false,
"requireValidOption": false,
"style": "text",
"value": "text",
"stars": 5,
"access": false,
"values": [
{
"label": "text",
"value": "text",
"selected": false
}
]
}
],
"action": "thankyou",
"action_value": "text",
"custom_css": "text",
"tracking_codes": {
"head": "text",
"body": "text",
"form_submission": "text"
},
"design": {
"background_type": "solid",
"background_color": "text",
"form_color": "text",
"text_color": "text",
"border_color": "text",
"logo_url": "https://example.com",
"background_image_url": "https://example.com"
},
"internal_notification": {
"enabled": true,
"recipient_emails": [
"[email protected]"
]
}
}{
"id": "fom_6a616204a33b04c59a01f7f2",
"object": "form",
"name": "text",
"title": "text",
"subtitle": "text",
"slug": "text",
"status": "draft",
"fields": [
{
"type": "text",
"name": "text",
"label": "text",
"required": false,
"placeholder": "text",
"className": "text",
"subtype": "text",
"multiple": false,
"inline": false,
"toggle": false,
"other": false,
"requireValidOption": false,
"style": "text",
"value": "text",
"stars": 5,
"access": false,
"values": [
{
"label": "text",
"value": "text",
"selected": false
}
]
}
],
"action": "thankyou",
"action_value": "text",
"custom_css": "text",
"tracking_codes": {
"head": "text",
"body": "text",
"form_submission": "text"
},
"design": {
"background_type": "solid",
"background_color": "text",
"form_color": "text",
"text_color": "text",
"border_color": "text",
"logo_url": "https://example.com",
"background_image_url": "https://example.com"
},
"internal_notification": {
"enabled": true,
"recipient_emails": [
"[email protected]"
]
},
"embed": {
"iframe_url": "https://example.com",
"html_url": "https://example.com",
"iframe_snippet": "text",
"script_snippet": "text"
},
"submission_count": 1,
"submission_token_last4": "text",
"submission_token": "text",
"previous_submission_token_valid_until": "2026-01-01T00:00:00.000Z",
"last_submission_at": "2026-05-27T14:23:11.482Z",
"created_at": "2026-05-27T14:23:11.482Z",
"updated_at": "2026-05-27T14:23:11.482Z",
"published_at": "2026-05-27T14:23:11.482Z"
}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.
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.
Keys 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.
For per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$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.
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.
2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$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.
A 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.
Every 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=.
acc_59fca1e3d2a57d28a10b0442Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (wrm_<hex>), a raw 24-hex ID, or the literal all.
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.
The 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.
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.
Also settable via ?workroom= or a workroom body field (POST/PATCH only) β query wins over header wins over body.
G Test1Archived.
No content
The resource doesn't exist or isn't visible to this caller.
DELETE /v3/forms/{id} HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
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.
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.
Keys 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.
For per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$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.
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.
2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$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.
A 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.
Every 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=.
acc_59fca1e3d2a57d28a10b0442Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (wrm_<hex>), a raw 24-hex ID, or the literal all.
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.
The 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.
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.
Also settable via ?workroom= or a workroom body field (POST/PATCH only) β query wins over header wins over body.
G Test1Published. submission_token present ONLY on first publish.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$Internal name (dashboard label).
Rendered heading shown to submitters.
URL-safe identifier auto-generated from name if omitted.
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.
What happens after the submitter clicks submit.
Companion to action β redirect URL, thank-you message text, etc.
Raw CSS injected into the form's <style> block on render. Legacy column: additional_css.
Total submissions to date.
Last 4 chars of the current submission_token. Full plaintext is returned ONLY at publish and rotate.
Full plaintext submission_token. Returned ONLY as a one-shot on:
POST /forms(create), when the request setis_published: trueβ a form created already-published gets a token minted immediately, the same as if it had been published separately right after.POST /forms/{id}/publish(first publish)POST /forms/{id}/rotate_submission_tokenStore it immediately; you cannot retrieve it again. If lost, rotate.
Rotate response only β timestamp at which the previously-issued token stops accepting submissions (default 24h grace).
RFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZThe resource doesn't exist or isn't visible to this caller.
POST /v3/forms/{id}/publish HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "fom_6a616204a33b04c59a01f7f2",
"object": "form",
"name": "text",
"title": "text",
"subtitle": "text",
"slug": "text",
"status": "draft",
"fields": [
{
"type": "text",
"name": "text",
"label": "text",
"required": false,
"placeholder": "text",
"className": "text",
"subtype": "text",
"multiple": false,
"inline": false,
"toggle": false,
"other": false,
"requireValidOption": false,
"style": "text",
"value": "text",
"stars": 5,
"access": false,
"values": [
{
"label": "text",
"value": "text",
"selected": false
}
]
}
],
"action": "thankyou",
"action_value": "text",
"custom_css": "text",
"tracking_codes": {
"head": "text",
"body": "text",
"form_submission": "text"
},
"design": {
"background_type": "solid",
"background_color": "text",
"form_color": "text",
"text_color": "text",
"border_color": "text",
"logo_url": "https://example.com",
"background_image_url": "https://example.com"
},
"internal_notification": {
"enabled": true,
"recipient_emails": [
"[email protected]"
]
},
"embed": {
"iframe_url": "https://example.com",
"html_url": "https://example.com",
"iframe_snippet": "text",
"script_snippet": "text"
},
"submission_count": 1,
"submission_token_last4": "text",
"submission_token": "text",
"previous_submission_token_valid_until": "2026-01-01T00:00:00.000Z",
"last_submission_at": "2026-05-27T14:23:11.482Z",
"created_at": "2026-05-27T14:23:11.482Z",
"updated_at": "2026-05-27T14:23:11.482Z",
"published_at": "2026-05-27T14:23:11.482Z"
}New public submissions are rejected with 401 while unpublished. The submission_token is retained (not rotated) so publishing again resumes with the same token.
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.
Keys 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.
For per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$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.
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.
2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$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.
A 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.
Every 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=.
acc_59fca1e3d2a57d28a10b0442Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (wrm_<hex>), a raw 24-hex ID, or the literal all.
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.
The 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.
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.
Also settable via ?workroom= or a workroom body field (POST/PATCH only) β query wins over header wins over body.
G Test1Now in draft.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$Internal name (dashboard label).
Rendered heading shown to submitters.
URL-safe identifier auto-generated from name if omitted.
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.
What happens after the submitter clicks submit.
Companion to action β redirect URL, thank-you message text, etc.
Raw CSS injected into the form's <style> block on render. Legacy column: additional_css.
Total submissions to date.
Last 4 chars of the current submission_token. Full plaintext is returned ONLY at publish and rotate.
Full plaintext submission_token. Returned ONLY as a one-shot on:
POST /forms(create), when the request setis_published: trueβ a form created already-published gets a token minted immediately, the same as if it had been published separately right after.POST /forms/{id}/publish(first publish)POST /forms/{id}/rotate_submission_tokenStore it immediately; you cannot retrieve it again. If lost, rotate.
Rotate response only β timestamp at which the previously-issued token stops accepting submissions (default 24h grace).
RFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZThe resource doesn't exist or isn't visible to this caller.
POST /v3/forms/{id}/unpublish HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "fom_6a616204a33b04c59a01f7f2",
"object": "form",
"name": "text",
"title": "text",
"subtitle": "text",
"slug": "text",
"status": "draft",
"fields": [
{
"type": "text",
"name": "text",
"label": "text",
"required": false,
"placeholder": "text",
"className": "text",
"subtype": "text",
"multiple": false,
"inline": false,
"toggle": false,
"other": false,
"requireValidOption": false,
"style": "text",
"value": "text",
"stars": 5,
"access": false,
"values": [
{
"label": "text",
"value": "text",
"selected": false
}
]
}
],
"action": "thankyou",
"action_value": "text",
"custom_css": "text",
"tracking_codes": {
"head": "text",
"body": "text",
"form_submission": "text"
},
"design": {
"background_type": "solid",
"background_color": "text",
"form_color": "text",
"text_color": "text",
"border_color": "text",
"logo_url": "https://example.com",
"background_image_url": "https://example.com"
},
"internal_notification": {
"enabled": true,
"recipient_emails": [
"[email protected]"
]
},
"embed": {
"iframe_url": "https://example.com",
"html_url": "https://example.com",
"iframe_snippet": "text",
"script_snippet": "text"
},
"submission_count": 1,
"submission_token_last4": "text",
"submission_token": "text",
"previous_submission_token_valid_until": "2026-01-01T00:00:00.000Z",
"last_submission_at": "2026-05-27T14:23:11.482Z",
"created_at": "2026-05-27T14:23:11.482Z",
"updated_at": "2026-05-27T14:23:11.482Z",
"published_at": "2026-05-27T14:23:11.482Z"
}Copies fields, custom_css, tracking_codes, design. Does NOT copy the submission_token or submission_count β the duplicate starts fresh.
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.
Keys 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.
For per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$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.
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.
2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$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.
A 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.
Every 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=.
acc_59fca1e3d2a57d28a10b0442Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (wrm_<hex>), a raw 24-hex ID, or the literal all.
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.
The 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.
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.
Also settable via ?workroom= or a workroom body field (POST/PATCH only) β query wins over header wins over body.
G Test1Name for the duplicate. Defaults to {original name} (copy).
New draft form.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$Internal name (dashboard label).
Rendered heading shown to submitters.
URL-safe identifier auto-generated from name if omitted.
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.
What happens after the submitter clicks submit.
Companion to action β redirect URL, thank-you message text, etc.
Raw CSS injected into the form's <style> block on render. Legacy column: additional_css.
Total submissions to date.
Last 4 chars of the current submission_token. Full plaintext is returned ONLY at publish and rotate.
Full plaintext submission_token. Returned ONLY as a one-shot on:
POST /forms(create), when the request setis_published: trueβ a form created already-published gets a token minted immediately, the same as if it had been published separately right after.POST /forms/{id}/publish(first publish)POST /forms/{id}/rotate_submission_tokenStore it immediately; you cannot retrieve it again. If lost, rotate.
Rotate response only β timestamp at which the previously-issued token stops accepting submissions (default 24h grace).
RFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZThe resource doesn't exist or isn't visible to this caller.
POST /v3/forms/{id}/duplicate HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 15
{
"name": "text"
}{
"id": "fom_6a616204a33b04c59a01f7f2",
"object": "form",
"name": "text",
"title": "text",
"subtitle": "text",
"slug": "text",
"status": "draft",
"fields": [
{
"type": "text",
"name": "text",
"label": "text",
"required": false,
"placeholder": "text",
"className": "text",
"subtype": "text",
"multiple": false,
"inline": false,
"toggle": false,
"other": false,
"requireValidOption": false,
"style": "text",
"value": "text",
"stars": 5,
"access": false,
"values": [
{
"label": "text",
"value": "text",
"selected": false
}
]
}
],
"action": "thankyou",
"action_value": "text",
"custom_css": "text",
"tracking_codes": {
"head": "text",
"body": "text",
"form_submission": "text"
},
"design": {
"background_type": "solid",
"background_color": "text",
"form_color": "text",
"text_color": "text",
"border_color": "text",
"logo_url": "https://example.com",
"background_image_url": "https://example.com"
},
"internal_notification": {
"enabled": true,
"recipient_emails": [
"[email protected]"
]
},
"embed": {
"iframe_url": "https://example.com",
"html_url": "https://example.com",
"iframe_snippet": "text",
"script_snippet": "text"
},
"submission_count": 1,
"submission_token_last4": "text",
"submission_token": "text",
"previous_submission_token_valid_until": "2026-01-01T00:00:00.000Z",
"last_submission_at": "2026-05-27T14:23:11.482Z",
"created_at": "2026-05-27T14:23:11.482Z",
"updated_at": "2026-05-27T14:23:11.482Z",
"published_at": "2026-05-27T14:23:11.482Z"
}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.
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.
Keys 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.
For per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$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.
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.
2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$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.
A 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.
Every 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=.
acc_59fca1e3d2a57d28a10b0442Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (wrm_<hex>), a raw 24-hex ID, or the literal all.
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.
The 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.
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.
Also settable via ?workroom= or a workroom body field (POST/PATCH only) β query wins over header wins over body.
G Test1Rotated. Store the new plaintext immediately.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$Internal name (dashboard label).
Rendered heading shown to submitters.
URL-safe identifier auto-generated from name if omitted.
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.
What happens after the submitter clicks submit.
Companion to action β redirect URL, thank-you message text, etc.
Raw CSS injected into the form's <style> block on render. Legacy column: additional_css.
Total submissions to date.
Last 4 chars of the current submission_token. Full plaintext is returned ONLY at publish and rotate.
Full plaintext submission_token. Returned ONLY as a one-shot on:
POST /forms(create), when the request setis_published: trueβ a form created already-published gets a token minted immediately, the same as if it had been published separately right after.POST /forms/{id}/publish(first publish)POST /forms/{id}/rotate_submission_tokenStore it immediately; you cannot retrieve it again. If lost, rotate.
Rotate response only β timestamp at which the previously-issued token stops accepting submissions (default 24h grace).
RFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZThe resource doesn't exist or isn't visible to this caller.
POST /v3/forms/{id}/rotate_submission_token HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "fom_6a616204a33b04c59a01f7f2",
"object": "form",
"name": "text",
"title": "text",
"subtitle": "text",
"slug": "text",
"status": "draft",
"fields": [
{
"type": "text",
"name": "text",
"label": "text",
"required": false,
"placeholder": "text",
"className": "text",
"subtype": "text",
"multiple": false,
"inline": false,
"toggle": false,
"other": false,
"requireValidOption": false,
"style": "text",
"value": "text",
"stars": 5,
"access": false,
"values": [
{
"label": "text",
"value": "text",
"selected": false
}
]
}
],
"action": "thankyou",
"action_value": "text",
"custom_css": "text",
"tracking_codes": {
"head": "text",
"body": "text",
"form_submission": "text"
},
"design": {
"background_type": "solid",
"background_color": "text",
"form_color": "text",
"text_color": "text",
"border_color": "text",
"logo_url": "https://example.com",
"background_image_url": "https://example.com"
},
"internal_notification": {
"enabled": true,
"recipient_emails": [
"[email protected]"
]
},
"embed": {
"iframe_url": "https://example.com",
"html_url": "https://example.com",
"iframe_snippet": "text",
"script_snippet": "text"
},
"submission_count": 1,
"submission_token_last4": "text",
"submission_token": "text",
"previous_submission_token_valid_until": "2026-01-01T00:00:00.000Z",
"last_submission_at": "2026-05-27T14:23:11.482Z",
"created_at": "2026-05-27T14:23:11.482Z",
"updated_at": "2026-05-27T14:23:11.482Z",
"published_at": "2026-05-27T14:23:11.482Z"
}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.
Keys 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.
For per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$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.
Page size. Default 25, max 100.
25Opaque 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.
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.
2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$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.
A 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.
Every 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=.
acc_59fca1e3d2a57d28a10b0442Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (wrm_<hex>), a raw 24-hex ID, or the literal all.
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.
The 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.
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.
Also settable via ?workroom= or a workroom body field (POST/PATCH only) β query wins over header wins over body.
G Test1A page of submissions.
True if additional records exist beyond this page.
Opaque cursor for the next page. Null on the last page.
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.
The resource doesn't exist or isn't visible to this caller.
GET /v3/forms/{id}/submissions HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"object": "text",
"data": [
{
"id": "fsm_6a616226a33b04c59a01f7f4",
"object": "form_submission",
"form_id": "fom_6a616204a33b04c59a01f7f2",
"page_id": "pg_66d9a11d0e5b7c1a4d8e2f1b",
"contact_id": "con_6a7eaec3505bea795709f897",
"values": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"ip": "text",
"user_agent": "text",
"referrer": "text",
"created_at": "2026-05-27T14:23:11.482Z"
}
],
"has_more": true,
"next_cursor": "text",
"prev_cursor": "text"
}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 [email protected], Reply-To the submittedemail;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 (failedwith 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) towebhook_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.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$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.
The form's current submission_token. Preferred over header + body forms.
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.
2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$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.
A 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.
Every 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=.
acc_59fca1e3d2a57d28a10b0442Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (wrm_<hex>), a raw 24-hex ID, or the literal all.
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.
The 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.
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.
Also settable via ?workroom= or a workroom body field (POST/PATCH only) β query wins over header wins over body.
G Test1Public submission payload. Auth is via submission_token (query string
?submission_token=..., X-Gleantap-Form-Token header, OR a
submission_token body field). Bearer auth is NOT accepted on this endpoint.
The form's current submission_token. Prefer the query-string or header form; body form is a fallback for CORS-restricted clients.
Submission recorded.
A v3 submission is fsm_<24-hex>. A submission made through the legacy dashboard submit (e.g. checkout pages) is fsm_<contact 24-hex>_.
fsm_6a616226a33b04c59a01f7f4Pattern: ^fsm_[0-9a-f]{24}(_[0-9]+)?$Null for a landing page's own (non-form) submit.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$Set when submitted through a landing page (POST /pages/{id}/submissions).
pg_66d9a11d0e5b7c1a4d8e2f1bPattern: ^pg_[0-9a-fA-F]{24}$A contact ID. Accepts either the native prefixed id (con_<24-hex>) or an external-ID reference (external_id:<your_id>).
con_6a7eaec3505bea795709f897Pattern: ^con_[0-9a-f]{24}$|^external_id:[^/]+$RFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZRequest could not be parsed or failed validation.
Missing or invalid submission_token, or the form is unpublished. Deliberately does not disclose which β treat as "cannot submit".
POST /v3/forms/{id}/submissions HTTP/1.1
Host: api.gleantap.com
Content-Type: application/json
Accept: */*
Content-Length: 75
{
"submission_token": "text",
"values": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}{
"id": "fsm_6a616226a33b04c59a01f7f4",
"object": "form_submission",
"form_id": "fom_6a616204a33b04c59a01f7f2",
"page_id": "pg_66d9a11d0e5b7c1a4d8e2f1b",
"contact_id": "con_6a7eaec3505bea795709f897",
"values": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"ip": "text",
"user_agent": "text",
"referrer": "text",
"created_at": "2026-05-27T14:23:11.482Z"
}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.
Keys 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.
For per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$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.
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.
2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$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.
A 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.
Every 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=.
acc_59fca1e3d2a57d28a10b0442Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (wrm_<hex>), a raw 24-hex ID, or the literal all.
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.
The 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.
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.
Also settable via ?workroom= or a workroom body field (POST/PATCH only) β query wins over header wins over body.
G Test1Sharing config.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$A staff user (from the legacy users collection). Used for owner_id, responsible_id, created_by, assigned_to, etc.
The resource doesn't exist or isn't visible to this caller.
GET /v3/forms/{id}/sharing HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"object": "text",
"form_id": "fom_6a616204a33b04c59a01f7f2",
"allowed_roles": {
"ANY_ADDITIONAL_PROPERTY": true
},
"other_allowed_user_ids": [
"text"
],
"role_updated_on": "2026-01-01T00:00:00.000Z"
}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.
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.
Keys 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.
For per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$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.
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.
2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$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.
A 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.
Every 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=.
acc_59fca1e3d2a57d28a10b0442Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (wrm_<hex>), a raw 24-hex ID, or the literal all.
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.
The 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.
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.
Also settable via ?workroom= or a workroom body field (POST/PATCH only) β query wins over header wins over body.
G Test1Required (non-empty) when allowed_roles.Other is true; otherwise ignored.
Updated sharing config.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$A staff user (from the legacy users collection). Used for owner_id, responsible_id, created_by, assigned_to, etc.
Request could not be parsed or failed validation.
The resource doesn't exist or isn't visible to this caller.
PUT /v3/forms/{id}/sharing HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 84
{
"allowed_roles": {
"ANY_ADDITIONAL_PROPERTY": true
},
"other_allowed_user_ids": [
"text"
]
}{
"object": "text",
"form_id": "fom_6a616204a33b04c59a01f7f2",
"allowed_roles": {
"ANY_ADDITIONAL_PROPERTY": true
},
"other_allowed_user_ids": [
"text"
],
"role_updated_on": "2026-01-01T00:00:00.000Z"
}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.
Keys 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.
For per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.
A v3 submission is fsm_<24-hex>. A submission made through the legacy dashboard submit (e.g. checkout pages) is fsm_<contact 24-hex>_.
fsm_6a616226a33b04c59a01f7f4Pattern: ^fsm_[0-9a-f]{24}(_[0-9]+)?$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.
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.
2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$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.
A 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.
Every 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=.
acc_59fca1e3d2a57d28a10b0442Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (wrm_<hex>), a raw 24-hex ID, or the literal all.
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.
The 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.
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.
Also settable via ?workroom= or a workroom body field (POST/PATCH only) β query wins over header wins over body.
G Test1The submission.
A v3 submission is fsm_<24-hex>. A submission made through the legacy dashboard submit (e.g. checkout pages) is fsm_<contact 24-hex>_.
fsm_6a616226a33b04c59a01f7f4Pattern: ^fsm_[0-9a-f]{24}(_[0-9]+)?$Null for a landing page's own (non-form) submit.
fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$Set when submitted through a landing page (POST /pages/{id}/submissions).
pg_66d9a11d0e5b7c1a4d8e2f1bPattern: ^pg_[0-9a-fA-F]{24}$A contact ID. Accepts either the native prefixed id (con_<24-hex>) or an external-ID reference (external_id:<your_id>).
con_6a7eaec3505bea795709f897Pattern: ^con_[0-9a-f]{24}$|^external_id:[^/]+$RFC 3339 timestamp, always UTC, millisecond precision.
2026-05-27T14:23:11.482ZThe resource doesn't exist or isn't visible to this caller.
GET /v3/form_submissions/{id} HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "fsm_6a616226a33b04c59a01f7f4",
"object": "form_submission",
"form_id": "fom_6a616204a33b04c59a01f7f2",
"page_id": "pg_66d9a11d0e5b7c1a4d8e2f1b",
"contact_id": "con_6a7eaec3505bea795709f897",
"values": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"ip": "text",
"user_agent": "text",
"referrer": "text",
"created_at": "2026-05-27T14:23:11.482Z"
}