> For the complete documentation index, see [llms.txt](https://developers.gleantap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gleantap.com/api-reference-v3/sales-automations.md).

# Sales Automations

Reusable CRM automation rules. 13 action types (task, tags, assign, add\_stage, ...) and 7 trigger types (added\_to\_segments, after\_x\_days, condition, ...). Referenced by flow `sales_automation` nodes.

## List sales-automation rules.

> CRM rules that fire on a pipeline event — a stage change, a task completion, a segment entry — and run actions such as creating a task or moving a stage. Rules created by flow nodes are excluded by default; pass \`source\` to include them.\
> \
> A legacy rule stored without a \`pipeline\_id\` runs but is not shown in the dashboard's automations list. Such rules are returned as stored (\`pipeline\_id: null\`) together with their \`workroom\_id\`, so they can be found and bound explicitly with \`PATCH\` — this endpoint does not write to them.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Sales Automations","description":"Reusable CRM automation rules. 13 action types (task, tags, assign, add_stage, ...) and 7 trigger types (added_to_segments, after_x_days, condition, ...). Referenced by flow `sales_automation` nodes."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}}},"schemas":{"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"SalesAutomation":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/SalesAutomationId"},"object":{"type":"string","enum":["sales_automation"]},"name":{"type":"string"},"flow_id":{"allOf":[{"$ref":"#/components/schemas/FlowId"}],"nullable":true,"description":"Set when this rule belongs to a flow node rather than standing alone. A flow-scoped rule has no schedule of its own — the flow decides when it runs, its `trigger.type` is always `condition`, and the standalone CRM runner skips it. Null means it is a free-standing rule that runs on its own trigger.\n"},"flow_node_id":{"type":"string","nullable":true,"description":"The specific flow node this rule is attached to. Null for a free-standing rule."},"pipeline_id":{"$ref":"#/components/schemas/PipelineId","nullable":true,"description":"The pipeline the rule is listed under. A null here means the rule runs but is invisible in the dashboard's CRM automations list, which filters on it."},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom this rule lives in. An `added_to_segments` trigger can only reference segments from the same workroom."},"status":{"type":"string","enum":["active","paused","inactive","completed"],"default":"active","description":"Status of the automation: `active` (runs on trigger), `paused` (temporarily disabled, does not fire), `inactive` (staged, not live), or `completed`. Defaults to `active`.\n"},"paused":{"type":"boolean","description":"True when the rule is paused or auto-disabled. A paused rule does not run until resumed with `status: active`."},"broken":{"type":"boolean","description":"True when the rule is missing required references (e.g. its trigger segment was deleted) and cannot fire."},"execute_on":{"type":"string","enum":["ongoing","onetime"]},"processed_count":{"type":"integer"},"trigger":{"$ref":"#/components/schemas/SalesAutomationTrigger"},"action":{"allOf":[{"$ref":"#/components/schemas/SalesAutomationAction"}],"description":"The FIRST action only, kept for backward compatibility. Prefer `actions`."},"actions":{"type":"array","description":"Every action on the rule, in the order the cron runs them.","items":{"$ref":"#/components/schemas/SalesAutomationAction"}},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"updated_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"last_processed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true}}},"SalesAutomationId":{"type":"string","pattern":"^saut_[0-9a-f]{24}$"},"FlowId":{"type":"string","pattern":"^flw_[0-9A-HJKMNP-TV-Z]{26}$"},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"SalesAutomationTrigger":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Dashboard labels, in the same order the UI lists them: `added_to_segments` = \"Added to a Segment\", `after_x_days` = \"After X Days in a Stage\", `no_response_in_x` = \"No Response in X Days\", `received_response_in_x` = \"Received a Response in X Days\", `after_completing` = \"After Completing Tasks\", `condition` = \"Condition\".\n\n`after_completing` is the **task-completed** trigger — it fires when the tasks on a contact in the given stage are checked off by a staff member. Use it for \"when a task is completed, do X\".\n","enum":["added_to_segments","after_x_days","condition","after_completing","no_response_in_x","received_response_in_x"]},"segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"For `added_to_segments`."},"days":{"type":"integer","description":"For `after_x_days`, `no_response_in_x`, `received_response_in_x`."},"conditions":{"type":"array","description":"For `condition`. Array of segment DSL conditions.","items":{"$ref":"#/components/schemas/SegmentCondition"}},"stage":{"type":"string","description":"Pipeline stage **name** (an ID is accepted and converted to the name). Applies to every trigger except `added_to_segments`, which is stage-less.\n\nOptional. Omit it and the rule applies to every stage in the pipeline, which runs correctly — but the dashboard's automation editor requires a stage and will not let anyone re-save the rule until one is set, so prefer naming one. The response carries a `no_trigger_stage` warning when omitted.\n\nA stage that is not in this rule's own pipeline IS rejected: matching is by name within `pipeline_id`, so a name borrowed from another pipeline matches nothing and the rule never fires. Call `listPipelineStages` for valid names.\n"}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"SalesAutomationAction":{"type":"object","required":["type"],"description":"Polymorphic on `type`. 13 action types available — see `describeFlowSchema` for the full guide + params per action.\n","properties":{"type":{"type":"string","enum":["tags","remove_tags","task","add_stage","move_stage","sync_stage","remove_stage","assign","remove_assign","status","priority","add_note","enroll_in_flow"]},"tag_names":{"type":"array","items":{"type":"string"},"description":"For `tags` / `remove_tags`."},"task_name":{"type":"string","description":"For `task`."},"description":{"type":"string","description":"For `task`."},"due_at":{"$ref":"#/components/schemas/Timestamp","description":"For `task` (write only; converted to `due_in_days`)."},"due_in_days":{"type":"integer","description":"For `task`. Days from the trigger until the task is due. Default 1."},"assignee_staff_id":{"$ref":"#/components/schemas/StaffId","description":"For `task`: one responsible (\"Specific\"). Omit both assignee fields for the contact owner (\"Owner\")."},"assignee_staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `task`: round-robin across these staff."},"assignee_mode":{"type":"string","readOnly":true,"enum":["Owner","Specific","Round Robin"],"description":"For `task`, read only."},"task_type":{"type":"string","description":"For `task`: task type id (`tst_…`). Defaults to the workroom's first type."},"stage_id":{"$ref":"#/components/schemas/StageId","description":"For stage actions. Required: a stage action with no valid stage is rejected (422), since the worker cannot run it."},"staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `assign` / `remove_assign`. Required (non-empty)."},"distribution":{"type":"string","enum":["All","Round Robin"],"description":"For `assign`. Other values (including the dashboard's \"Round Robin By Day\", which needs a per-day roster) are stored as `All` with a warning."},"reassign":{"type":"boolean","default":false,"description":"For `assign`: true replaces a contact's existing responsible; false only fills unassigned contacts."},"value":{"type":"string","description":"For `status` / `priority`."},"note":{"type":"string","description":"For `add_note`."},"flow_id":{"type":"string","description":"For `enroll_in_flow`."},"applies_to":{"type":"string","description":"Segment scope — usually \"All\" or a segment name.","default":"All"}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"}}},"paths":{"/sales_automations":{"get":{"tags":["Sales Automations"],"operationId":"listSalesAutomations","summary":"List sales-automation rules.","description":"CRM rules that fire on a pipeline event — a stage change, a task completion, a segment entry — and run actions such as creating a task or moving a stage. Rules created by flow nodes are excluded by default; pass `source` to include them.\n\nA legacy rule stored without a `pipeline_id` runs but is not shown in the dashboard's automations list. Such rules are returned as stored (`pipeline_id: null`) together with their `workroom_id`, so they can be found and bound explicitly with `PATCH` — this endpoint does not write to them.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["pipeline","flow","all"],"default":"pipeline"},"description":"Filter rules by source. `pipeline` (default) returns standalone CRM pipeline rules; `flow` returns rules generated by flow nodes; `all` returns both."},{"name":"pipeline_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/PipelineId"},"description":"Filter rules by pipeline ID."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","paused","inactive","completed"]},"description":"Filter rules by status."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SalesAutomation"}}}}]}}}}}}}}}
```

## Create a reusable CRM automation rule.

> 13 action types, 7 trigger types. Also referenceable from flow \`sales\_automation\` nodes via \`salesautomation\_id\`, OR passed inline on the flow node itself. The full action and trigger catalog, with examples, is returned by \`describeFlowSchema\`.\
> \
> \*\*A rule lives under a pipeline.\*\* The dashboard's CRM automations list filters on \`pipeline\_id\`, so a rule without one runs but never appears in the UI. Omit \`pipeline\_id\` and the workroom's default pipeline is used — the response says which, via a \`pipeline\_defaulted:…\` warning. Pass it explicitly when the rule belongs to a specific pipeline.\
> \
> \*\*\`added\_to\_segments\` segments are verified.\*\* Each ID must be a real segment in this rule's workroom (compare \`Segment.workroom\_id\` with the rule's \`workroom\_id\`); an unknown or sibling-workroom ID is rejected with \`422\`, because such a rule would show a blank trigger in the editor and match nobody. Always read the response's \`warnings\[]\` — it names any reference that was dropped or defaulted (\`unknown\_stage\_id:…\`, \`task\_missing\_assignee\`, …).\
> \
> With trigger \`added\_to\_segments\` the rule fires on one specific segment, identified by ID. Segment names are not unique and often similar — "test entry" and "Tag: test" are unrelated segments — so a name match is not a reliable identifier. \`listSegments\` returns the available segments with their IDs.\
> \
> Requires the trigger, the stage it applies to and what the action(s) should do. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Sales Automations","description":"Reusable CRM automation rules. 13 action types (task, tags, assign, add_stage, ...) and 7 trigger types (added_to_segments, after_x_days, condition, ...). Referenced by flow `sales_automation` nodes."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"SalesAutomationCreate":{"type":"object","required":["name","trigger"],"anyOf":[{"required":["actions"]},{"required":["action"]}],"properties":{"name":{"type":"string"},"pipeline_id":{"$ref":"#/components/schemas/PipelineId","description":"The pipeline this rule belongs to. Defaults to the workroom default pipeline; if the workroom has no pipeline, pipeline_id is required so the rule is visible in the dashboard."},"execute_on":{"type":"string","enum":["ongoing","onetime"],"default":"ongoing"},"status":{"type":"string","enum":["active","paused","inactive"],"default":"active","description":"`active` (default), `paused`, or `inactive`. Pass `paused` to create a rule in a paused state."},"paused":{"type":"boolean","default":false,"description":"Pass true to create the rule in a paused state."},"trigger":{"$ref":"#/components/schemas/SalesAutomationTrigger","description":"Pipeline-scoped triggers (`after_x_days`, `after_completing`, `no_response_in_x`, `received_response_in_x`) need a pipeline: in a workroom with none, create returns 422."},"actions":{"type":"array","minItems":1,"description":"One or more actions, run in order by the same rule — this is the dashboard's \"Add Action\" button. Prefer this over `action`.\n\nSupply either `actions` or `action`; if both are sent, `actions` wins and the response carries an `action_ignored` warning.\n","items":{"$ref":"#/components/schemas/SalesAutomationAction"}},"action":{"allOf":[{"$ref":"#/components/schemas/SalesAutomationAction"}],"description":"A single action. Equivalent to `actions` with one entry."}}},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"SalesAutomationTrigger":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Dashboard labels, in the same order the UI lists them: `added_to_segments` = \"Added to a Segment\", `after_x_days` = \"After X Days in a Stage\", `no_response_in_x` = \"No Response in X Days\", `received_response_in_x` = \"Received a Response in X Days\", `after_completing` = \"After Completing Tasks\", `condition` = \"Condition\".\n\n`after_completing` is the **task-completed** trigger — it fires when the tasks on a contact in the given stage are checked off by a staff member. Use it for \"when a task is completed, do X\".\n","enum":["added_to_segments","after_x_days","condition","after_completing","no_response_in_x","received_response_in_x"]},"segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"For `added_to_segments`."},"days":{"type":"integer","description":"For `after_x_days`, `no_response_in_x`, `received_response_in_x`."},"conditions":{"type":"array","description":"For `condition`. Array of segment DSL conditions.","items":{"$ref":"#/components/schemas/SegmentCondition"}},"stage":{"type":"string","description":"Pipeline stage **name** (an ID is accepted and converted to the name). Applies to every trigger except `added_to_segments`, which is stage-less.\n\nOptional. Omit it and the rule applies to every stage in the pipeline, which runs correctly — but the dashboard's automation editor requires a stage and will not let anyone re-save the rule until one is set, so prefer naming one. The response carries a `no_trigger_stage` warning when omitted.\n\nA stage that is not in this rule's own pipeline IS rejected: matching is by name within `pipeline_id`, so a name borrowed from another pipeline matches nothing and the rule never fires. Call `listPipelineStages` for valid names.\n"}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"SalesAutomationAction":{"type":"object","required":["type"],"description":"Polymorphic on `type`. 13 action types available — see `describeFlowSchema` for the full guide + params per action.\n","properties":{"type":{"type":"string","enum":["tags","remove_tags","task","add_stage","move_stage","sync_stage","remove_stage","assign","remove_assign","status","priority","add_note","enroll_in_flow"]},"tag_names":{"type":"array","items":{"type":"string"},"description":"For `tags` / `remove_tags`."},"task_name":{"type":"string","description":"For `task`."},"description":{"type":"string","description":"For `task`."},"due_at":{"$ref":"#/components/schemas/Timestamp","description":"For `task` (write only; converted to `due_in_days`)."},"due_in_days":{"type":"integer","description":"For `task`. Days from the trigger until the task is due. Default 1."},"assignee_staff_id":{"$ref":"#/components/schemas/StaffId","description":"For `task`: one responsible (\"Specific\"). Omit both assignee fields for the contact owner (\"Owner\")."},"assignee_staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `task`: round-robin across these staff."},"assignee_mode":{"type":"string","readOnly":true,"enum":["Owner","Specific","Round Robin"],"description":"For `task`, read only."},"task_type":{"type":"string","description":"For `task`: task type id (`tst_…`). Defaults to the workroom's first type."},"stage_id":{"$ref":"#/components/schemas/StageId","description":"For stage actions. Required: a stage action with no valid stage is rejected (422), since the worker cannot run it."},"staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `assign` / `remove_assign`. Required (non-empty)."},"distribution":{"type":"string","enum":["All","Round Robin"],"description":"For `assign`. Other values (including the dashboard's \"Round Robin By Day\", which needs a per-day roster) are stored as `All` with a warning."},"reassign":{"type":"boolean","default":false,"description":"For `assign`: true replaces a contact's existing responsible; false only fills unassigned contacts."},"value":{"type":"string","description":"For `status` / `priority`."},"note":{"type":"string","description":"For `add_note`."},"flow_id":{"type":"string","description":"For `enroll_in_flow`."},"applies_to":{"type":"string","description":"Segment scope — usually \"All\" or a segment name.","default":"All"}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"SalesAutomation":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/SalesAutomationId"},"object":{"type":"string","enum":["sales_automation"]},"name":{"type":"string"},"flow_id":{"allOf":[{"$ref":"#/components/schemas/FlowId"}],"nullable":true,"description":"Set when this rule belongs to a flow node rather than standing alone. A flow-scoped rule has no schedule of its own — the flow decides when it runs, its `trigger.type` is always `condition`, and the standalone CRM runner skips it. Null means it is a free-standing rule that runs on its own trigger.\n"},"flow_node_id":{"type":"string","nullable":true,"description":"The specific flow node this rule is attached to. Null for a free-standing rule."},"pipeline_id":{"$ref":"#/components/schemas/PipelineId","nullable":true,"description":"The pipeline the rule is listed under. A null here means the rule runs but is invisible in the dashboard's CRM automations list, which filters on it."},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom this rule lives in. An `added_to_segments` trigger can only reference segments from the same workroom."},"status":{"type":"string","enum":["active","paused","inactive","completed"],"default":"active","description":"Status of the automation: `active` (runs on trigger), `paused` (temporarily disabled, does not fire), `inactive` (staged, not live), or `completed`. Defaults to `active`.\n"},"paused":{"type":"boolean","description":"True when the rule is paused or auto-disabled. A paused rule does not run until resumed with `status: active`."},"broken":{"type":"boolean","description":"True when the rule is missing required references (e.g. its trigger segment was deleted) and cannot fire."},"execute_on":{"type":"string","enum":["ongoing","onetime"]},"processed_count":{"type":"integer"},"trigger":{"$ref":"#/components/schemas/SalesAutomationTrigger"},"action":{"allOf":[{"$ref":"#/components/schemas/SalesAutomationAction"}],"description":"The FIRST action only, kept for backward compatibility. Prefer `actions`."},"actions":{"type":"array","description":"Every action on the rule, in the order the cron runs them.","items":{"$ref":"#/components/schemas/SalesAutomationAction"}},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"updated_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"last_processed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true}}},"SalesAutomationId":{"type":"string","pattern":"^saut_[0-9a-f]{24}$"},"FlowId":{"type":"string","pattern":"^flw_[0-9A-HJKMNP-TV-Z]{26}$"},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"}}},"paths":{"/sales_automations":{"post":{"tags":["Sales Automations"],"operationId":"createSalesAutomation","summary":"Create a reusable CRM automation rule.","description":"13 action types, 7 trigger types. Also referenceable from flow `sales_automation` nodes via `salesautomation_id`, OR passed inline on the flow node itself. The full action and trigger catalog, with examples, is returned by `describeFlowSchema`.\n\n**A rule lives under a pipeline.** The dashboard's CRM automations list filters on `pipeline_id`, so a rule without one runs but never appears in the UI. Omit `pipeline_id` and the workroom's default pipeline is used — the response says which, via a `pipeline_defaulted:…` warning. Pass it explicitly when the rule belongs to a specific pipeline.\n\n**`added_to_segments` segments are verified.** Each ID must be a real segment in this rule's workroom (compare `Segment.workroom_id` with the rule's `workroom_id`); an unknown or sibling-workroom ID is rejected with `422`, because such a rule would show a blank trigger in the editor and match nobody. Always read the response's `warnings[]` — it names any reference that was dropped or defaulted (`unknown_stage_id:…`, `task_missing_assignee`, …).\n\nWith trigger `added_to_segments` the rule fires on one specific segment, identified by ID. Segment names are not unique and often similar — \"test entry\" and \"Tag: test\" are unrelated segments — so a name match is not a reliable identifier. `listSegments` returns the available segments with their IDs.\n\nRequires the trigger, the stage it applies to and what the action(s) should do. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesAutomationCreate"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesAutomation"}}}}}}}}}
```

## Retrieve one sales-automation rule.

> Its trigger, the stage it applies to, and every action it runs. Actions come back as \`actions\[]\`; \`action\` repeats the first for compatibility.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Sales Automations","description":"Reusable CRM automation rules. 13 action types (task, tags, assign, add_stage, ...) and 7 trigger types (added_to_segments, after_x_days, condition, ...). Referenced by flow `sales_automation` nodes."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"SalesAutomation":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/SalesAutomationId"},"object":{"type":"string","enum":["sales_automation"]},"name":{"type":"string"},"flow_id":{"allOf":[{"$ref":"#/components/schemas/FlowId"}],"nullable":true,"description":"Set when this rule belongs to a flow node rather than standing alone. A flow-scoped rule has no schedule of its own — the flow decides when it runs, its `trigger.type` is always `condition`, and the standalone CRM runner skips it. Null means it is a free-standing rule that runs on its own trigger.\n"},"flow_node_id":{"type":"string","nullable":true,"description":"The specific flow node this rule is attached to. Null for a free-standing rule."},"pipeline_id":{"$ref":"#/components/schemas/PipelineId","nullable":true,"description":"The pipeline the rule is listed under. A null here means the rule runs but is invisible in the dashboard's CRM automations list, which filters on it."},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom this rule lives in. An `added_to_segments` trigger can only reference segments from the same workroom."},"status":{"type":"string","enum":["active","paused","inactive","completed"],"default":"active","description":"Status of the automation: `active` (runs on trigger), `paused` (temporarily disabled, does not fire), `inactive` (staged, not live), or `completed`. Defaults to `active`.\n"},"paused":{"type":"boolean","description":"True when the rule is paused or auto-disabled. A paused rule does not run until resumed with `status: active`."},"broken":{"type":"boolean","description":"True when the rule is missing required references (e.g. its trigger segment was deleted) and cannot fire."},"execute_on":{"type":"string","enum":["ongoing","onetime"]},"processed_count":{"type":"integer"},"trigger":{"$ref":"#/components/schemas/SalesAutomationTrigger"},"action":{"allOf":[{"$ref":"#/components/schemas/SalesAutomationAction"}],"description":"The FIRST action only, kept for backward compatibility. Prefer `actions`."},"actions":{"type":"array","description":"Every action on the rule, in the order the cron runs them.","items":{"$ref":"#/components/schemas/SalesAutomationAction"}},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"updated_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"last_processed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true}}},"SalesAutomationId":{"type":"string","pattern":"^saut_[0-9a-f]{24}$"},"FlowId":{"type":"string","pattern":"^flw_[0-9A-HJKMNP-TV-Z]{26}$"},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"SalesAutomationTrigger":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Dashboard labels, in the same order the UI lists them: `added_to_segments` = \"Added to a Segment\", `after_x_days` = \"After X Days in a Stage\", `no_response_in_x` = \"No Response in X Days\", `received_response_in_x` = \"Received a Response in X Days\", `after_completing` = \"After Completing Tasks\", `condition` = \"Condition\".\n\n`after_completing` is the **task-completed** trigger — it fires when the tasks on a contact in the given stage are checked off by a staff member. Use it for \"when a task is completed, do X\".\n","enum":["added_to_segments","after_x_days","condition","after_completing","no_response_in_x","received_response_in_x"]},"segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"For `added_to_segments`."},"days":{"type":"integer","description":"For `after_x_days`, `no_response_in_x`, `received_response_in_x`."},"conditions":{"type":"array","description":"For `condition`. Array of segment DSL conditions.","items":{"$ref":"#/components/schemas/SegmentCondition"}},"stage":{"type":"string","description":"Pipeline stage **name** (an ID is accepted and converted to the name). Applies to every trigger except `added_to_segments`, which is stage-less.\n\nOptional. Omit it and the rule applies to every stage in the pipeline, which runs correctly — but the dashboard's automation editor requires a stage and will not let anyone re-save the rule until one is set, so prefer naming one. The response carries a `no_trigger_stage` warning when omitted.\n\nA stage that is not in this rule's own pipeline IS rejected: matching is by name within `pipeline_id`, so a name borrowed from another pipeline matches nothing and the rule never fires. Call `listPipelineStages` for valid names.\n"}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"SalesAutomationAction":{"type":"object","required":["type"],"description":"Polymorphic on `type`. 13 action types available — see `describeFlowSchema` for the full guide + params per action.\n","properties":{"type":{"type":"string","enum":["tags","remove_tags","task","add_stage","move_stage","sync_stage","remove_stage","assign","remove_assign","status","priority","add_note","enroll_in_flow"]},"tag_names":{"type":"array","items":{"type":"string"},"description":"For `tags` / `remove_tags`."},"task_name":{"type":"string","description":"For `task`."},"description":{"type":"string","description":"For `task`."},"due_at":{"$ref":"#/components/schemas/Timestamp","description":"For `task` (write only; converted to `due_in_days`)."},"due_in_days":{"type":"integer","description":"For `task`. Days from the trigger until the task is due. Default 1."},"assignee_staff_id":{"$ref":"#/components/schemas/StaffId","description":"For `task`: one responsible (\"Specific\"). Omit both assignee fields for the contact owner (\"Owner\")."},"assignee_staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `task`: round-robin across these staff."},"assignee_mode":{"type":"string","readOnly":true,"enum":["Owner","Specific","Round Robin"],"description":"For `task`, read only."},"task_type":{"type":"string","description":"For `task`: task type id (`tst_…`). Defaults to the workroom's first type."},"stage_id":{"$ref":"#/components/schemas/StageId","description":"For stage actions. Required: a stage action with no valid stage is rejected (422), since the worker cannot run it."},"staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `assign` / `remove_assign`. Required (non-empty)."},"distribution":{"type":"string","enum":["All","Round Robin"],"description":"For `assign`. Other values (including the dashboard's \"Round Robin By Day\", which needs a per-day roster) are stored as `All` with a warning."},"reassign":{"type":"boolean","default":false,"description":"For `assign`: true replaces a contact's existing responsible; false only fills unassigned contacts."},"value":{"type":"string","description":"For `status` / `priority`."},"note":{"type":"string","description":"For `add_note`."},"flow_id":{"type":"string","description":"For `enroll_in_flow`."},"applies_to":{"type":"string","description":"Segment scope — usually \"All\" or a segment name.","default":"All"}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"}}},"paths":{"/sales_automations/{id}":{"get":{"tags":["Sales Automations"],"operationId":"retrieveSalesAutomation","summary":"Retrieve one sales-automation rule.","description":"Its trigger, the stage it applies to, and every action it runs. Actions come back as `actions[]`; `action` repeats the first for compatibility.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesAutomation"}}}}}}}}}
```

## Update a sales-automation rule.

> Patches the trigger, trigger stage or actions. Passing \`actions\[]\` replaces the whole action list; omitted fields are left unchanged. An action the worker cannot run (stage action without a valid stage, \`enroll\_in\_flow\` without flows, \`assign\` without staff) returns 422 \`invalid\_action\`. Setting \`status: 1\` also clears \`paused\`, as the dashboard's Resume does.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Sales Automations","description":"Reusable CRM automation rules. 13 action types (task, tags, assign, add_stage, ...) and 7 trigger types (added_to_segments, after_x_days, condition, ...). Referenced by flow `sales_automation` nodes."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"SalesAutomationCreate":{"type":"object","required":["name","trigger"],"anyOf":[{"required":["actions"]},{"required":["action"]}],"properties":{"name":{"type":"string"},"pipeline_id":{"$ref":"#/components/schemas/PipelineId","description":"The pipeline this rule belongs to. Defaults to the workroom default pipeline; if the workroom has no pipeline, pipeline_id is required so the rule is visible in the dashboard."},"execute_on":{"type":"string","enum":["ongoing","onetime"],"default":"ongoing"},"status":{"type":"string","enum":["active","paused","inactive"],"default":"active","description":"`active` (default), `paused`, or `inactive`. Pass `paused` to create a rule in a paused state."},"paused":{"type":"boolean","default":false,"description":"Pass true to create the rule in a paused state."},"trigger":{"$ref":"#/components/schemas/SalesAutomationTrigger","description":"Pipeline-scoped triggers (`after_x_days`, `after_completing`, `no_response_in_x`, `received_response_in_x`) need a pipeline: in a workroom with none, create returns 422."},"actions":{"type":"array","minItems":1,"description":"One or more actions, run in order by the same rule — this is the dashboard's \"Add Action\" button. Prefer this over `action`.\n\nSupply either `actions` or `action`; if both are sent, `actions` wins and the response carries an `action_ignored` warning.\n","items":{"$ref":"#/components/schemas/SalesAutomationAction"}},"action":{"allOf":[{"$ref":"#/components/schemas/SalesAutomationAction"}],"description":"A single action. Equivalent to `actions` with one entry."}}},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"SalesAutomationTrigger":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Dashboard labels, in the same order the UI lists them: `added_to_segments` = \"Added to a Segment\", `after_x_days` = \"After X Days in a Stage\", `no_response_in_x` = \"No Response in X Days\", `received_response_in_x` = \"Received a Response in X Days\", `after_completing` = \"After Completing Tasks\", `condition` = \"Condition\".\n\n`after_completing` is the **task-completed** trigger — it fires when the tasks on a contact in the given stage are checked off by a staff member. Use it for \"when a task is completed, do X\".\n","enum":["added_to_segments","after_x_days","condition","after_completing","no_response_in_x","received_response_in_x"]},"segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"For `added_to_segments`."},"days":{"type":"integer","description":"For `after_x_days`, `no_response_in_x`, `received_response_in_x`."},"conditions":{"type":"array","description":"For `condition`. Array of segment DSL conditions.","items":{"$ref":"#/components/schemas/SegmentCondition"}},"stage":{"type":"string","description":"Pipeline stage **name** (an ID is accepted and converted to the name). Applies to every trigger except `added_to_segments`, which is stage-less.\n\nOptional. Omit it and the rule applies to every stage in the pipeline, which runs correctly — but the dashboard's automation editor requires a stage and will not let anyone re-save the rule until one is set, so prefer naming one. The response carries a `no_trigger_stage` warning when omitted.\n\nA stage that is not in this rule's own pipeline IS rejected: matching is by name within `pipeline_id`, so a name borrowed from another pipeline matches nothing and the rule never fires. Call `listPipelineStages` for valid names.\n"}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"SalesAutomationAction":{"type":"object","required":["type"],"description":"Polymorphic on `type`. 13 action types available — see `describeFlowSchema` for the full guide + params per action.\n","properties":{"type":{"type":"string","enum":["tags","remove_tags","task","add_stage","move_stage","sync_stage","remove_stage","assign","remove_assign","status","priority","add_note","enroll_in_flow"]},"tag_names":{"type":"array","items":{"type":"string"},"description":"For `tags` / `remove_tags`."},"task_name":{"type":"string","description":"For `task`."},"description":{"type":"string","description":"For `task`."},"due_at":{"$ref":"#/components/schemas/Timestamp","description":"For `task` (write only; converted to `due_in_days`)."},"due_in_days":{"type":"integer","description":"For `task`. Days from the trigger until the task is due. Default 1."},"assignee_staff_id":{"$ref":"#/components/schemas/StaffId","description":"For `task`: one responsible (\"Specific\"). Omit both assignee fields for the contact owner (\"Owner\")."},"assignee_staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `task`: round-robin across these staff."},"assignee_mode":{"type":"string","readOnly":true,"enum":["Owner","Specific","Round Robin"],"description":"For `task`, read only."},"task_type":{"type":"string","description":"For `task`: task type id (`tst_…`). Defaults to the workroom's first type."},"stage_id":{"$ref":"#/components/schemas/StageId","description":"For stage actions. Required: a stage action with no valid stage is rejected (422), since the worker cannot run it."},"staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `assign` / `remove_assign`. Required (non-empty)."},"distribution":{"type":"string","enum":["All","Round Robin"],"description":"For `assign`. Other values (including the dashboard's \"Round Robin By Day\", which needs a per-day roster) are stored as `All` with a warning."},"reassign":{"type":"boolean","default":false,"description":"For `assign`: true replaces a contact's existing responsible; false only fills unassigned contacts."},"value":{"type":"string","description":"For `status` / `priority`."},"note":{"type":"string","description":"For `add_note`."},"flow_id":{"type":"string","description":"For `enroll_in_flow`."},"applies_to":{"type":"string","description":"Segment scope — usually \"All\" or a segment name.","default":"All"}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"SalesAutomation":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/SalesAutomationId"},"object":{"type":"string","enum":["sales_automation"]},"name":{"type":"string"},"flow_id":{"allOf":[{"$ref":"#/components/schemas/FlowId"}],"nullable":true,"description":"Set when this rule belongs to a flow node rather than standing alone. A flow-scoped rule has no schedule of its own — the flow decides when it runs, its `trigger.type` is always `condition`, and the standalone CRM runner skips it. Null means it is a free-standing rule that runs on its own trigger.\n"},"flow_node_id":{"type":"string","nullable":true,"description":"The specific flow node this rule is attached to. Null for a free-standing rule."},"pipeline_id":{"$ref":"#/components/schemas/PipelineId","nullable":true,"description":"The pipeline the rule is listed under. A null here means the rule runs but is invisible in the dashboard's CRM automations list, which filters on it."},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom this rule lives in. An `added_to_segments` trigger can only reference segments from the same workroom."},"status":{"type":"string","enum":["active","paused","inactive","completed"],"default":"active","description":"Status of the automation: `active` (runs on trigger), `paused` (temporarily disabled, does not fire), `inactive` (staged, not live), or `completed`. Defaults to `active`.\n"},"paused":{"type":"boolean","description":"True when the rule is paused or auto-disabled. A paused rule does not run until resumed with `status: active`."},"broken":{"type":"boolean","description":"True when the rule is missing required references (e.g. its trigger segment was deleted) and cannot fire."},"execute_on":{"type":"string","enum":["ongoing","onetime"]},"processed_count":{"type":"integer"},"trigger":{"$ref":"#/components/schemas/SalesAutomationTrigger"},"action":{"allOf":[{"$ref":"#/components/schemas/SalesAutomationAction"}],"description":"The FIRST action only, kept for backward compatibility. Prefer `actions`."},"actions":{"type":"array","description":"Every action on the rule, in the order the cron runs them.","items":{"$ref":"#/components/schemas/SalesAutomationAction"}},"created_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"updated_by":{"$ref":"#/components/schemas/StaffId","nullable":true},"created_at":{"$ref":"#/components/schemas/Timestamp"},"last_processed_at":{"$ref":"#/components/schemas/Timestamp","nullable":true}}},"SalesAutomationId":{"type":"string","pattern":"^saut_[0-9a-f]{24}$"},"FlowId":{"type":"string","pattern":"^flw_[0-9A-HJKMNP-TV-Z]{26}$"},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"}}},"paths":{"/sales_automations/{id}":{"patch":{"tags":["Sales Automations"],"operationId":"updateSalesAutomation","summary":"Update a sales-automation rule.","description":"Patches the trigger, trigger stage or actions. Passing `actions[]` replaces the whole action list; omitted fields are left unchanged. An action the worker cannot run (stage action without a valid stage, `enroll_in_flow` without flows, `assign` without staff) returns 422 `invalid_action`. Setting `status: 1` also clears `paused`, as the dashboard's Resume does.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesAutomationCreate"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesAutomation"}}}}}}}}}
```

## DELETE /sales\_automations/{id}

> \*\*Permanent.\*\* There is no undo and no trash to restore from. Anything that references the deleted record is affected too.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Sales Automations","description":"Reusable CRM automation rules. 13 action types (task, tags, assign, add_stage, ...) and 7 trigger types (added_to_segments, after_x_days, condition, ...). Referenced by flow `sales_automation` nodes."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}}},"paths":{"/sales_automations/{id}":{"delete":{"tags":["Sales Automations"],"operationId":"deleteSalesAutomation","description":"**Permanent.** There is no undo and no trash to restore from. Anything that references the deleted record is affected too.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"responses":{"204":{"description":"Deleted."}}}}}}
```
