For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

List forms for the account.

get
Authorizations
AuthorizationstringRequired

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.

Query parameters
workroomstringOptional

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.

limitinteger Β· min: 1 Β· max: 100Optional

Page size. Default 25, max 100.

Default: 25
cursorstringOptional

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.

Header parameters
Gleantap-VersionstringOptional

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.

Example: 2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$
Gleantap-AccountstringOptional

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=.

Example: acc_59fca1e3d2a57d28a10b0442
Gleantap-WorkroomstringOptional

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.

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.

Example: G Test1
Responses
200

A page of forms.

application/json
objectconst: listRequired
has_morebooleanRequired

True if additional records exist beyond this page.

next_cursorstring Β· nullableRequired

Opaque cursor for the next page. Null on the last page.

prev_cursorstring Β· nullableRequired

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/forms
GET /v3/forms HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

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"
}

Create a form.

post

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.

Authorizations
AuthorizationstringRequired

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.

Query parameters
workroomstringOptional

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.

Header parameters
Gleantap-VersionstringOptional

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.

Example: 2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$
Gleantap-AccountstringOptional

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=.

Example: acc_59fca1e3d2a57d28a10b0442
Gleantap-WorkroomstringOptional

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.

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.

Example: G Test1
Idempotency-Keystring Β· max: 255Optional

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.

Example: 8e3c7a90-7c4d-4f8e-8e3c-7a907c4d4f8e
Body
namestringRequired
titlestringOptional
subtitlestringOptional
slugstringOptional

Auto-generated from name if omitted.

actionstring Β· enumOptional

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 if action is omitted entirely; no action_value needed.
  • 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.
  • redirect β€” send the visitor to a URL after submitting. Provide action_value with the destination URL.
Possible values:
action_valuestringOptional

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.

custom_cssstringOptional
is_publishedbooleanOptional

Publish immediately if true. Defaults to false (draft).

Responses
201

Form created.

application/json
idstringOptionalExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
objectstring Β· enumOptionalPossible values:
namestringOptional

Internal name (dashboard label).

titlestringOptional

Rendered heading shown to submitters.

subtitlestringOptional
slugstringOptional

URL-safe identifier auto-generated from name if omitted.

statusstring Β· enumOptional

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.

Possible values:
actionstring Β· enumOptional

What happens after the submitter clicks submit.

Possible values:
action_valuestringOptional

Companion to action β€” redirect URL, thank-you message text, etc.

custom_cssstringOptional

Raw CSS injected into the form's <style> block on render. Legacy column: additional_css.

submission_countintegerOptional

Total submissions to date.

submission_token_last4string Β· nullableOptional

Last 4 chars of the current submission_token. Full plaintext is returned ONLY at publish and rotate.

submission_tokenstringOptional

Full plaintext submission_token. Returned ONLY as a one-shot on:

  • 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.
  • POST /forms/{id}/publish (first publish)
  • POST /forms/{id}/rotate_submission_token Store it immediately; you cannot retrieve it again. If lost, rotate.
previous_submission_token_valid_untilstring Β· date-timeOptional

Rotate response only β€” timestamp at which the previously-issued token stops accepting submissions (default 24h grace).

last_submission_atstring Β· date-time Β· nullableOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
created_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
updated_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
published_atstring Β· date-time Β· nullableOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
post/forms
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"
}

Retrieve a form.

get

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.

Authorizations
AuthorizationstringRequired

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.

Path parameters
idstringRequiredExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
Query parameters
workroomstringOptional

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.

Header parameters
Gleantap-VersionstringOptional

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.

Example: 2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$
Gleantap-AccountstringOptional

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=.

Example: acc_59fca1e3d2a57d28a10b0442
Gleantap-WorkroomstringOptional

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.

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.

Example: G Test1
Responses
200

Form.

application/json
idstringOptionalExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
objectstring Β· enumOptionalPossible values:
namestringOptional

Internal name (dashboard label).

titlestringOptional

Rendered heading shown to submitters.

subtitlestringOptional
slugstringOptional

URL-safe identifier auto-generated from name if omitted.

statusstring Β· enumOptional

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.

Possible values:
actionstring Β· enumOptional

What happens after the submitter clicks submit.

Possible values:
action_valuestringOptional

Companion to action β€” redirect URL, thank-you message text, etc.

custom_cssstringOptional

Raw CSS injected into the form's <style> block on render. Legacy column: additional_css.

submission_countintegerOptional

Total submissions to date.

submission_token_last4string Β· nullableOptional

