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

Pipelines

Sales pipelines + stages. Each pipeline has an ordered list of stages that opportunities move through.

List sales pipelines.

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

OK

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

OK

{
  "object": "text",
  "data": [
    {
      "id": "text",
      "object": "pipeline",
      "name": "text",
      "is_default": true,
      "owner_id": "text",
      "active_linked_children": [
        "text"
      ],
      "stages": [
        {
          "id": "text",
          "object": "pipeline_stage",
          "pipeline_id": "text",
          "name": "text",
          "order": 1,
          "color": "text",
          "stage_type": "manual",
          "criteria": [
            {
              "segment": "Attributes",
              "data": "text",
              "event": "text",
              "operator": "=",
              "value": null,
              "value2": null,
              "operator2": "text",
              "value2_id": [
                "text"
              ],
              "data_type": "String",
              "dataAlias": "text",
              "ANY_ADDITIONAL_PROPERTY": "anything"
            }
          ],
          "with_or_criteria": [
            [
              {
                "segment": "Attributes",
                "data": "text",
                "event": "text",
                "operator": "=",
                "value": null,
                "value2": null,
                "operator2": "text",
                "value2_id": [
                  "text"
                ],
                "data_type": "String",
                "dataAlias": "text",
                "ANY_ADDITIONAL_PROPERTY": "anything"
              }
            ]
          ],
          "segment_id": "seg_01H8XKE...",
          "owner_id": "text",
          "contact_count": 1,
          "created_at": "2026-05-27T14:23:11.482Z"
        }
      ],
      "created_by": "text",
      "updated_by": "text",
      "created_at": "2026-05-27T14:23:11.482Z",
      "updated_at": "2026-05-27T14:23:11.482Z"
    }
  ],
  "has_more": true,
  "next_cursor": "text",
  "prev_cursor": "text"
}

Create a pipeline.

post

Requires the pipeline name. 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.

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
namestringRequired
is_defaultbooleanOptionalDefault: false
owner_idstringOptional

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

Pattern: ^usr_[0-9a-f]{24}$
Responses
201

Created

application/json
idstringOptionalPattern: ^pip_[0-9a-f]{24}$
objectstring Β· enumOptionalPossible values:
namestringOptional
is_defaultbooleanOptional
owner_idstring Β· nullableOptional

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

Pattern: ^usr_[0-9a-f]{24}$
active_linked_childrenstring[]Optional
created_bystring Β· nullableOptional

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

Pattern: ^usr_[0-9a-f]{24}$
updated_bystring Β· nullableOptional

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

Pattern: ^usr_[0-9a-f]{24}$
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
post/pipelines
POST /v3/pipelines HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 52

{
  "name": "text",
  "is_default": false,
  "owner_id": "text"
}
201

Created

