Enroll sequence leads

Async contract

This endpoint queues enrollment work and returns immediately when eligible leads exist. Poll GET /api/operation-runs/{operation_run_id} with the returned operationRunId or operation_run_id for canonical progress; developer keys need the additional jobs:read scope. The returned task_id identifies the native bulk job, whose status read is available for executor diagnostics. Admission does not prove completed enrollment or message delivery.

If preflight finds no eligible leads, the response is a successful 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 its task and canonical operation IDs for replay. Inspect skip reasons; poll only identities actually returned.

idempotencyKey makes a retry safe only when the enrollment input is unchanged. tableAudience is optional proof; when supplied, the backend validates its table, lead column, and fingerprint before admitting enrollment.

Native Command Center enrollment remains sensitive under Approve for me, including manual-only or reviewOnly enrollment. Activating a sequence automatically in that mode does not approve adding Leads. Combined launch-and-enroll actions also require approval. HTTP and CLI enrollment keep their existing explicit authenticated invocation and scope requirements.

Activation contract

• Real enrollment requires the target sequence to already be ACTIVE.
• reviewOnly=true stages paused enrollment records and skips sending side effects. It is a mutation, not a read-only preview, and also permits DRAFT or PAUSED sequences. Use the audience preview for read-only eligibility checks.
• Table-driven add_to_sequence columns use the same activation and eligibility checks as direct enroll. The sequence's sourceTableId must match the table the column belongs to.

Assignee and sender routing

Find teammate IDs with GET /api/org/users (users:read). Find mailbox and LinkedIn account IDs with GET /api/sender-accounts (integrations:read). Copy exact returned IDs; never use current_user, a display name or email as an ID.

If assignedToUserId and assignmentPlan are omitted, ownership defaults to the resolved requesting actor. A developer-key request uses its owner as the default actor. With one assignee and no team plan, routing is single; round-robin requires an explicit team assignment plan. Existing sender selections can be pinned; inspect account defaults and access before overriding them.

• Most enrollments only need assignedToUserId. When senderAccountIds and assignmentPlan are omitted, Autotouch uses that assignee's default connected email and LinkedIn sender accounts.
• Use senderAccountIds only when one enrollment must be pinned to a specific email or LinkedIn sender account.
• Use assignmentPlan plus routingMode=round_robin or weighted_round_robin when distributing leads across multiple owners or sender accounts.
• Owners/admins manage defaults and delegation through /api/sender-accounts; ordinary "assign these leads to me" enrollments do not need sender-account management.

Lead-ID prerequisite

leadIds must contain existing CRM Lead IDs, not teammate IDs or a table's boolean In Leads flag. For Research Table rows without CRM identities, use Sync to Leads (the add_to_crm provider; research_table.sync_to_leads where that operation is exposed), then consume its Lead-ID result column. Preserve the requested audience; do not silently restrict it to rows already in CRM.

Conflict guard

Set skipActiveSequenceConflicts: true when the handoff should skip people already active in another sequence. This is recommended for table-driven or automated handoffs unless the user explicitly wants parallel enrollment.

Context behavior

• When researchContext.fieldIds is present, those IDs are used as the selected context set.
• When fieldIds is omitted, audience/draft context falls back to starred research columns.

Why favorites matter

• Calling workflows use favorites to surface high-signal context quickly in sidecar views.
• AI draft generation uses the selected/fallback context set, so importing both intent and full context improves output quality.

Mark a research column as a favorite by setting isImportant: true on POST /api/tables/{table_id}/columns or PATCH /api/tables/{table_id}/columns/{column_id}.