Skip to main content
Sequences are cold-outreach campaigns. You define an audience with lead criteria, a throttle that governs pacing and business hours, and then launch the sequence to enroll matching leads into a per-contact dispatch queue. Every endpoint on this page operates inside the calling organization’s tenant — you cannot read or write sequences from another organization with the same key.
call and whatsapp are dispatchable channels. A whatsapp sequence is a multi-step drip: a sequence-level channelConfig names the sending account, and an ordered list of steps carries the per-step message content and delays. SequenceChannel also defines email, but that channel is still deferred.

Lifecycle

A sequence moves through a fixed set of SequenceStatus states:
  • draft — newly created. Editable and deletable. Nothing is enqueued yet.
  • running — launched. The dispatch worker is processing the contact queue.
  • paused — temporarily halted. Resume to continue from where it left off.
  • completed — auto-set when the queue drains (every contact reached a terminal state). Terminal.
Transition rules — illegal transitions return 400 BAD_REQUEST:

List sequences

Scope: sequences:read. Returns every sequence for the organization, newest first. This endpoint is not paginated — it returns a flat data array.
A personal credential only receives running sequences as { id, name, channel, status }. Query status is ignored. channelConfig, criteria, throttle, and progress are omitted. Creating, launching, or pausing a whole sequence is not available.

Query parameters

Response 200

Each sequence carries a progress object derived from its contact queue.

The progress object

Counts of contacts by SequenceContactStatus. total is the sum of the rest.

Create a sequence

Scope: sequences:write. Creates a sequence in draft status. Nothing is enqueued until you launch it.

Request body

criteria — audience filter

All fields are optional and combine with AND. An empty object {} matches every lead in the organization.

channelConfig — WhatsApp (required)

Required when channel is whatsapp; omit it (or send {}) for call. This is the sender for the whole drip — it no longer holds the message (that moved into steps).

steps — WhatsApp (required)

A WhatsApp sequence is a drip: an ordered array of 1–10 steps. Each enrolled lead advances through the steps over time, and its position in the drip is the per-sequence follow-up status. Each step’s channelConfig carries the message content; delayValue/delayUnit schedule when it fires. Each step’s channelConfig (the message content):
WhatsApp drip messages are sent from the org’s connected WhatsApp account and thread into the inbox. The drip stops for a lead that replies (any inbound WhatsApp), opts out with a keyword (BAJA, STOP, CANCELAR, UNSUBSCRIBE), or reaches a won/lost stage — the lead is marked stopped and skips any remaining steps. Opt-outs are also excluded from future WhatsApp outreach (whatsappOptOut). Per-step sends are internal — they are not separate API requests, and launch charges the quota by enrolled leads, not by steps.

throttle — pacing and business hours

All fields are required.

Request — WhatsApp drip

A whatsapp sequence with a sender channelConfig and a 3-step steps drip: an immediate intro, a follow-up 2 days later (with ±2h jitter), and a final nudge 3 days after that which moves the lead to a pipeline stage. Here criteria.leadIds targets a single explicit lead:

Response 201

Common errors

  • 400 VALIDATION_ERROR — invalid body (e.g. empty name, unknown channel, malformed throttle, or channel: "whatsapp" without a valid channelConfig and at least one steps entry).

Get a sequence

Scope: sequences:read. Returns the same shape as a list item, including the progress object. 404 NOT_FOUND if the sequence doesn’t exist or belongs to another org. For WhatsApp drips, the response additionally carries the ordered steps, a progress.stopped count, a stepFunnel, and a whatsappReceipts object — live delivery and read receipts from the provider:
steps echoes the drip definition (each entry gains a zero-based stepOrder). stepFunnel reports how many enrolled leads received each step (cumulative — stepOrder 0 is the largest, and counts fall off as leads stop or are still waiting). whatsappReceipts aggregates across all step messages:

Update a sequence

Scope: sequences:write. Draft-only — editing a launched sequence returns 400 BAD_REQUEST.

Request body

