> ## Documentation Index
> Fetch the complete documentation index at: https://developers.flowestate.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Sequences

> Create, configure, and run cold-outreach sequences. Preview the audience, then launch, pause, and resume.

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.

> [!NOTE]
>
> **`call` and `whatsapp` are dispatchable channels.** A `whatsapp` sequence is a multi-step **drip**: a sequence-level [`channelConfig`](#channelconfig-whatsapp-required) names the sending account, and an ordered list of [`steps`](#steps-whatsapp-required) carries the per-step message content and delays. [`SequenceChannel`](https://developers.flowestate.app/enums#sequencechannel) also defines `email`, but that channel is still deferred.

## Lifecycle

A sequence moves through a fixed set of [`SequenceStatus`](https://developers.flowestate.app/enums#sequencestatus) states:

```
draft  →  running  ⇄  paused  →  completed
```

* **`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`:

| Action | Allowed from | Notes |
| - | - | - |
| `PATCH` (edit) | `draft` only | Once launched, the configuration is frozen. |
| `DELETE` | `draft` only | Launched sequences keep their contact history and cannot be deleted. |
| `launch` | `draft` only | Requires a non-empty audience of at most **5000** eligible leads. |
| `pause` | `running` only | |
| `resume` | `paused` only | |

***

## List sequences

```http theme={null}
GET /sequences
```

**Scope:** `sequences:read`. Returns every sequence for the organization, newest first. This endpoint is **not paginated** — it returns a flat `data` array.

> [!NOTE]
>
> A [personal credential](https://developers.flowestate.app/member-access.md) 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

| Param | Type | Notes |
| - | - | - |
| `status` | enum | Optional. Filter by [`SequenceStatus`](https://developers.flowestate.app/enums#sequencestatus): `draft`, `running`, `paused`, or `completed`. An invalid value returns `400 VALIDATION_ERROR`. |

### Response 200

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

```json theme={null}
{
  "data": [
    {
      "id": "seq_...",
      "organizationId": "org_...",
      "name": "Q3 cold callbacks",
      "channel": "call",
      "status": "running",
      "criteria": {
        "statuses": ["new", "contacted"],
        "stageIds": ["b1f2...-uuid"],
        "sources": ["meta", "website"],
        "minScore": 40
      },
      "channelConfig": {},
      "throttle": {
        "maxPerMinute": 5,
        "businessHoursStart": "09:00",
        "businessHoursEnd": "18:00",
        "timezone": "America/Santo_Domingo",
        "weekdays": [1, 2, 3, 4, 5]
      },
      "createdBy": null,
      "createdAt": "2026-06-20T14:00:00.000Z",
      "updatedAt": "2026-06-21T09:30:00.000Z",
      "startedAt": "2026-06-21T09:30:00.000Z",
      "completedAt": null,
      "progress": {
        "total": 320,
        "pending": 210,
        "inProgress": 4,
        "sent": 100,
        "failed": 5,
        "skipped": 1
      }
    }
  ]
}
```

### The `progress` object

Counts of contacts by [`SequenceContactStatus`](https://developers.flowestate.app/enums#sequencecontactstatus). `total` is the sum of the rest.

| Field | Description |
| - | - |
| `total` | Total contacts enrolled in the sequence. |
| `pending` | Queued, not yet attempted. |
| `inProgress` | Currently being dispatched (`in_progress`). |
| `sent` | Successfully dispatched. |
| `failed` | Dispatch failed after retries. |
| `skipped` | Skipped (e.g. lead opted out or became ineligible). |
| `stopped` | **WhatsApp drips only.** Drip halted mid-flow — the lead replied, opted out, or reached a won/lost stage. |

***

## Create a sequence

```http theme={null}
POST /sequences
```

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

### Request body

```json theme={null}
{
  "name": "Q3 cold callbacks",
  "channel": "call",
  "criteria": {
    "statuses": ["new", "contacted"],
    "stageIds": ["b1f2...-uuid"],
    "sources": ["meta", "website"],
    "minScore": 40
  },
  "throttle": {
    "maxPerMinute": 5,
    "businessHoursStart": "09:00",
    "businessHoursEnd": "18:00",
    "timezone": "America/Santo_Domingo",
    "weekdays": [1, 2, 3, 4, 5]
  }
}
```

| Field | Required | Notes |
| - | - | - |
| `name` | yes | 1..120 chars (trimmed). |
| `channel` | no | One of [`SequenceChannel`](https://developers.flowestate.app/enums#sequencechannel): `call` or `whatsapp`. Defaults to `call`. |
| `channelConfig` | conditional | **Required when `channel` is `whatsapp`.** Names the sending account only — see [below](#channelconfig-whatsapp-required). Ignored for `call`. |
| `steps` | conditional | **Required when `channel` is `whatsapp`** (1–10 ordered drip steps). The per-step message content and delays — see [below](#steps-whatsapp-required). Omit for `call`. |
| `criteria` | yes | Audience filter. See below. |
| `throttle` | yes | Pacing rules. See below. |

#### `criteria` — audience filter

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

| Field | Type | Notes |
| - | - | - |
| `statuses` | string\[] | Match leads whose status is one of these [`LeadStatus`](https://developers.flowestate.app/enums#leadstatus) values. |
| `stageIds` | string\[] (uuid) | Match leads in any of these pipeline stages. Discover stage IDs via [`GET /pipeline/stages`](https://developers.flowestate.app/api-reference/pipeline). |
| `sources` | string\[] | Match leads whose source is one of these [`LeadSource`](https://developers.flowestate.app/enums#leadsource) values. |
| `minScore` | integer (0–100) | Match leads with `score >= minScore`. |
| `leadIds` | string\[] (uuid) | Optional, max **5000**. Restrict the audience to these explicit leads. Works for any channel — pass a single id to build a one-recipient sequence. Combines with the other filters via AND. |

#### `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)).

| Field | Type | Notes |
| - | - | - |
| `whatsappAccountId` | string (uuid) | **Required.** The connected account that sends **every** step. Obtain it from [`GET /whatsapp/accounts`](https://developers.flowestate.app/api-reference/whatsapp#list-whatsapp-accounts) — can be a member account or the org-global account. |

#### `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.

| Field | Type | Notes |
| - | - | - |
| `channelConfig` | object | **Required.** The message content for this step. See the per-step content fields below. |
| `delayValue` | integer (0–365) | **Required.** Delay before this step fires, **relative to the previous step's send**. Step 0 is relative to launch/enrolment, so `delayValue: 0` sends it immediately. |
| `delayUnit` | enum | One of [`SequenceStepDelayUnit`](https://developers.flowestate.app/enums#sequencestepdelayunit): `minutes`, `hours`, `days`. Defaults to `days`. |
| `jitterMinutes` | integer (0–1440) | Optional. A uniform random ± window added to the delay, to look human and spread load. |
| `targetStageId` | string (uuid) | Optional. Move the lead to this pipeline stage when the step fires — which can trigger that stage's automations. Discover stage IDs via [`GET /pipeline/stages`](https://developers.flowestate.app/api-reference/pipeline). |

Each step's `channelConfig` (the message content):

| Field | Type | Notes |
| - | - | - |
| `message` | string | **Required**, 1..4096 chars. Supports variables: `{{firstName}}`, `{{lastName}}`, `{{fullName}}`, and any lead custom-field key as `{{fieldName}}`. Unknown variables render empty. |
| `messageVariants` | string\[] | Optional, max **10**. Alternate message bodies; one is chosen deterministically per contact to reduce spam fingerprinting. |
| `media` | object | Optional. `{ url (https string), type, mimetype? (string), fileName? (string) }`, where `type` is one of [`WhatsappMediaType`](https://developers.flowestate.app/enums#whatsappmediatype): `image`, `video`, `document`. When present, `message` is used as the media caption. |
| `optOutFooter` | boolean | Optional, default `true`. Appends a compliance opt-out footer to the message. |
| `optOutFooterText` | string | Optional, max 280 chars. Overrides the default footer text. |

> [!NOTE]
>
> 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.

| Field | Type | Notes |
| - | - | - |
| `maxPerMinute` | integer (1–60) | Max contacts dispatched per minute. |
| `businessHoursStart` | string `"HH:MM"` | Start of the daily dispatch window, in `timezone` local time. |
| `businessHoursEnd` | string `"HH:MM"` | End of the daily dispatch window. |
| `timezone` | string | IANA timezone (e.g. `America/Santo_Domingo`), 1..64 chars. |
| `weekdays` | integer\[] | ISO weekdays the sequence may dispatch on (Mon=1 … Sun=7). At least one, at most seven. |

### 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:

```bash theme={null}
curl -X POST https://panel.flowestate.app/api/v1/sequences \
  -H "Authorization: Bearer fe_k_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 WhatsApp follow-ups",
    "channel": "whatsapp",
    "criteria": {
      "statuses": ["new", "contacted"],
      "leadIds": ["b1f2...-uuid"]
    },
    "channelConfig": {
      "whatsappAccountId": "a3c9...-uuid"
    },
    "steps": [
      {
        "delayValue": 0,
        "delayUnit": "days",
        "channelConfig": {
          "message": "Hi {{firstName}}, here is the brochure you asked about.",
          "messageVariants": [
            "Hello {{firstName}}, sharing the brochure you requested.",
            "Hi {{fullName}}, attaching the brochure for you."
          ],
          "media": {
            "url": "https://cdn.example.com/brochure.pdf",
            "type": "document",
            "mimetype": "application/pdf",
            "fileName": "brochure.pdf"
          },
          "optOutFooter": true
        }
      },
      {
        "delayValue": 2,
        "delayUnit": "days",
        "jitterMinutes": 120,
        "channelConfig": {
          "message": "Hi {{firstName}}, did you get a chance to look at the brochure?"
        }
      },
      {
        "delayValue": 3,
        "delayUnit": "days",
        "targetStageId": "c4d5...-uuid",
        "channelConfig": {
          "message": "Hi {{firstName}}, happy to set up a quick call whenever works for you."
        }
      }
    ],
    "throttle": {
      "maxPerMinute": 5,
      "businessHoursStart": "09:00",
      "businessHoursEnd": "18:00",
      "timezone": "America/Santo_Domingo",
      "weekdays": [1, 2, 3, 4, 5]
    }
  }'
```

### Response 201

```json theme={null}
{ "id": "seq_..." }
```

### 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

```http theme={null}
GET /sequences/{sequenceId}
```

**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:

```json theme={null}
{
  "id": "seq_...",
  "channel": "whatsapp",
  "channelConfig": {
    "whatsappAccountId": "a3c9...-uuid"
  },
  "steps": [
    {
      "stepOrder": 0,
      "delayValue": 0,
      "delayUnit": "days",
      "channelConfig": {
        "message": "Hi {{firstName}}, here is the brochure you asked about."
      }
    },
    {
      "stepOrder": 1,
      "delayValue": 2,
      "delayUnit": "days",
      "jitterMinutes": 120,
      "channelConfig": {
        "message": "Hi {{firstName}}, did you get a chance to look at the brochure?"
      }
    },
    {
      "stepOrder": 2,
      "delayValue": 3,
      "delayUnit": "days",
      "targetStageId": "c4d5...-uuid",
      "channelConfig": {
        "message": "Hi {{firstName}}, happy to set up a quick call whenever works for you."
      }
    }
  ],
  "progress": {
    "total": 320,
    "pending": 210,
    "inProgress": 4,
    "sent": 100,
    "failed": 5,
    "skipped": 1,
    "stopped": 12
  },
  "stepFunnel": [
    { "stepOrder": 0, "sent": 308 },
    { "stepOrder": 1, "sent": 190 },
    { "stepOrder": 2, "sent": 96 }
  ],
  "whatsappReceipts": {
    "sent": 100,
    "delivered": 92,
    "read": 64,
    "failed": 8
  }
}
```

`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:

| Field | Description |
| - | - |
| `sent` | Messages handed off to the provider. |
| `delivered` | Confirmed delivered to the recipient's device. |
| `read` | Confirmed read by the recipient. |
| `failed` | Reported failed by the provider after sending. |

***

## Update a sequence

```http theme={null}
PATCH /sequences/{sequenceId}
```

**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.

```json theme={null}
{
  "name": "Q3 cold callbacks (refined)",
  "criteria": { "statuses": ["new"], "minScore": 60 },
  "throttle": {
    "maxPerMinute": 8,
    "businessHoursStart": "10:00",
    "businessHoursEnd": "17:00",
    "timezone": "America/Santo_Domingo",
    "weekdays": [1, 2, 3, 4, 5]
  }
}
```

`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

```json theme={null}
{ "id": "seq_..." }
```

### Common errors

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

***

## Delete a sequence

```http theme={null}
DELETE /sequences/{sequenceId}
```

**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

```json theme={null}
{ "deleted": true, "id": "seq_..." }
```

### 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

```http theme={null}
POST /sequences/preview-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

```json theme={null}
{
  "criteria": {
    "statuses": ["new", "contacted"],
    "sources": ["meta"],
    "minScore": 40
  }
}
```

The `criteria` object follows the [same schema](#criteria-audience-filter) as on create.

### Response 200

```json theme={null}
{ "count": 1840 }
```

***

## Launch a sequence

```http theme={null}
POST /sequences/{sequenceId}/launch
```

**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`.

> [!WARNING]
>
> **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](https://developers.flowestate.app/rate-limits.md) for how the weighted monthly cost is accounted.

### Response 200

```json theme={null}
{ "id": "seq_...", "enqueued": 1200 }
```

`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

```http theme={null}
POST /sequences/{sequenceId}/pause
```

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

### Response 200

```json theme={null}
{ "id": "seq_..." }
```

### Common errors

* `400 BAD_REQUEST` — `"Only running sequences can be paused"`.

***

## Resume a sequence

```http theme={null}
POST /sequences/{sequenceId}/resume
```

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

### Response 200

```json theme={null}
{ "id": "seq_..." }
```

### Common errors

* `400 BAD_REQUEST` — `"Only paused sequences can be resumed"`.

***

## List sequence contacts for a lead

```http theme={null}
GET /leads/{leadId}/sequence-contacts
```

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

### Response 200

```json theme={null}
{
  "data": [
    {
      "id": "uuid",
      "sequenceId": "uuid",
      "status": "sent",
      "currentStep": 1,
      "pauseKind": null,
      "scheduledAt": "2026-07-21T04:19:15.658Z",
      "updatedAt": "2026-07-21T04:19:30.858Z"
    }
  ]
}
```

***

## Enroll a lead in a sequence

```http theme={null}
POST /leads/{leadId}/sequence-contacts
```

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

### Request body

```json theme={null}
{ "sequenceId": "uuid" }
```

### Response 201

```json theme={null}
{ "id": "uuid", "sequenceId": "uuid", "leadId": "uuid" }
```

### 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

```http theme={null}
PATCH /leads/{leadId}/sequence-contacts/{contactId}
```

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

### Request body

```json theme={null}
{ "action": "pause" }
```

`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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.