Sequences API — Enroll, Monitor, and Control Outreach Runs

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.

Read endpoints require sequences:read. Enrolling, updating variables, pausing, resuming, and stopping require sequences:write.

Enroll a contact

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

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 and add entries:

Known contact — POST /v1/contact-entries returns contact_id immediately; enrollment starts in the same request when the list has an active default template.
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.

Terminal states (SUCCEEDED, COMPLETED, FAILED, STOPPED_EARLY) cannot be resumed.

Overview

Users

Contacts

Accounts

Sequences & Tasks

Events & Webhooks

Sequences API — Enroll, Monitor, and Control Outreach Runs

Enroll a contact

Enroll via contact lists

List and inspect sequences

Sequence statuses

​Enroll a contact

​Enroll via contact lists

​List and inspect sequences

​Sequence statuses

Enroll a contact

Enroll via contact lists

List and inspect sequences

Sequence statuses