Last 4 chars of the current submission_token. Full plaintext is returned ONLY at publish and rotate.

submission_tokenstringOptional

Full plaintext submission_token. Returned ONLY as a one-shot on:

  • 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.
  • POST /forms/{id}/publish (first publish)
  • POST /forms/{id}/rotate_submission_token Store it immediately; you cannot retrieve it again. If lost, rotate.
previous_submission_token_valid_untilstring Β· date-timeOptional

Rotate response only β€” timestamp at which the previously-issued token stops accepting submissions (default 24h grace).

last_submission_atstring Β· date-time Β· nullableOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
created_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
updated_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
published_atstring Β· date-time Β· nullableOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
get/forms/{id}
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"
}

Update a form.

patch

Partial patch. tracking_codes and design are merged per-key β€” supply only the values to change.

Authorizations
AuthorizationstringRequired

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.

Path parameters
idstringRequiredExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
Query parameters
workroomstringOptional

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.

Header parameters
Gleantap-VersionstringOptional

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.

Example: 2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$
Gleantap-AccountstringOptional

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=.

Example: acc_59fca1e3d2a57d28a10b0442
Gleantap-WorkroomstringOptional

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.

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.

Example: G Test1
Body

PATCH β€” supply only the fields to change. Partial tracking_codes and design are merged.

namestringOptional
titlestringOptional
subtitlestringOptional
slugstringOptional
actionstring Β· enumOptionalPossible values:
action_valuestringOptional
custom_cssstringOptional
Responses
200

Updated form.

application/json
idstringOptionalExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
objectstring Β· enumOptionalPossible values:
namestringOptional

Internal name (dashboard label).

titlestringOptional

Rendered heading shown to submitters.

subtitlestringOptional
slugstringOptional

URL-safe identifier auto-generated from name if omitted.

statusstring Β· enumOptional

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.

Possible values:
actionstring Β· enumOptional

What happens after the submitter clicks submit.

Possible values:
action_valuestringOptional

Companion to action β€” redirect URL, thank-you message text, etc.

custom_cssstringOptional

Raw CSS injected into the form's <style> block on render. Legacy column: additional_css.

submission_countintegerOptional

Total submissions to date.

submission_token_last4string Β· nullableOptional

Last 4 chars of the current submission_token. Full plaintext is returned ONLY at publish and rotate.

submission_tokenstringOptional

Full plaintext submission_token. Returned ONLY as a one-shot on:

  • 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.
  • POST /forms/{id}/publish (first publish)
  • POST /forms/{id}/rotate_submission_token Store it immediately; you cannot retrieve it again. If lost, rotate.
previous_submission_token_valid_untilstring Β· date-timeOptional

Rotate response only β€” timestamp at which the previously-issued token stops accepting submissions (default 24h grace).

last_submission_atstring Β· date-time Β· nullableOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
created_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
updated_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
published_atstring Β· date-time Β· nullableOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
patch/forms/{id}
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"
}

Delete a form.

delete

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.

Authorizations
AuthorizationstringRequired

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.

Path parameters
idstringRequiredExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
Query parameters
workroomstringOptional

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.

Header parameters
Gleantap-VersionstringOptional

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.

Example: 2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$
Gleantap-AccountstringOptional

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=.

Example: acc_59fca1e3d2a57d28a10b0442
Gleantap-WorkroomstringOptional

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.

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.

Example: G Test1
Responses
204

Archived.

No content

delete/forms/{id}
DELETE /v3/forms/{id} HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Publish a form.

post

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.

Authorizations
AuthorizationstringRequired

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.

Path parameters
idstringRequiredExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
Query parameters
workroomstringOptional

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.

Header parameters
Gleantap-VersionstringOptional

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.

Example: 2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$
Gleantap-AccountstringOptional

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=.

Example: acc_59fca1e3d2a57d28a10b0442
Gleantap-WorkroomstringOptional

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.

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.

Example: G Test1
Responses
200

Published. submission_token present ONLY on first publish.

application/json
idstringOptionalExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
objectstring Β· enumOptionalPossible values:
namestringOptional

Internal name (dashboard label).

titlestringOptional

Rendered heading shown to submitters.

subtitlestringOptional
slugstringOptional

URL-safe identifier auto-generated from name if omitted.

statusstring Β· enumOptional

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.

Possible values:
actionstring Β· enumOptional

What happens after the submitter clicks submit.

Possible values:
action_valuestringOptional

Companion to action β€” redirect URL, thank-you message text, etc.

custom_cssstringOptional

