Enroll a selected sequence audience

This page documents the canonical HTTP contract for this endpoint.

Requires an authenticated user session. The current HTTP scope resolver rejects developer API keys, even though the operation catalog declares command scopes.

selection follows this exact structure: {"mode":"ids","ids":["<LEAD_ID>"]} or {"mode":"descriptor","descriptor":{"root":{"kind":"rule","field":"lead_status","operator":"eq","value":"qualified"}}}. The shared selection object may also carry search, sort, limit, scope, source_table_id, and source_table_scope; descriptor selections use descriptor.root directly (no extra filter or filters wrapper). This is the selection-based counterpart to exact-ID enrollment. The server resolves selection criteria; callers do not need to expand every matching Lead ID themselves. Provide exactly one of selection or leadIds.

The queued response confirms asynchronous admission. Poll GET /api/operation-runs/{operation_run_id} using the returned operationRunId or operation_run_id for canonical progress. Developer keys need jobs:read for that read; this enrollment route itself still requires a user session. The native task_id is available through bulk-job status for executor diagnostics.

If no leads are eligible, the API returns status=noop. Without an idempotency key, task_id=null and no operation ID is returned. With idempotencyKey, the server persists a terminal no-op outcome and returns task and canonical operation IDs for replay. Inspect skip reasons and poll only identities actually returned.

Native Command Center enrollment remains sensitive under Approve for me, including manual-only or review-only enrollment; automatic sequence activation does not approve adding Leads. Combined launch-and-enroll actions also require approval. HTTP and CLI keep their existing explicit authenticated invocation and scope requirements.

Normal enrollment requires an ACTIVE sequence. reviewOnly=true is a mutating staging action: it creates paused enrollment records and skips sending side effects, including when the sequence is DRAFT or PAUSED. Use audience preview for read-only eligibility checks. A table-linked selection must identify CRM Lead records, typically from a Sync to Leads result.

Path parameters

sequence_idrequired
string
Sequence ID.

Name	Type	Description
sequence_idrequired	string	Sequence ID.

Query parameters

actorUserId · optional
string | null
Optional actor override, resolved as a same-organization active user.

Name	Type	Description
actorUserId	string \| null	Optional actor override, resolved as a same-organization active user.

Body parameters

assignedToUserId · optional
string | null
Assignee for generated sequence tasks.
assignmentPlan · optional
array<object> | null
Optional assignment routes.
idempotencyKey · optional
string | null
Optional 8-200 character key for retrying the same admission input. maxLength: 200; minLength: 8
leadIds · optional
array<string> | null
Explicit existing CRM Lead IDs. Provide this or selection.
processLimit · optional
integer | null
Optional upper bound on leads processed.
researchContext · optional
object | null
Optional research context attached to generated tasks.
reviewOnly · optional
boolean | null
Stage paused enrollment records and skip sending side effects. This mutation also permits DRAFT or PAUSED sequences; use audience preview for read-only checks.
routingMode · optional
string | null
single, round_robin, or weighted_round_robin. enum: ["single","round_robin","weighted_round_robin"]
scope · optional
string | null
Lead selection scope.
selection · optional
BulkSelectionModel | null
BulkSelectionModel: {mode:"ids",ids:[...]} or {mode:"descriptor",descriptor:{root:<FilterNode>}}. Descriptor root is a rule or group with kind, field/operator/value or logic/children. Provide this or leadIds.
senderAccountIds · optional
object | null
Optional channel-to-sender account IDs.
senderBindings · optional
object | null
Optional explicit sender bindings.
skipActiveSequenceConflicts · optional
boolean | null
Override the selected sequence conflict policy. Omitted/null inherits the sequence setting; explicitly send true for the CRM operation default. Account exclusions remain sequence-level.
sourceTableId · optional
string | null
Research table context for resolving a descriptor selection.
sourceTableScope · optional
string | null
Research table scope, such as company or lead.
startDate · optional
string | null
Optional enrollment start timestamp.
updateLeadOwner · optional
boolean | null
Update each Lead owner to the resolved assignee.
variableMap · optional
object | null
Optional sequence variable mapping.
variableOverrides · optional
object | null
Optional variable overrides.

