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.

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",
  "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>"
  }
}

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

201 - application/json

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",
  "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>"
  }
}

Overview

Users

Contacts

Accounts

Sequences & Tasks

Events & Webhooks

Enroll Contact

Authorizations

Body

Response