Workflow APIs: sequences + tasks

What this covers

This guide covers workflow routes that support developer API keys. Some legacy user-session routes appear in the reference and are labeled individually; the scope list below only authorizes key-supported routes.

Required scopes

sequences:read, sequences:write, sequences:run
tasks:read, tasks:write
integrations:read only when advanced routing needs explicit sender-account lookup.

Actor model (`actorUserId`)

The sequence and task mutation endpoints that expose actorUserId accept it as an optional query parameter. Check the individual endpoint contract.

JWT callers: actor defaults to authenticated user.
Developer-key callers: sequence mutations use an explicit actorUserId, or the key owner when omitted; an invalid explicit actor fails. Task actor resolution tries the explicit actor and then the key owner. Do not rely on fallback to represent a different user.
Explicit actors and developer-key owners are looked up in the same organization and must not be deleted. Task mutations also restrict user-session actor overrides according to endpoint permissions.

Common actor errors: actor_user_required, invalid_actor_user_id, invalid_api_key_owner_user; task actor overrides may return actor_override_forbidden.

Sequence authoring rules (external contract)

sourceTableId is required for create/update via developer key. This links the sequence to a research table — the same table where add_to_sequence columns will run.
Sequence must contain at least one step.
First email step cannot be configured as reply.
Bulk and personal delivery both support manual email review tasks; automated bulk sends still require provider readiness.
Treat automated sending and AI drafting as separate choices: manual AI-draft review uses executionMode=MANUAL and aiDraft=true; template-based automation uses fixed templates with executionMode=AUTOMATED.
Automated AI-drafted steps require aiAutomationTrusted=true on the step (the legacy sequence-level flag is also accepted). Leave non-empty subjectTemplate, bodyTemplate, and scriptTemplate out of AI-draft steps; combining them with aiDraft=true is rejected.
Every authored sequence with actions requires flowGraph, including straight-line designs. Set version=1, exactly one starting node in entryNodeIds, and explicit routing edges. Action nodes reference sourceStepId or inline stepConfig; steps is an action content catalog whose array order does not route execution.
defaultAppendSignature (optional) sets sequence-level default signature behavior for email steps.
steps[].appendSignature (optional) overrides signature behavior per email step.
When signature append is enabled for a step, the saved user signature is appended deterministically at send time.

Creation and activation are separate requests

POST /api/sequences persists DRAFT and returns {id, success}. Bind that exact id before separately setting status to ACTIVE. Activation requires sequences:run and its sender, approval, and readiness checks. The create request does not enroll leads or send; publishing a definition does not activate a DRAFT.

Command Center's completed new-sequence creation flow normally continues from this saved draft to the separate activation boundary unless the user explicitly requests draft-only or inactive creation. Existing draft edits, autosaves, and clones do not inherit that completion default. An activation failure leaves the saved sequence intact; report its actual status and blocker, and claim ACTIVE only after activation evidence. Audience enrollment remains a separate authorized action.

Manual AI-draft review step types

CALL
CUSTOM
LINKEDIN_CONNECT, LINKEDIN_MESSAGE, LINKEDIN_CHAT_MESSAGE, LINKEDIN_VOICE_MESSAGE
EMAIL only when emailSendMode=MANUAL

LINKEDIN_VISIT_PROFILE is always automated and notifies the lead; it is not a manual AI-draft review step. WAIT steps cannot use aiDraft.

LinkedIn connection branches

For LinkedIn connect plus fallback flows, create the connect action in steps[], then add a graph condition attached to that connect node:

metadata.decisionType=outcome_wait
metadata.listenFor=linkedin_connection_accepted
metadata.waitMode=up_to with metadata.waitDays

The connected branch can route to connected-only actions such as LINKEDIN_CHAT_MESSAGE or LINKEDIN_VOICE_MESSAGE. Use LINKEDIN_MESSAGE for best-available LinkedIn delivery on paths that may not be connected. The not-connected branch should route to actions that do not require a first-degree connection, such as a manual email fallback.

Delivery/readiness nuances

Personal delivery requires inbox readiness for the resolved actor.
Accepted sequence enrollment work returns canonical operation IDs for operation-run progress; developer keys need jobs:read for this read. Native task_id reads remain available for bulk-job diagnostics. A status=noop response has no task or operation identity when no idempotency key was supplied; an idempotent no-op returns a saved terminal receipt with those IDs. Inspect skip reasons and poll only returned identities. Admission does not prove enrollment or message delivery.
Normal enrollment requires the target sequence to be ACTIVE. reviewOnly=true stages paused enrollment records and skips sending side effects; it also permits DRAFT or PAUSED sequences. This writes enrollment records. Use audience preview for a read-only check.
Most enrollments should set assignedToUserId and omit sender routing. Autotouch uses that assignee's default connected email and LinkedIn sender accounts.
Use senderAccountIds, assignmentPlan, and routingMode only for explicit sender pinning or team round-robin routing. Use GET /api/sender-accounts to discover those IDs.
Set skipActiveSequenceConflicts=true for automated/table-driven handoffs unless the user explicitly wants parallel sequence enrollment.
Use POST /api/sequences/{sequence_id}/audience/enroll when the server should resolve an explicit or descriptor-based audience; this route requires an authenticated user session. Developer API keys can use the separate exact-ID enrollment route with its documented scope.
GET /api/sequences/{sequence_id}/audience, enrollment updates, direct LinkedIn message sending, task LinkedIn send-and-complete, and requester company context currently require a user session. The read-only direct LinkedIn status/search/post routes separately support linkedin:read. Developer API keys are blocked on the listed session-only routes.

Research context and favorite fields

POST /api/sequences/{sequence_id}/enroll accepts optional researchContext.

sourceTableId links enrollments to a live research source table.
fieldIds (optional) sets explicit selected research field IDs for context.
If fieldIds is omitted, draft/audience context falls back to starred (favorite) research columns.
Table-driven add-to-sequence runs auto-attach source table context only; favorites are resolved via starred fallback unless explicit fieldIds are provided.

Why this matters:

Calling workflows depend on fast context retrieval in sidecar views, so starred fields should represent the highest-signal call context.
AI-generated emails/copy rely on this context set for grounding, so list imports should carry both intent signals and full source context.

Over the API, mark those columns as favorites by setting isImportant: true on column create/update.

Requester context and draft readiness

AI draft quality also depends on requester context. Use GET /api/llm/company-context before draft-heavy workflows when you need to verify the effective org/personal context and whether draft quality will be degraded.

variables returns the resolved requester/company-context variables available to runtime prompts.
draft_readiness summarizes whether primary requester fields such as user_value_proposition and buyer_persona are missing, plus whether research context is explicit or relying on starred fallback.
Sequence/task AI draft behavior uses the same context contract exposed in GET /api/capabilities under execution_policies.workflows.tasks.ai_draft.context_contract.

CLI coverage note

Installable autotouch commands cover the main public research-table, lead, sequence, task, and workflow helper surfaces. Raw HTTP remains the canonical contract documented here.