Raw CSS injected into the form's <style> block on render. Legacy column: additional_css.

submission_countintegerOptional

Total submissions to date.

submission_token_last4string Β· nullableOptional

Last 4 chars of the current submission_token. Full plaintext is returned ONLY at publish and rotate.

submission_tokenstringOptional

Full plaintext submission_token. Returned ONLY as a one-shot on:

  • 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.
  • POST /forms/{id}/publish (first publish)
  • POST /forms/{id}/rotate_submission_token Store it immediately; you cannot retrieve it again. If lost, rotate.
previous_submission_token_valid_untilstring Β· date-timeOptional

Rotate response only β€” timestamp at which the previously-issued token stops accepting submissions (default 24h grace).

last_submission_atstring Β· date-time Β· nullableOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
created_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
updated_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
published_atstring Β· date-time Β· nullableOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
post/forms/{id}/publish
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"
}

Unpublish (return to draft).

post

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

Authorizations
AuthorizationstringRequired

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.

Path parameters
idstringRequiredExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
Query parameters
workroomstringOptional

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.

Header parameters
Gleantap-VersionstringOptional

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.

Example: 2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$
Gleantap-AccountstringOptional

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=.

Example: acc_59fca1e3d2a57d28a10b0442
Gleantap-WorkroomstringOptional

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.

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.

Example: G Test1
Responses
200

Now in draft.

application/json
idstringOptionalExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
objectstring Β· enumOptionalPossible values:
namestringOptional

Internal name (dashboard label).

titlestringOptional

Rendered heading shown to submitters.

subtitlestringOptional
slugstringOptional

URL-safe identifier auto-generated from name if omitted.

statusstring Β· enumOptional

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.

Possible values:
actionstring Β· enumOptional

What happens after the submitter clicks submit.

Possible values:
action_valuestringOptional

Companion to action β€” redirect URL, thank-you message text, etc.

custom_cssstringOptional

Raw CSS injected into the form's <style> block on render. Legacy column: additional_css.

submission_countintegerOptional

Total submissions to date.

submission_token_last4string Β· nullableOptional

Last 4 chars of the current submission_token. Full plaintext is returned ONLY at publish and rotate.

submission_tokenstringOptional

Full plaintext submission_token. Returned ONLY as a one-shot on:

  • 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.
  • POST /forms/{id}/publish (first publish)
  • POST /forms/{id}/rotate_submission_token Store it immediately; you cannot retrieve it again. If lost, rotate.
previous_submission_token_valid_untilstring Β· date-timeOptional

Rotate response only β€” timestamp at which the previously-issued token stops accepting submissions (default 24h grace).

last_submission_atstring Β· date-time Β· nullableOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
created_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
updated_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
published_atstring Β· date-time Β· nullableOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
post/forms/{id}/unpublish
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"
}

Duplicate a form as a new draft.

post

Copies fields, custom_css, tracking_codes, design. Does NOT copy the submission_token or submission_count β€” the duplicate starts fresh.

Authorizations
AuthorizationstringRequired

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.

Path parameters
idstringRequiredExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
Query parameters
workroomstringOptional

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.

Header parameters
Gleantap-VersionstringOptional

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.

Example: 2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$
Gleantap-AccountstringOptional

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=.

Example: acc_59fca1e3d2a57d28a10b0442
Gleantap-WorkroomstringOptional

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.

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.

Example: G Test1
Body
namestringOptional

Name for the duplicate. Defaults to {original name} (copy).

Responses
201

New draft form.

application/json
idstringOptionalExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
objectstring Β· enumOptionalPossible values:
namestringOptional

Internal name (dashboard label).

titlestringOptional

Rendered heading shown to submitters.

subtitlestringOptional
slugstringOptional

URL-safe identifier auto-generated from name if omitted.

statusstring Β· enumOptional

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.

Possible values:
actionstring Β· enumOptional

What happens after the submitter clicks submit.

Possible values:
action_valuestringOptional

Companion to action β€” redirect URL, thank-you message text, etc.

custom_cssstringOptional

Raw CSS injected into the form's <style> block on render. Legacy column: additional_css.

submission_countintegerOptional

Total submissions to date.

submission_token_last4string Β· nullableOptional

Last 4 chars of the current submission_token. Full plaintext is returned ONLY at publish and rotate.

submission_tokenstringOptional

Full plaintext submission_token. Returned ONLY as a one-shot on:

  • 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.
  • POST /forms/{id}/publish (first publish)
  • POST /forms/{id}/rotate_submission_token Store it immediately; you cannot retrieve it again. If lost, rotate.
