Enroll Contact List Members
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.
Requires the sequences:write scope on the API key.
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
}Authorizations
Bearer API key issued from Settings → Developers.
Path Parameters
ID of the contact list.
Body
Enroll Contact List Members payload
Sequence template to enroll the contacts into.
Contacts to enroll. Any id that is not a contact of this workspace is skipped.
1What to do with contacts already enrolled or recently contacted.
SKIP, ADD_IF_ALL_COMPLETED, ADD_ANYWAY, REPLACE How many days to wait before a contact can be enrolled again. Omit to use the workspace default.
x >= 0Response
Successful Response
Contacts enrolled.
Contacts left alone, because the id is unknown here or the conflict strategy said to skip them.
Contacts whose existing sequence was replaced.
Contacts that were enrolled.
Sequence runs started by this call.
The background run that checks each contact's eligibility (email verification included) and enrolls it.
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.
Was this page helpful?
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
}