Enroll Contact List Members - Topo

POST

/

v1

/

contact-lists

/

{contact_list_id}

/

enroll

Enroll Contact List Members

curl --request POST \
  --url https://api.topo.io/v1/contact-lists/{contact_list_id}/enroll \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sequence_template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "contact_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "conflict_strategy": "SKIP",
  "reenroll_cooldown_days": 1
}
'

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

fetch('https://api.topo.io/v1/contact-lists/{contact_list_id}/enroll', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.topo.io/v1/contact-lists/{contact_list_id}/enroll"

payload = {
    "sequence_template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "contact_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "conflict_strategy": "SKIP",
    "reenroll_cooldown_days": 1
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "enrolled_count": 123,
  "skipped_count": 123,
  "replaced_count": 123,
  "enrolled_contact_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "created_sequence_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "enrollment_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "queued_count": 0
}

Enroll many contacts of a list into a sequence template in one call. Unlike POST /v1/sequences, which enrolls a single contact and fails on any conflict, this reports per-outcome counts and applies conflict_strategy to contacts already enrolled or recently contacted, so a large enrollment does not stop at the first one that cannot start. Each contact’s eligibility is checked before it is enrolled, including an email verification when its address was never verified. When the checks take longer than about 20 seconds, the response returns what is known so far: queued_count contacts are still being checked and are enrolled in the background by the run enrollment_run_id. Follow them with GET /v1/sequences?contact_id=<uuid>. Requires the sequences:write scope on the API key.

Authorizations

Authorization

string

header

required

Bearer API key issued from Settings → Developers.

Path Parameters

contact_list_id

string<uuid>

required

ID of the contact list.

Body

application/json

Enroll Contact List Members payload

sequence_template_id

string<uuid>

required

Sequence template to enroll the contacts into.

contact_ids

string<uuid>[]

required

Contacts to enroll. Any id that is not a contact of this workspace is skipped.

Minimum array length: 1

conflict_strategy

enum<string>

default:SKIP

What to do with contacts already enrolled or recently contacted.

Available options:

SKIP,

ADD_IF_ALL_COMPLETED,

ADD_ANYWAY,

REPLACE

reenroll_cooldown_days

integer | null

How many days to wait before a contact can be enrolled again. Omit to use the workspace default.

Required range: x >= 0

Response

200 - application/json

Successful Response

enrolled_count

integer

required

Contacts enrolled.

skipped_count

integer

required

Contacts left alone, because the id is unknown here or the conflict strategy said to skip them.

replaced_count

integer

required

Contacts whose existing sequence was replaced.

enrolled_contact_ids

string<uuid>[]

required

Contacts that were enrolled.

created_sequence_ids

string<uuid>[]

required

Sequence runs started by this call.

enrollment_run_id

string<uuid> | null

The background run that checks each contact's eligibility (email verification included) and enrolls it.

queued_count

integer

default:0

Contacts still being checked when the call returned. They are enrolled in the background; list their sequences with GET /v1/sequences?contact_id= to follow them.

Enroll Contact List Members

curl --request POST \
  --url https://api.topo.io/v1/contact-lists/{contact_list_id}/enroll \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sequence_template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "contact_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "conflict_strategy": "SKIP",
  "reenroll_cooldown_days": 1
}
'

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

fetch('https://api.topo.io/v1/contact-lists/{contact_list_id}/enroll', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.topo.io/v1/contact-lists/{contact_list_id}/enroll"

payload = {
    "sequence_template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "contact_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "conflict_strategy": "SKIP",
    "reenroll_cooldown_days": 1
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "enrolled_count": 123,
  "skipped_count": 123,
  "replaced_count": 123,
  "enrolled_contact_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "created_sequence_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "enrollment_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "queued_count": 0
}