previous_submission_token_valid_untilstring Β· date-timeOptional

Rotate response only β€” timestamp at which the previously-issued token stops accepting submissions (default 24h grace).

last_submission_atstring Β· date-time Β· nullableOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
created_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
updated_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
published_atstring Β· date-time Β· nullableOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
post/forms/{id}/duplicate
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"
}

Rotate the form's submission_token.

post

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.

Authorizations
AuthorizationstringRequired

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.

Path parameters
idstringRequiredExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
Query parameters
workroomstringOptional

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.

Header parameters
Gleantap-VersionstringOptional

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.

Example: 2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$
Gleantap-AccountstringOptional

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=.

Example: acc_59fca1e3d2a57d28a10b0442
Gleantap-WorkroomstringOptional

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.

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.

Example: G Test1
Responses
200

Rotated. Store the new plaintext immediately.

application/json
idstringOptionalExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
objectstring Β· enumOptionalPossible values:
namestringOptional

Internal name (dashboard label).

titlestringOptional

Rendered heading shown to submitters.

subtitlestringOptional
slugstringOptional

URL-safe identifier auto-generated from name if omitted.

statusstring Β· enumOptional

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.

Possible values:
actionstring Β· enumOptional

What happens after the submitter clicks submit.

Possible values:
action_valuestringOptional

Companion to action β€” redirect URL, thank-you message text, etc.

custom_cssstringOptional

Raw CSS injected into the form's <style> block on render. Legacy column: additional_css.

submission_countintegerOptional

Total submissions to date.

submission_token_last4string Β· nullableOptional

Last 4 chars of the current submission_token. Full plaintext is returned ONLY at publish and rotate.

submission_tokenstringOptional

Full plaintext submission_token. Returned ONLY as a one-shot on:

  • 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.
  • POST /forms/{id}/publish (first publish)
  • POST /forms/{id}/rotate_submission_token Store it immediately; you cannot retrieve it again. If lost, rotate.
previous_submission_token_valid_untilstring Β· date-timeOptional

Rotate response only β€” timestamp at which the previously-issued token stops accepting submissions (default 24h grace).

last_submission_atstring Β· date-time Β· nullableOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
created_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
updated_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
published_atstring Β· date-time Β· nullableOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
post/forms/{id}/rotate_submission_token
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"
}

List submissions for a form (authenticated).

get
Authorizations
AuthorizationstringRequired

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.

Path parameters
idstringRequiredExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
Query parameters
workroomstringOptional

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.

limitinteger Β· min: 1 Β· max: 100Optional

Page size. Default 25, max 100.

Default: 25
cursorstringOptional

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.

Header parameters
Gleantap-VersionstringOptional

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.

Example: 2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$
Gleantap-AccountstringOptional

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=.

Example: acc_59fca1e3d2a57d28a10b0442
Gleantap-WorkroomstringOptional

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.

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.

Example: G Test1
Responses
200

A page of submissions.

application/json
objectconst: listRequired
has_morebooleanRequired

True if additional records exist beyond this page.

next_cursorstring Β· nullableRequired

Opaque cursor for the next page. Null on the last page.

prev_cursorstring Β· nullableRequired

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/forms/{id}/submissions
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"
}

Public: submit a form.

post

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 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.

Path parameters
idstringRequiredExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
Query parameters
workroomstringOptional

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.

submission_tokenstringOptional

The form's current submission_token. Preferred over header + body forms.

Header parameters
Gleantap-VersionstringOptional

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.

Example: 2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$
Gleantap-AccountstringOptional

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=.

Example: acc_59fca1e3d2a57d28a10b0442
Gleantap-WorkroomstringOptional

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.

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.

Example: G Test1
X-Gleantap-Form-TokenstringOptional
Body

Public 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.

submission_tokenstringOptional

The form's current submission_token. Prefer the query-string or header form; body form is a fallback for CORS-restricted clients.

Responses
201

Submission recorded.

application/json
idstringOptional

A v3 submission is fsm_<24-hex>. A submission made through the legacy dashboard submit (e.g. checkout pages) is fsm_<contact 24-hex>_.

Example: fsm_6a616226a33b04c59a01f7f4Pattern: ^fsm_[0-9a-f]{24}(_[0-9]+)?$
objectstring Β· enumOptionalPossible values:
form_idstring Β· nullableOptional

Null for a landing page's own (non-form) submit.

Example: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
page_idstring Β· nullableOptional

