contacts

Enroll Contact List Members

Changed on

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.

post/v1/contact-lists/{contact_list_id}/enroll

Request

  • Base URL: https://api.topo.io
  • URL: https://api.topo.io/v1/contact-lists/{contact_list_id}/enroll
  • Auth: HTTP bearer

Path parameters

contact_list_idstring uuid required

ID of the contact list.

Request body

sequence_template_idstring uuid required

Sequence template to enroll the contacts into.

contact_idsstring[] required

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

conflict_strategy'SKIP' | 'ADD_IF_ALL_COMPLETED' | 'ADD_ANYWAY' | 'REPLACE'
reenroll_cooldown_daysinteger nullable

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

Response

Successful Response

enrolled_countinteger required

Contacts enrolled.

skipped_countinteger required

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

replaced_countinteger required

Contacts whose existing sequence was replaced.

enrolled_contact_idsstring[] required

Contacts that were enrolled.

created_sequence_idsstring[] required

Sequence runs started by this call.

enrollment_run_idstring uuid nullable

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

queued_countinteger

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.

Changes