Skip to main content
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:
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. Before the sequence starts, Topo checks the contact’s eligibility, including an email verification when the address was never verified:
  • 201 — the check finished within about 20 seconds and the response is the new sequence resource.
  • 422 — the contact cannot be enrolled: it has neither an email nor a LinkedIn URL, it is excluded, or it lacks a channel the template needs (no email, a bounced email, or no LinkedIn URL for LinkedIn steps) while the template stops on missing data or has no other channel left.
  • 202 — the check is still running. The body carries enrollment_run_id, contact_id and sequence_template_id. Topo enrolls the contact in the background; poll GET /v1/sequences?contact_id=<uuid> to see its sequence once it starts.

​
Enroll via contact lists

Alternatively, attach a default_sequence_template_id to a contact list and add entries:
  1. Known contact — POST /v1/contact-entries returns contact_id immediately; enrollment is queued in the same request when the list has an active default template, and the contact enters its sequence once its eligibility is checked.
  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

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