Enroll Contact

Enroll a contact into a sequence template, starting a sequence run.

The template must be ACTIVE and have at least one step; the sequence is instantiated from the template’s steps and scheduled exactly like an enrollment made from the app, including task-owner assignment.

A contact already running this template is rejected rather than enrolled twice, and so is a contact (or its company) on an exclusion list.

A contact with an active sequence from a different template is also rejected: stop that sequence first (POST /v1/sequences/{id}/stop) to avoid two sequences messaging the same person at once. Templates the contact only has completed or stopped sequences for do not block enrollment.

Before the sequence starts, the contact’s eligibility is checked, email verification included. When that finishes within about 20 seconds the response is 201 with the sequence, or 422 when the contact cannot be enrolled (no email nor LinkedIn URL, excluded, or missing a channel the template needs: no email or LinkedIn URL for its steps, or a bounced email, when the template stops on missing data or has no other channel left). Otherwise the response is 202 with the enrollment run: the contact is enrolled in the background, and GET /v1/sequences?contact_id= shows its sequence once it starts.

Requires the sequences:write scope on the API key.

POST

sequences

Enroll Contact

curl --request POST \
  --url https://api.topo.io/v1/sequences \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sequence_template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    contact_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    sequence_template_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  })
};

fetch('https://api.topo.io/v1/sequences', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.topo.io/v1/sequences"

payload = {
    "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "sequence_template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sequence_template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "ACTIVE",
  "variables": {},
  "source_contact_list_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "last_step_executed_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "contact": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "<string>",
    "linkedin_url": "<string>",
    "job_title": "<string>",
    "company_name": "<string>",
    "company_domain": "<string>"
  },
  "sequence_template": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>"
  }
}

{
  "enrollment_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sequence_template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Authorizations

Authorization

string

header

required

Bearer API key issued from Settings → Developers.

Body

application/json

Enroll Contact payload

contact_id

string<uuid>

required

Contact to enroll.

sequence_template_id

string<uuid>

required

Active template to instantiate the sequence from.

Response

Successful Response

string<uuid>

required

Unique identifier.

organization_id

string<uuid>

required

Workspace this sequence belongs to.

contact_id

string<uuid> | null

required

Contact this sequence is targeting.

sequence_template_id

string<uuid>

required

Template the sequence was instantiated from.

status

enum<string>

required

Current execution state.

Available options:

ACTIVE,

SUCCEEDED,

FAILED,

COMPLETED,

WAITING_FOR_LEAD,

WAITING_FOR_USER,

STOPPED_EARLY,

FOUND,

REFUSED

variables

Variables · object | null

required

Per-run template variables substituted into outbound messages.

Hide child attributes

variables.{key}

string | null

source_contact_list_id

string<uuid> | null

required

Contact list that triggered this sequence, if any.

last_step_executed_at

string<date-time> | null

required

When the most recent step ran.

created_at

string<date-time>

required

When the sequence was created.

updated_at

string<date-time>

required

When the sequence last changed.

contact

PublicContactSummary · object | null

Summary of the contact this sequence is targeting.

Hide child attributes

contact.id

string<uuid>

required

Unique identifier of the contact.

contact.first_name

string | null

First name.

contact.last_name

string | null

Last name.

contact.email

string | null

Email.

contact.linkedin_url

string | null

LinkedIn profile URL.

contact.job_title

string | null

Job title.

contact.company_name

string | null

Employer name.

contact.company_domain

string | null

Employer's primary domain.

sequence_template

PublicSequenceTemplateSummary · object | null

Summary of the template this sequence was instantiated from.

Hide child attributes

sequence_template.id

string<uuid>

required

Unique identifier of the sequence template.

sequence_template.name

string

required

Template name.

Enroll Contact

curl --request POST \
  --url https://api.topo.io/v1/sequences \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sequence_template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    contact_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    sequence_template_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  })
};

fetch('https://api.topo.io/v1/sequences', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.topo.io/v1/sequences"

payload = {
    "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "sequence_template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sequence_template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "ACTIVE",
  "variables": {},
  "source_contact_list_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "last_step_executed_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "contact": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "<string>",
    "linkedin_url": "<string>",
    "job_title": "<string>",
    "company_name": "<string>",
    "company_domain": "<string>"
  },
  "sequence_template": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>"
  }
}

{
  "enrollment_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sequence_template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Overview

MCP

Users

Search

Contacts

Accounts

Sequences & Tasks

Events & Webhooks

Signals

Enroll Contact

Authorizations

Body

Response