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

# Sequences API — Enroll, Monitor, and Control Outreach Runs

> Enroll contacts into sequence templates, filter runs by contact, pause, resume, stop, and update per-run variables.

A **sequence** is a live outreach run for a single contact enrolled in a sequence template. It executes each configured step — emails, LinkedIn messages, manual tasks — according to the template's schedule and tracks the contact's current position and state.

<Note>
  Read endpoints require `sequences:read`. Enrolling, updating variables, pausing, resuming, and stopping require `sequences:write`.
</Note>

## Enroll a contact

The most direct path is `POST /v1/sequences` with the contact and template you want:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.topo.io/v1/sequences \
  -H "Authorization: Bearer topo_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "01954b2e-1111-7000-bbbb-222222222222",
    "sequence_template_id": "01954b2e-3333-7000-dddd-444444444444"
  }'
```

The template must be `ACTIVE` with at least one step. Topo rejects duplicate enrollments (same contact already running that template) and contacts on an exclusion list. The response is `201` with the new sequence resource.

### Enroll via contact lists

Alternatively, attach a `default_sequence_template_id` to a [contact list](/api-reference/contact-lists) and add entries:

1. **Known contact** — `POST /v1/contact-entries` returns `contact_id` immediately; enrollment starts in the same request when the list has an active default template.
2. **New person** — `contact_id` is `null` until lead-import finishes; enrollment runs after resolution when a default template is set.

Verify enrollment with `GET /v1/sequences?contact_id=<uuid>` — filter by the contact you enrolled.

## List and inspect sequences

`GET /v1/sequences` supports filters including `contact_id`, `sequence_template_id`, `status`, and `created_at_before` / `created_at_after`. `GET /v1/sequences/{sequence_id}` returns a single run.

`PATCH /v1/sequences/{sequence_id}` merges per-run `variables` into the sequence.

Action endpoints:

* `POST /v1/sequences/{sequence_id}/pause` — optional `paused_until` body
* `POST /v1/sequences/{sequence_id}/resume`
* `POST /v1/sequences/{sequence_id}/stop` — `reason` (`WIN` or `LOSE`) and `scope` (`CONTACT` stops this run only, `ACCOUNT` also stops sequences for other contacts of the same account)

## Sequence statuses

| Status             | Description                                                                              |
| ------------------ | ---------------------------------------------------------------------------------------- |
| `ACTIVE`           | The sequence is running and steps will execute on schedule.                              |
| `WAITING_FOR_LEAD` | Your team sent a message and the sequence waits for the contact to reply.                |
| `WAITING_FOR_USER` | Blocked on a user action — a pending manual task or a pause until `paused_until`.        |
| `SUCCEEDED`        | Ended on a positive outcome (interest, or stopped with `reason=WIN`).                    |
| `FAILED`           | Ended negatively (bounce, unsubscribe, or stopped with `reason=LOSE`).                   |
| `STOPPED_EARLY`    | Ended before completion (template stopped, sender removed, or removed from source list). |
| `COMPLETED`        | All steps executed without a positive reply.                                             |
| `FOUND`            | Intermediate state during lead processing before full activation.                        |
| `REFUSED`          | Contact rejected at enrollment; the sequence never started.                              |

<Tip>
  Terminal states (`SUCCEEDED`, `COMPLETED`, `FAILED`, `STOPPED_EARLY`) cannot be resumed.
</Tip>