{
  "id": "text",
  "object": "pipeline",
  "name": "text",
  "is_default": true,
  "owner_id": "text",
  "active_linked_children": [
    "text"
  ],
  "stages": [
    {
      "id": "text",
      "object": "pipeline_stage",
      "pipeline_id": "text",
      "name": "text",
      "order": 1,
      "color": "text",
      "stage_type": "manual",
      "criteria": [
        {
          "segment": "Attributes",
          "data": "text",
          "event": "text",
          "operator": "=",
          "value": null,
          "value2": null,
          "operator2": "text",
          "value2_id": [
            "text"
          ],
          "data_type": "String",
          "dataAlias": "text",
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "with_or_criteria": [
        [
          {
            "segment": "Attributes",
            "data": "text",
            "event": "text",
            "operator": "=",
            "value": null,
            "value2": null,
            "operator2": "text",
            "value2_id": [
              "text"
            ],
            "data_type": "String",
            "dataAlias": "text",
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        ]
      ],
      "segment_id": "seg_01H8XKE...",
      "owner_id": "text",
      "contact_count": 1,
      "created_at": "2026-05-27T14:23:11.482Z"
    }
  ],
  "created_by": "text",
  "updated_by": "text",
  "created_at": "2026-05-27T14:23:11.482Z",
  "updated_at": "2026-05-27T14:23:11.482Z"
}

Retrieve one sales pipeline.

get

The pipeline's name, its stages in order, and whether it is the account default. Sales-automation rules reference a pipeline by this ID.

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
idstringRequiredPattern: ^pip_[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

OK

application/json
idstringOptionalPattern: ^pip_[0-9a-f]{24}$
objectstring Β· enumOptionalPossible values:
namestringOptional
is_defaultbooleanOptional
owner_idstring Β· nullableOptional

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

Pattern: ^usr_[0-9a-f]{24}$
active_linked_childrenstring[]Optional
created_bystring Β· nullableOptional

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

Pattern: ^usr_[0-9a-f]{24}$
updated_bystring Β· nullableOptional

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

Pattern: ^usr_[0-9a-f]{24}$
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
get/pipelines/{id}
GET /v3/pipelines/{id} HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "id": "text",
  "object": "pipeline",
  "name": "text",
  "is_default": true,
  "owner_id": "text",
  "active_linked_children": [
    "text"
  ],
  "stages": [
    {
      "id": "text",
      "object": "pipeline_stage",
      "pipeline_id": "text",
      "name": "text",
      "order": 1,
      "color": "text",
      "stage_type": "manual",
      "criteria": [
        {
          "segment": "Attributes",
          "data": "text",
          "event": "text",
          "operator": "=",
          "value": null,
          "value2": null,
          "operator2": "text",
          "value2_id": [
            "text"
          ],
          "data_type": "String",
          "dataAlias": "text",
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "with_or_criteria": [
        [
          {
            "segment": "Attributes",
            "data": "text",
            "event": "text",
            "operator": "=",
            "value": null,
            "value2": null,
            "operator2": "text",
            "value2_id": [
              "text"
            ],
            "data_type": "String",
            "dataAlias": "text",
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        ]
      ],
      "segment_id": "seg_01H8XKE...",
      "owner_id": "text",
      "contact_count": 1,
      "created_at": "2026-05-27T14:23:11.482Z"
    }
  ],
  "created_by": "text",
  "updated_by": "text",
  "created_at": "2026-05-27T14:23:11.482Z",
  "updated_at": "2026-05-27T14:23:11.482Z"
}

Update a pipeline's name or default flag.

patch

Patches the pipeline itself, not its stages β€” use the stage operations for those. Omitted fields are left unchanged.

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
idstringRequiredPattern: ^pip_[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

Fields to patch on a sales pipeline. All fields are optional. Omitted fields are left unchanged.

namestringOptional

Display name of the pipeline.

is_defaultbooleanOptional

Whether this pipeline is the default sales pipeline for the workroom. Setting true makes this the default and clears the default flag on any previous default pipeline. Omit to leave unchanged (no default false).

owner_idstring Β· nullableOptional

Staff user who owns this pipeline.

Pattern: ^usr_[0-9a-f]{24}$
Responses
200

OK

application/json
idstringOptionalPattern: ^pip_[0-9a-f]{24}$
objectstring Β· enumOptionalPossible values:
namestringOptional
is_defaultbooleanOptional
owner_idstring Β· nullableOptional

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

Pattern: ^usr_[0-9a-f]{24}$
active_linked_childrenstring[]Optional
created_bystring Β· nullableOptional

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

Pattern: ^usr_[0-9a-f]{24}$
updated_bystring Β· nullableOptional

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

Pattern: ^usr_[0-9a-f]{24}$
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
patch/pipelines/{id}
PATCH /v3/pipelines/{id} HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "name": "text",
  "is_default": true,
  "owner_id": "text"
}
200

OK

{
  "id": "text",
  "object": "pipeline",
  "name": "text",
  "is_default": true,
  "owner_id": "text",
  "active_linked_children": [
    "text"
  ],
  "stages": [
    {
      "id": "text",
      "object": "pipeline_stage",
      "pipeline_id": "text",
      "name": "text",
      "order": 1,
      "color": "text",
      "stage_type": "manual",
      "criteria": [
        {
          "segment": "Attributes",
          "data": "text",
          "event": "text",
          "operator": "=",
          "value": null,
          "value2": null,
          "operator2": "text",
          "value2_id": [
            "text"
          ],
          "data_type": "String",
          "dataAlias": "text",
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "with_or_criteria": [
        [
          {
            "segment": "Attributes",
            "data": "text",
            "event": "text",
            "operator": "=",
            "value": null,
            "value2": null,
            "operator2": "text",
            "value2_id": [
              "text"
            ],
            "data_type": "String",
            "dataAlias": "text",
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        ]
      ],
      "segment_id": "seg_01H8XKE...",
      "owner_id": "text",
      "contact_count": 1,
      "created_at": "2026-05-27T14:23:11.482Z"
    }
  ],
  "created_by": "text",
  "updated_by": "text",
  "created_at": "2026-05-27T14:23:11.482Z",
  "updated_at": "2026-05-27T14:23:11.482Z"
}
delete

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
idstringRequiredPattern: ^pip_[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

Deleted. Cascades to stages.

No content

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

Deleted. Cascades to stages.

No content

List a pipeline's stages, in order.

get

Stages in their display order, with the contact count in each. Stage order is what the dashboard's kanban columns follow; change it with reorderPipelineStages.

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
idstringRequiredPattern: ^pip_[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

Stages sorted by order ASC.

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

Stages sorted by order ASC.

{
  "object": "text",
  "data": [
    {
      "id": "text",
      "object": "pipeline_stage",
      "pipeline_id": "text",
      "name": "text",
      "order": 1,
      "color": "text",
      "stage_type": "manual",
      "criteria": [
        {
          "segment": "Attributes",
          "data": "text",
          "event": "text",
          "operator": "=",
          "value": null,
          "value2": null,
          "operator2": "text",
          "value2_id": [
            "text"
          ],
          "data_type": "String",
          "dataAlias": "text",
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "with_or_criteria": [
        [
          {
            "segment": "Attributes",
            "data": "text",
            "event": "text",
            "operator": "=",
            "value": null,
            "value2": null,
            "operator2": "text",
            "value2_id": [
              "text"
            ],
            "data_type": "String",
            "dataAlias": "text",
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        ]
      ],
      "segment_id": "seg_01H8XKE...",
      "owner_id": "text",
      "contact_count": 1,
      "created_at": "2026-05-27T14:23:11.482Z"
    }
  ],
  "has_more": true,
  "next_cursor": "text",
  "prev_cursor": "text"
}
post

Requires the stage name and its position. 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.

Path parameters
idstringRequiredPattern: ^pip_[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
namestringRequired
orderintegerOptional

Optional. Defaults to end of list.

colorstringOptional
stage_typestring Β· enumOptional

manual (default) β†’ no criteria. static / dynamic β†’ criteria is required. See the PipelineStage schema for semantics.

Default: manualPossible values:
owner_idstringOptional

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

Pattern: ^usr_[0-9a-f]{24}$
Responses
201

Created.

application/json
idstringOptionalPattern: ^stg_[0-9a-f]{24}$
objectstring Β· enumOptionalPossible values:
pipeline_idstringOptionalPattern: ^pip_[0-9a-f]{24}$
namestringOptional
orderintegerOptional

1-based; lower renders first (leftmost in the pipeline board).

colorstring Β· nullableOptional

Background color hex.

stage_typestring Β· enumOptional

How contacts arrive in this stage:

  • manual (default) β€” contacts are added by hand or by an automation. No criteria.
  • static β€” one-shot criteria; matching contacts are added ONCE when the stage is created (or when the criteria is edited).
  • dynamic β€” continuous criteria; the background worker keeps the stage's membership in sync with the criteria β€” new matches roll in, non-matches roll out.
Possible values:
segment_idstring Β· nullableOptional

Auto-created shadow segment when stage_type is static/dynamic; re-used (updated in place) when the criteria are edited, as the dashboard does. Read-only from the v3 API.

Example: seg_01H8XKE...Pattern: ^seg_[0-9A-HJKMNP-TV-Z]{26}$
owner_idstring Β· nullableOptional

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

Pattern: ^usr_[0-9a-f]{24}$
contact_countintegerOptional

Number of contacts currently in this stage.

created_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
post/pipelines/{id}/stages
POST /v3/pipelines/{id}/stages HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 542

{
  "name": "text",
  "order": 1,
  "color": "text",
  "stage_type": "manual",
  "criteria": [
    {
      "segment": "Attributes",
      "data": "text",
      "event": "text",
      "operator": "=",
      "value": null,
      "value2": null,
      "operator2": "text",
      "value2_id": [
        "text"
      ],
      "data_type": "String",
      "dataAlias": "text",
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "with_or_criteria": [
    [
      {
        "segment": "Attributes",
        "data": "text",
        "event": "text",
        "operator": "=",
        "value": null,
        "value2": null,
        "operator2": "text",
        "value2_id": [
          "text"
        ],
        "data_type": "String",
        "dataAlias": "text",
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ]
  ],
  "owner_id": "text"
}
201

Created.

{
  "id": "text",
  "object": "pipeline_stage",
  "pipeline_id": "text",
  "name": "text",
  "order": 1,
  "color": "text",
  "stage_type": "manual",
  "criteria": [
    {
      "segment": "Attributes",
      "data": "text",
      "event": "text",
      "operator": "=",
      "value": null,
      "value2": null,
      "operator2": "text",
      "value2_id": [
        "text"
      ],
      "data_type": "String",
      "dataAlias": "text",
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "with_or_criteria": [
    [
      {
        "segment": "Attributes",
        "data": "text",
        "event": "text",
        "operator": "=",
        "value": null,
        "value2": null,
        "operator2": "text",
        "value2_id": [
          "text"
        ],
        "data_type": "String",
        "dataAlias": "text",
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ]
  ],
  "segment_id": "seg_01H8XKE...",
  "owner_id": "text",
  "contact_count": 1,
  "created_at": "2026-05-27T14:23:11.482Z"
}

Retrieve one pipeline stage.

get

The stage's name, position and the pipeline it belongs to. Note that sales-automation rules match a trigger stage by NAME within their own pipeline, not by this ID.

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
idstringRequiredPattern: ^pip_[0-9a-f]{24}$
stage_idstringRequiredPattern: ^stg_[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

OK

application/json
idstringOptionalPattern: ^stg_[0-9a-f]{24}$
objectstring Β· enumOptionalPossible values:
pipeline_idstringOptionalPattern: ^pip_[0-9a-f]{24}$
namestringOptional
orderintegerOptional

1-based; lower renders first (leftmost in the pipeline board).

colorstring Β· nullableOptional

Background color hex.

stage_typestring Β· enumOptional

How contacts arrive in this stage:

  • manual (default) β€” contacts are added by hand or by an automation. No criteria.
  • static β€” one-shot criteria; matching contacts are added ONCE when the stage is created (or when the criteria is edited).
  • dynamic β€” continuous criteria; the background worker keeps the stage's membership in sync with the criteria β€” new matches roll in, non-matches roll out.
Possible values:
segment_idstring Β· nullableOptional

Auto-created shadow segment when stage_type is static/dynamic; re-used (updated in place) when the criteria are edited, as the dashboard does. Read-only from the v3 API.

Example: seg_01H8XKE...Pattern: ^seg_[0-9A-HJKMNP-TV-Z]{26}$
owner_idstring Β· nullableOptional

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

Pattern: ^usr_[0-9a-f]{24}$
contact_countintegerOptional

Number of contacts currently in this stage.

created_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
get/pipelines/{id}/stages/{stage_id}
GET /v3/pipelines/{id}/stages/{stage_id} HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

OK

{
  "id": "text",
  "object": "pipeline_stage",
  "pipeline_id": "text",
  "name": "text",
  "order": 1,
  "color": "text",
  "stage_type": "manual",
  "criteria": [
    {
      "segment": "Attributes",
      "data": "text",
      "event": "text",
      "operator": "=",
      "value": null,
      "value2": null,
      "operator2": "text",
      "value2_id": [
        "text"
      ],
      "data_type": "String",
      "dataAlias": "text",
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "with_or_criteria": [
    [
      {
        "segment": "Attributes",
        "data": "text",
        "event": "text",
        "operator": "=",
        "value": null,
        "value2": null,
        "operator2": "text",
        "value2_id": [
          "text"
        ],
        "data_type": "String",
        "dataAlias": "text",
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ]
  ],
  "segment_id": "seg_01H8XKE...",
  "owner_id": "text",
  "contact_count": 1,
  "created_at": "2026-05-27T14:23:11.482Z"
}

Rename or move a pipeline stage.

patch

Renaming a stage rewrites the trigger_stage of any sales-automation rule that referenced the old name, since rules match stages by name.

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
idstringRequiredPattern: ^pip_[0-9a-f]{24}$
stage_idstringRequiredPattern: ^stg_[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

Fields to patch on a pipeline stage. All fields are optional. Omitted fields are left unchanged.

namestringOptional

Display name of the stage.

orderintegerOptional

1-based position among stages in this pipeline.

colorstringOptional

Background color hex.

stage_typestring Β· enumOptional

manual β†’ no criteria. static / dynamic β†’ criteria required. Omit to leave unchanged.

Possible values:
owner_idstring Β· nullableOptional

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

Pattern: ^usr_[0-9a-f]{24}$
Responses
200

OK

application/json
idstringOptionalPattern: ^stg_[0-9a-f]{24}$
objectstring Β· enumOptionalPossible values:
pipeline_idstringOptionalPattern: ^pip_[0-9a-f]{24}$
namestringOptional
orderintegerOptional

1-based; lower renders first (leftmost in the pipeline board).

colorstring Β· nullableOptional

Background color hex.

stage_typestring Β· enumOptional

How contacts arrive in this stage:

  • manual (default) β€” contacts are added by hand or by an automation. No criteria.
  • static β€” one-shot criteria; matching contacts are added ONCE when the stage is created (or when the criteria is edited).
  • dynamic β€” continuous criteria; the background worker keeps the stage's membership in sync with the criteria β€” new matches roll in, non-matches roll out.
Possible values:
segment_idstring Β· nullableOptional

Auto-created shadow segment when stage_type is static/dynamic; re-used (updated in place) when the criteria are edited, as the dashboard does. Read-only from the v3 API.

Example: seg_01H8XKE...Pattern: ^seg_[0-9A-HJKMNP-TV-Z]{26}$
owner_idstring Β· nullableOptional

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

Pattern: ^usr_[0-9a-f]{24}$
contact_countintegerOptional

Number of contacts currently in this stage.

created_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
patch/pipelines/{id}/stages/{stage_id}
PATCH /v3/pipelines/{id}/stages/{stage_id} HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 542

{
  "name": "text",
  "order": 1,
  "color": "text",
  "stage_type": "manual",
  "criteria": [
    {
      "segment": "Attributes",
      "data": "text",
      "event": "text",
      "operator": "=",
      "value": null,
      "value2": null,
      "operator2": "text",
      "value2_id": [
        "text"
      ],
      "data_type": "String",
      "dataAlias": "text",
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "with_or_criteria": [
    [
      {
        "segment": "Attributes",
        "data": "text",
        "event": "text",
        "operator": "=",
        "value": null,
        "value2": null,
        "operator2": "text",
        "value2_id": [
          "text"
        ],
        "data_type": "String",
        "dataAlias": "text",
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ]
  ],
  "owner_id": "text"
}
200

OK

{
  "id": "text",
  "object": "pipeline_stage",
  "pipeline_id": "text",
  "name": "text",
  "order": 1,
  "color": "text",
  "stage_type": "manual",
  "criteria": [
    {
      "segment": "Attributes",
      "data": "text",
      "event": "text",
      "operator": "=",
      "value": null,
      "value2": null,
      "operator2": "text",
      "value2_id": [
        "text"
      ],
      "data_type": "String",
      "dataAlias": "text",
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "with_or_criteria": [
    [
      {
        "segment": "Attributes",
        "data": "text",
        "event": "text",
        "operator": "=",
        "value": null,
        "value2": null,
        "operator2": "text",
        "value2_id": [
          "text"
        ],
        "data_type": "String",
        "dataAlias": "text",
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ]
  ],
  "segment_id": "seg_01H8XKE...",
  "owner_id": "text",
  "contact_count": 1,
  "created_at": "2026-05-27T14:23:11.482Z"
}
delete

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
idstringRequiredPattern: ^pip_[0-9a-f]{24}$
stage_idstringRequiredPattern: ^stg_[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

Deleted.

No content

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

Deleted.

No content

Reorder stages within a pipeline.

post

Body {stage_ids: ["stg_..."]} in desired display order. Assigns order = 1..N.

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
idstringRequiredPattern: ^pip_[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
stage_idsstring[]Required
Responses
200

OK

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.

post/pipelines/{id}/stages/reorder
POST /v3/pipelines/{id}/stages/reorder HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "stage_ids": [
    "text"
  ]
}
200

OK

{
  "object": "text",
  "data": [
    {
      "id": "text",
      "object": "pipeline_stage",
      "pipeline_id": "text",
      "name": "text",
      "order": 1,
      "color": "text",
      "stage_type": "manual",
      "criteria": [
        {
          "segment": "Attributes",
          "data": "text",
          "event": "text",
          "operator": "=",
          "value": null,
          "value2": null,
          "operator2": "text",
          "value2_id": [
            "text"
          ],
          "data_type": "String",
          "dataAlias": "text",
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "with_or_criteria": [
        [
          {
            "segment": "Attributes",
            "data": "text",
            "event": "text",
            "operator": "=",
            "value": null,
            "value2": null,
            "operator2": "text",
            "value2_id": [
              "text"
            ],
            "data_type": "String",
            "dataAlias": "text",
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        ]
      ],
      "segment_id": "seg_01H8XKE...",
      "owner_id": "text",
      "contact_count": 1,
      "created_at": "2026-05-27T14:23:11.482Z"
    }
  ],
  "has_more": true,
  "next_cursor": "text",
  "prev_cursor": "text"
}

Duplicate a pipeline.

post

Creates a new pipeline with the same stages (name, type, criteria, order, color, owner). Each static/dynamic stage gets a fresh shadow segment recomputed from its criteria β€” no contact membership is copied; the new pipeline's stages start empty until the background worker recomputes them, exactly as a newly created stage would. is_default is NOT copied β€” the duplicate is never made the account's default pipeline.

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
idstringRequiredPattern: ^pip_[0-9a-f]{24}$
Header parameters
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
Body
namestringOptional

Name for the duplicate. Defaults to "<source name> (copy)".

Responses
201

Created.

application/json
idstringOptionalPattern: ^pip_[0-9a-f]{24}$
objectstring Β· enumOptionalPossible values:
namestringOptional
is_defaultbooleanOptional
owner_idstring Β· nullableOptional

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

Pattern: ^usr_[0-9a-f]{24}$
active_linked_childrenstring[]Optional
created_bystring Β· nullableOptional

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

Pattern: ^usr_[0-9a-f]{24}$
updated_bystring Β· nullableOptional

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

Pattern: ^usr_[0-9a-f]{24}$
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
post/pipelines/{id}/duplicate
POST /v3/pipelines/{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": "text",
  "object": "pipeline",
  "name": "text",
  "is_default": true,
  "owner_id": "text",
  "active_linked_children": [
    "text"
  ],
  "stages": [
    {
      "id": "text",
      "object": "pipeline_stage",
      "pipeline_id": "text",
      "name": "text",
      "order": 1,
      "color": "text",
      "stage_type": "manual",
      "criteria": [
        {
          "segment": "Attributes",
          "data": "text",
          "event": "text",
          "operator": "=",
          "value": null,
          "value2": null,
          "operator2": "text",
          "value2_id": [
            "text"
          ],
          "data_type": "String",
          "dataAlias": "text",
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "with_or_criteria": [
        [
          {
            "segment": "Attributes",
            "data": "text",
            "event": "text",
            "operator": "=",
            "value": null,
            "value2": null,
            "operator2": "text",
            "value2_id": [
              "text"
            ],
            "data_type": "String",
            "dataAlias": "text",
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        ]
      ],
      "segment_id": "seg_01H8XKE...",
      "owner_id": "text",
      "contact_count": 1,
      "created_at": "2026-05-27T14:23:11.482Z"
    }
  ],
  "created_by": "text",
  "updated_by": "text",
  "created_at": "2026-05-27T14:23:11.482Z",
  "updated_at": "2026-05-27T14:23:11.482Z"
}

Reorder the top-level pipelines list.

post

Reorders pipelines themselves β€” distinct from POST /v3/pipelines/{id}/stages/reorder, which only reorders stages within one pipeline. Body {pipeline_ids: ["pip_..."]} in desired display order; assigns sort_order = 1..N. Pipelines that have never been reordered (no sort_order set) sort AFTER every explicitly-ordered pipeline in GET /v3/pipelines, not interleaved by creation date. Malformed or unresolvable ids are skipped silently. The response returns only the pipelines passed in this call, shaped and in the order provided β€” not the full listPipelines page.

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.

Header parameters
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
Body
pipeline_idsstring[]Required
Responses
200

OK

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.

post/pipelines/reorder
POST /v3/pipelines/reorder HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 25

{
  "pipeline_ids": [
    "text"
  ]
}
200

OK

{
  "object": "text",
  "data": [
    {
      "id": "text",
      "object": "pipeline",
      "name": "text",
      "is_default": true,
      "owner_id": "text",
      "active_linked_children": [
        "text"
      ],
      "stages": [
        {
          "id": "text",
          "object": "pipeline_stage",
          "pipeline_id": "text",
          "name": "text",
          "order": 1,
          "color": "text",
          "stage_type": "manual",
          "criteria": [
            {
              "segment": "Attributes",
              "data": "text",
              "event": "text",
              "operator": "=",
              "value": null,
              "value2": null,
              "operator2": "text",
              "value2_id": [
                "text"
              ],
              "data_type": "String",
              "dataAlias": "text",
              "ANY_ADDITIONAL_PROPERTY": "anything"
            }
          ],
          "with_or_criteria": [
            [
              {
                "segment": "Attributes",
                "data": "text",
                "event": "text",
                "operator": "=",
                "value": null,
                "value2": null,
                "operator2": "text",
                "value2_id": [
                  "text"
                ],
                "data_type": "String",
                "dataAlias": "text",
                "ANY_ADDITIONAL_PROPERTY": "anything"
              }
            ]
          ],
          "segment_id": "seg_01H8XKE...",
          "owner_id": "text",
          "contact_count": 1,
          "created_at": "2026-05-27T14:23:11.482Z"
        }
      ],
      "created_by": "text",
      "updated_by": "text",
      "created_at": "2026-05-27T14:23:11.482Z",
      "updated_at": "2026-05-27T14:23:11.482Z"
    }
  ],
  "has_more": true,
  "next_cursor": "text",
  "prev_cursor": "text"
}

Read a pipeline'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
idstringRequiredPattern: ^pip_[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: pipeline_sharingOptional
pipeline_idstringOptionalPattern: ^pip_[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/pipelines/{id}/sharing
GET /v3/pipelines/{id}/sharing HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "object": "text",
  "pipeline_id": "text",
  "allowed_roles": {
    "ANY_ADDITIONAL_PROPERTY": true
  },
  "other_allowed_user_ids": [
    "text"
  ],
  "role_updated_on": "2026-01-01T00:00:00.000Z"
}

Replace a pipeline'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
idstringRequiredPattern: ^pip_[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: pipeline_sharingOptional
pipeline_idstringOptionalPattern: ^pip_[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/pipelines/{id}/sharing
PUT /v3/pipelines/{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",
  "pipeline_id": "text",
  "allowed_roles": {
    "ANY_ADDITIONAL_PROPERTY": true
  },
  "other_allowed_user_ids": [
    "text"
  ],
  "role_updated_on": "2026-01-01T00:00:00.000Z"
}

Add or move a contact to a stage within a pipeline β€” direct and synchronous.

put

Sets the contact's current stage in this pipeline right now, regardless of prior state: if the contact isn't in the pipeline yet, this adds them; if they're already in it, this moves them. There is no separate "add" endpoint β€” the two are the same write, distinguished only by previous_stage_id in the response (null = fresh add or idempotent no-op).

Works on a stage of ANY stage_type β€” including static/dynamic stages whose membership is normally computed from criteria by a background worker. This plants a manual-override marker (mirroring the dashboard's own drag-and-drop behavior) that protects the contact against backward or equal-stage moves during background criteria sync. Note that in standard Gleantap pipeline semantics, downstream dynamic stages with a higher display order can advance a matching contact forward when criteria match. Re-GET the contact or pipeline contact membership to observe current placement.

Idempotent: calling this again with the same stage_id the contact is already at is a safe no-op β€” no duplicate history entries are written.

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
idstringRequiredPattern: ^pip_[0-9a-f]{24}$
contact_idstringRequired

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:[^/]+$
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
stage_idstringRequiredPattern: ^stg_[0-9a-f]{24}$
Responses
200

The contact's current membership record, including where they were before this call.

application/json

A contact's current position within one pipeline. There is no "in the pipeline but no stage" state β€” a contact either has exactly one of these, or isn't in the pipeline at all.

objectconst: pipeline_membershipOptional
pipeline_idstringOptionalPattern: ^pip_[0-9a-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:[^/]+$
stage_idstring Β· nullableOptionalPattern: ^stg_[0-9a-f]{24}$
stage_namestring Β· nullableOptional

Display name of the current stage.

statusstring Β· enumOptional

Independent of stage β€” changed separately (e.g. by a sales_automation status action), not by moving stages.

Possible values:
prioritystring Β· nullableOptional
added_atstring Β· date-timeOptional

RFC 3339 timestamp, always UTC, millisecond precision.

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

RFC 3339 timestamp, always UTC, millisecond precision.

Example: 2026-05-27T14:23:11.482Z
previous_stage_idstring Β· nullableOptional

Only present on the PUT response. null if the contact was not previously in this pipeline (a fresh add) or was already at that stage (idempotent no-op β€” nothing was written). Otherwise the stage they were moved FROM.

Pattern: ^stg_[0-9a-f]{24}$
put/pipelines/{id}/contacts/{contact_id}
PUT /v3/pipelines/{id}/contacts/{contact_id} HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "stage_id": "text"
}
{
  "object": "text",
  "pipeline_id": "text",
  "contact_id": "con_6a7eaec3505bea795709f897",
  "stage_id": "text",
  "stage_name": "text",
  "status": "Active",
  "priority": "text",
  "added_at": "2026-05-27T14:23:11.482Z",
  "last_updated_at": "2026-05-27T14:23:11.482Z",
  "previous_stage_id": "text"
}

Remove a contact from a pipeline entirely β€” direct and synchronous.

delete

Removes the contact's ENTIRE membership in this pipeline β€” there is no "stay in the pipeline but clear the stage" state to target, so this always removes them from every stage of it, not just one.

Requires expected_stage_id (query parameter) naming the stage you believe the contact is currently at, as an optimistic-concurrency check β€” if it doesn't match their actual current stage, this returns 409 and writes nothing. Re-GET the contact or pipeline first if you're not sure.

This is treated as a MANUAL removal, same as the dashboard's own delete action β€” which means it is NOT a cheap, reversible action: it plants a permanent marker that blocks this contact from ever being silently re-added to this pipeline by an automation or by stage criteria again, even though the contact document itself is otherwise untouched. Calling the add/move endpoint again for this contact and pipeline overrides that block for that one explicit call, but nothing else will re-add them on its own afterward. Only use this when removal is really intended.

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
idstringRequiredPattern: ^pip_[0-9a-f]{24}$
contact_idstringRequired

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:[^/]+$
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.

expected_stage_idstringRequired

The stage you expect the contact to currently be at in this pipeline. Required β€” this is the optimistic-concurrency check that must pass before anything is removed.

Pattern: ^stg_[0-9a-f]{24}$
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

Removed.

No content

delete/pipelines/{id}/contacts/{contact_id}
DELETE /v3/pipelines/{id}/contacts/{contact_id}?expected_stage_id=text HTTP/1.1
Host: api.gleantap.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content