Set when submitted through a landing page (POST /pages/{id}/submissions).

Example: pg_66d9a11d0e5b7c1a4d8e2f1bPattern: ^pg_[0-9a-fA-F]{24}$
contact_idstringOptional

A contact ID. Accepts either the native prefixed id (con_<24-hex>) or an external-ID reference (external_id:<your_id>).

Example: con_6a7eaec3505bea795709f897Pattern: ^con_[0-9a-f]{24}$|^external_id:[^/]+$
ipstring Β· nullableOptional
user_agentstring Β· nullableOptional
referrerstring Β· nullableOptional
created_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
post/forms/{id}/submissions
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"
}

Read a form's sharing configuration.

get
Authorizations
AuthorizationstringRequired

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.

Path parameters
idstringRequiredExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
Query parameters
workroomstringOptional

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.

Header parameters
Gleantap-VersionstringOptional

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.

Example: 2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$
Gleantap-AccountstringOptional

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=.

Example: acc_59fca1e3d2a57d28a10b0442
Gleantap-WorkroomstringOptional

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.

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.

Example: G Test1
Responses
200

Sharing config.

application/json
objectconst: form_sharingOptional
form_idstringOptionalExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
other_allowed_user_idsstring[]Optional

A staff user (from the legacy users collection). Used for owner_id, responsible_id, created_by, assigned_to, etc.

role_updated_onstring Β· date-time Β· nullableOptional
get/forms/{id}/sharing
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"
}

Replace a form's sharing configuration.

put

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.

Authorizations
AuthorizationstringRequired

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.

Path parameters
idstringRequiredExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
Query parameters
workroomstringOptional

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.

Header parameters
Gleantap-VersionstringOptional

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.

Example: 2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$
Gleantap-AccountstringOptional

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=.

Example: acc_59fca1e3d2a57d28a10b0442
Gleantap-WorkroomstringOptional

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.

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.

Example: G Test1
Body
other_allowed_user_idsstring[]Optional

Required (non-empty) when allowed_roles.Other is true; otherwise ignored.

Responses
200

Updated sharing config.

application/json
objectconst: form_sharingOptional
form_idstringOptionalExample: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
other_allowed_user_idsstring[]Optional

A staff user (from the legacy users collection). Used for owner_id, responsible_id, created_by, assigned_to, etc.

role_updated_onstring Β· date-time Β· nullableOptional
put/forms/{id}/sharing
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"
}

Retrieve a single form submission.

get
Authorizations
AuthorizationstringRequired

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.

Path parameters
idstringRequired

A v3 submission is fsm_<24-hex>. A submission made through the legacy dashboard submit (e.g. checkout pages) is fsm_<contact 24-hex>_.

Example: fsm_6a616226a33b04c59a01f7f4Pattern: ^fsm_[0-9a-f]{24}(_[0-9]+)?$
Query parameters
workroomstringOptional

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.

Header parameters
Gleantap-VersionstringOptional

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.

Example: 2026-05-27Pattern: ^\d{4}-\d{2}-\d{2}$
Gleantap-AccountstringOptional

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=.

Example: acc_59fca1e3d2a57d28a10b0442
Gleantap-WorkroomstringOptional

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.

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.

Example: G Test1
Responses
200

The submission.

application/json
idstringOptional

A v3 submission is fsm_<24-hex>. A submission made through the legacy dashboard submit (e.g. checkout pages) is fsm_<contact 24-hex>_.

Example: fsm_6a616226a33b04c59a01f7f4Pattern: ^fsm_[0-9a-f]{24}(_[0-9]+)?$
objectstring Β· enumOptionalPossible values:
form_idstring Β· nullableOptional

Null for a landing page's own (non-form) submit.

Example: fom_6a616204a33b04c59a01f7f2Pattern: ^fom_[0-9a-f]{24}$
page_idstring Β· nullableOptional

Set when submitted through a landing page (POST /pages/{id}/submissions).

Example: pg_66d9a11d0e5b7c1a4d8e2f1bPattern: ^pg_[0-9a-fA-F]{24}$
contact_idstringOptional

A contact ID. Accepts either the native prefixed id (con_<24-hex>) or an external-ID reference (external_id:<your_id>).

Example: con_6a7eaec3505bea795709f897Pattern: ^con_[0-9a-f]{24}$|^external_id:[^/]+$
ipstring Β· nullableOptional
user_agentstring Β· nullableOptional
referrerstring Β· nullableOptional
created_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
get/form_submissions/{id}
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"
}