All fields optional; send only what you want to change. channel cannot be changed.
criteria and throttle are replaced wholesale when provided — send the complete object, not a partial patch. For a WhatsApp drip, channelConfig (the sender) and steps (the full ordered drip) are likewise replaced wholesale — send the complete steps array, not a single step.

Response 200

Common errors

  • 400 BAD_REQUEST — "Only draft sequences can be edited".
  • 400 VALIDATION_ERROR — invalid body.
  • 404 NOT_FOUND — unknown sequence.

Delete a sequence

Scope: sequences:write. Draft-only. Launched sequences own their contact queue and history (who was dialed, results, provider references), so they are kept as a record and cannot be deleted.

Response 200

Common errors

  • 400 BAD_REQUEST — "Only draft sequences can be deleted; launched sequences keep their contact history".
  • 404 NOT_FOUND — unknown sequence.

Preview the audience

Scope: sequences:read. Counts how many leads currently match a set of criteria — without creating or launching anything. Use it to size an audience before committing, and to confirm it sits under the 5000-lead launch ceiling.

Request body

The criteria object follows the same schema as on create.

Response 200


Launch a sequence

Scope: sequences:write. Draft-only. Resolves the audience from the sequence’s criteria, enrolls each matching lead into the contact queue, and flips the sequence to running.
Launching charges your monthly API quota proportionally to the audience size. Unlike every other endpoint — which costs one unit — a launch consumes one unit per enqueued contact. A launch that enrolls 1,200 leads costs 1,200 units against your monthly quota. This weighting applies to all channels, including WhatsApp. Preview the audience first, and see Rate limits for how the weighted monthly cost is accounted.

Response 200

enqueued is the number of contacts enrolled (the number of units charged).

Common errors

  • 400 BAD_REQUEST — "Only draft sequences can be launched" (already running, paused, or completed).
  • 400 BAD_REQUEST — "No eligible leads match this sequence's criteria" (empty audience).
  • 400 BAD_REQUEST — "Audience too large (over 5000 eligible leads). Narrow the criteria before launching."
  • 404 NOT_FOUND — unknown sequence.

Pause a sequence

Scope: sequences:write. Running-only. Halts dispatch; in-flight contacts finish, but no new contacts are picked up.

Response 200

Common errors

  • 400 BAD_REQUEST — "Only running sequences can be paused".

Resume a sequence

Scope: sequences:write. Paused-only. Returns the sequence to running and the worker continues from the remaining pending contacts.

Response 200

Common errors

  • 400 BAD_REQUEST — "Only paused sequences can be resumed".

List sequence contacts for a lead

Scope: sequences:read. Returns enrollments for one lead. With a personal credential the lead must be in the current portfolio (404 otherwise).

Response 200


Enroll a lead in a sequence

Scope: sequences:write. Enrolls one lead in a running sequence.

Request body

Response 201

Common errors

  • 400 SEQUENCE_INACTIVE — sequence missing, not running, or unsupported channel.
  • 400 INELIGIBLE — the lead does not match the sequence audience / channel rules.
  • 409 ALREADY_ENROLLED — already in this sequence (including a previous withdraw).
  • 404 NOT_FOUND — lead missing or outside the caller’s portfolio.

Pause, resume, or withdraw a participation

Scope: sequences:write. Acts on a single enrollment, not the whole sequence.

Request body

action is one of pause, resume, withdraw.
  • pause — manual pause (pauseKind: "manual"). Progress is kept.
  • resume — clears that pause if the sequence is still running and the lead is still eligible. Keeps a future scheduledAt.
  • withdraw — sets status to stopped. The member cannot enroll that lead again.

Common errors

  • 400 NOT_PAUSED — resume without a manual pause.
  • 400 SEQUENCE_INACTIVE — sequence is not running.
  • 400 INELIGIBLE — lead no longer eligible on resume.
  • 409 WITHDRAWN — participation already ended.
  • 404 NOT_FOUND — lead or contact missing, or lead outside the portfolio.