Name	Type	Description
assignedToUserId	string \| null	Assignee for generated sequence tasks.
assignmentPlan	array<object> \| null	Optional assignment routes.
idempotencyKey	string \| null	Optional 8-200 character key for retrying the same admission input. maxLength: 200; minLength: 8
leadIds	array<string> \| null	Explicit existing CRM Lead IDs. Provide this or selection.
processLimit	integer \| null	Optional upper bound on leads processed.
researchContext	object \| null	Optional research context attached to generated tasks.
reviewOnly	boolean \| null	Stage paused enrollment records and skip sending side effects. This mutation also permits DRAFT or PAUSED sequences; use audience preview for read-only checks.
routingMode	string \| null	single, round_robin, or weighted_round_robin. enum: ["single","round_robin","weighted_round_robin"]
scope	string \| null	Lead selection scope.
selection	BulkSelectionModel \| null	BulkSelectionModel: {mode:"ids",ids:[...]} or {mode:"descriptor",descriptor:{root:<FilterNode>}}. Descriptor root is a rule or group with kind, field/operator/value or logic/children. Provide this or leadIds.
senderAccountIds	object \| null	Optional channel-to-sender account IDs.
senderBindings	object \| null	Optional explicit sender bindings.
skipActiveSequenceConflicts	boolean \| null	Override the selected sequence conflict policy. Omitted/null inherits the sequence setting; explicitly send true for the CRM operation default. Account exclusions remain sequence-level.
sourceTableId	string \| null	Research table context for resolving a descriptor selection.
sourceTableScope	string \| null	Research table scope, such as company or lead.
startDate	string \| null	Optional enrollment start timestamp.
updateLeadOwner	boolean \| null	Update each Lead owner to the resolved assignee.
variableMap	object \| null	Optional sequence variable mapping.
variableOverrides	object \| null	Optional variable overrides.

Definitions

BulkSelectionModel

Fields

descriptor · optional
FilterDescriptor | null
ids · optional
array<string> | null
include_skipped · optional
boolean | null
limit · optional
integer | null
moderequired
string
pattern: "^(ids|descriptor)$"
scope · optional
string | null
search · optional
string | null
sort · optional
array<SortSpecModel> | null
source_table_id · optional
string | null
source_table_scope · optional
string | null

Name	Type	Description
descriptor	FilterDescriptor \| null	-
ids	array<string> \| null	-
include_skipped	boolean \| null	-
limit	integer \| null	-
moderequired	string	pattern: "^(ids\|descriptor)$"
scope	string \| null	-
search	string \| null	-
sort	array<SortSpecModel> \| null	-
source_table_id	string \| null	-
source_table_scope	string \| null	-

FilterDescriptor

Fields

rootrequired
RuleNode | GroupNode

Name	Type	Description
rootrequired	RuleNode \| GroupNode	-

RuleNode

Fields

fieldrequired
string
kind · optional
string
default: "rule"
operatorrequired
string
value · optional
JSON value | null
values · optional
array<JSON value> | null

Name	Type	Description
fieldrequired	string	-
kind	string	default: "rule"
operatorrequired	string	-
value	JSON value \| null	-
values	array<JSON value> \| null	-

GroupNode

Fields

childrenrequired
array<RuleNode | GroupNode>
kind · optional
string
default: "group"
logicrequired
GroupLogic
enum: ["and","or","not"]

Name	Type	Description
childrenrequired	array<RuleNode \| GroupNode>	-
kind	string	default: "group"
logicrequired	GroupLogic	enum: ["and","or","not"]

GroupLogic

SortSpecModel

Fields

day_end · optional
string | null
day_start · optional
string | null
direction · optional
SortDirection
default: "asc"; enum: ["asc","desc"]
fieldrequired
string

Name	Type	Description
day_end	string \| null	-
day_start	string \| null	-
direction	SortDirection	default: "asc"; enum: ["asc","desc"]
fieldrequired	string	-

SortDirection

Errors

Status	Meaning
400	Provide selection or leadIds; invalid selection or actor.
401	Missing or invalid user session.
403	Developer API keys are not supported on this route.
409	Idempotency key was reused with different input, or the sequence must be ACTIVE.

Example

bash

curl -X POST "https://app.autotouch.ai/api/sequences/67c4a4f7b4dd8f2d4999f014/audience/enroll" \
  -H "Authorization: Bearer <user_session_token>" \
  -H "Content-Type: application/json" \
  -d '{"leadIds":["67c4b113b4dd8f2d4999f0f1"],"scope":"org"}'

Request body

json

{
  "selection": { "mode": "descriptor", "descriptor": { "root": { "kind": "rule", "field": "lead_status", "operator": "eq", "value": "qualified" } } },
  "scope": "org",
  "skipActiveSequenceConflicts": true,
  "idempotencyKey": "qualified-audience-20260927"
}

Response example

json

{
  "success": true,
  "status": "queued",
  "task_id": "bulk_20260927_5fd85a73",
  "message": "Enrollment queued",
  "taskScopes": [{"sequenceId": "67c4a4f7b4dd8f2d4999f014"}],
  "operation_run_id": "run_123",
  "operationRunId": "run_123",
  "matched_count": 10,
  "requested": 12,
  "eligible": 10,
  "skipped": { "already_enrolled": 0, "duplicate_input": 0, "invalid_lead": 0, "blacklisted": 0, "account_status": 0, "active_sequence_conflict": 2 }
}