---
title: "Enroll Contact List Members"
method: POST
path: "/v1/contact-lists/{contact_list_id}/enroll"
tags: ["contacts"]
---

# Enroll Contact List Members

`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

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.

## Path parameters

- `contact_list_id` string, uuid, required

## Request body

- EnrollContactListPublicInput
  - `sequence_template_id` string, uuid, required: Sequence template to enroll the contacts into.
  - `contact_ids` string[], 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_days` integer, nullable: How many days to wait before a contact can be enrolled again. Omit to use the workspace default.

## Response `200`

Successful Response

- EnrollContactListPublicOutput
  - `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[], required: Contacts that were enrolled.
  - `created_sequence_ids` string[], required: Sequence runs started by this call.
  - `enrollment_run_id` string, uuid, nullable: The background run that checks each contact's eligibility (email verification included) and enrolls it.
  - `queued_count` integer: 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

- **2026-09-26** `889b0290212f`: 2 info
  - added the optional property `enrollment_run_id` to the response with the `200` status
  - added the optional property `queued_count` to the response with the `200` status
- **2026-08-18** `ad6ac1d13526`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/topo/apis/topo-public-api/changes/v1/contact-lists/:contact_list_id/enroll/post.md)

---

[API](https://skmtc.dev/topo/apis/topo-public-api.md) · [All operations](https://skmtc.dev/topo/apis/topo-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/topo/apis/topo-public-api/revisions/62914910b2a8?raw)