---
title: "Enroll an audience in a sequence"
method: POST
path: "/sequences/{sequenceId}/enroll-audience"
tags: ["Sequences"]
---

# Enroll an audience in a sequence

`POST /sequences/{sequenceId}/enroll-audience`

## Request

- Base URL: `https://api.sequenzy.com/api/v1`
- URL: `https://api.sequenzy.com/api/v1/sequences/{sequenceId}/enroll-audience`
- Auth: HTTP bearer

Starts a background run that enrolls every active contact matching the audience (everyone, lists, a segment, a filter, or rules) into the sequence, in batches, with no per-request cap. Contacts already active, waiting, or paused in the sequence are skipped; one_time sequences also skip contacts who completed or were cancelled before; unsubscribed and bounced contacts are never enrolled. Only one run per sequence can be queued or running at a time. The sequence must be enabled and accepting entrants. This is how a manual-trigger countdown sequence gets its audience; late enrollees skip the steps whose key date already passed.

## Path parameters

- `sequenceId` string, required

## Request body

- object
  - `audience` SequenceAudience, required: Who to enroll. Same shape as campaign targetLists.
    - `type` 'all' | 'lists' | 'segment' | 'filtered' | 'rules', required
    - `listIds` string[]: For type lists.
    - `segmentId` string: For type segment.
    - `filters` object[]: For type filtered; subscriber filters.
    - `filterJoinOperator` 'and' | 'or'
    - `include` object[]: For type rules; include rules of type all, lists, segments, or filtered.
    - `exclude` object[]: For type rules; exclude rules.
    - `excludedSubscriberIds` string[]: Contacts removed from the include rules. Does not remove contacts listed in includedSubscriberIds.
    - `includedSubscriberIds` string[]: Specific contacts to enroll in addition to the include rules. Use type rules with an empty include array to enroll only these contacts, with no per-request cap. IDs that belong to another company, or to contacts who are unsubscribed, bounced or without an email, are skipped.
  - `targetNodeId` string, nullable: Step to start contacts at. Defaults to the first step after the trigger. Cannot be a trigger node.
  - `scheduledFor` string, date-time, nullable: Start the run at this moment instead of now (up to one year ahead). The run is created queued with a delayed job and can be cancelled before it starts. A past value starts now.
  - `data` object, nullable: Run-level data shared by everyone in this run (a sale end time, a discount percentage, a cut-off time). Stored on the run and copied into every enrolled contact's sequence context at enrollment time; the sequence's emails and conditions read it as `{{enrollment.<field>}}` (nested paths like `{{enrollment.draw.date}}` work). Must be a JSON object of at most 8 KB, 100 top-level keys and 8 levels of nesting; keys named __proto__, constructor or prototype and strings containing NUL characters are rejected. Omit, null or {} for none. Auto-enroll syncs do not carry run data.

## Response `200`

Run queued

- object
  - `success` boolean
  - `audienceEnrollment` SequenceAudienceEnrollment: One background audience enrollment run.
    - `id` string
    - `sequenceId` string
    - `status` 'queued' | 'running' | 'completed' | 'cancelled' | 'failed'
    - `audience` SequenceAudience: Who to enroll. Same shape as campaign targetLists.
      - `type` 'all' | 'lists' | 'segment' | 'filtered' | 'rules', required
      - `listIds` string[]: For type lists.
      - `segmentId` string: For type segment.
      - `filters` object[]: For type filtered; subscriber filters.
      - `filterJoinOperator` 'and' | 'or'
      - `include` object[]: For type rules; include rules of type all, lists, segments, or filtered.
      - `exclude` object[]: For type rules; exclude rules.
      - `excludedSubscriberIds` string[]: Contacts removed from the include rules. Does not remove contacts listed in includedSubscriberIds.
      - `includedSubscriberIds` string[]: Specific contacts to enroll in addition to the include rules. Use type rules with an empty include array to enroll only these contacts, with no per-request cap. IDs that belong to another company, or to contacts who are unsubscribed, bounced or without an email, are skipped.
    - `includedSubscriberCount` integer: Number of hand-picked contacts in `audience.includedSubscriberIds`, 0 when none.
    - `data` object, nullable: Run-level data passed when the run was started, read by the run's emails as `{{enrollment.<field>}}`. Null when none was given.
    - `targetNodeId` string, nullable: Step contacts start at.
    - `estimatedCount` integer: Audience size estimated when the run started.
    - `processedCount` integer: Subscribers scanned so far.
    - `enrolledCount` integer
    - `skippedCount` integer: Matching contacts skipped because they were already in the sequence (or, for one_time sequences, finished it before).
    - `source` string
    - `error` string, nullable
    - `createdAt` string, date-time
    - `scheduledFor` string, date-time, nullable: Delayed start. While set and in the future the run stays queued; cancel it before then to prevent the enrollment.
    - `startedAt` string, date-time, nullable
    - `completedAt` string, date-time, nullable
    - `cancelRequestedAt` string, date-time, nullable
  - `message` string

## Other responses

- `400`: Invalid audience, invalid run data, sequence not accepting enrollments, or invalid target node
- `401`: Unauthorized
- `404`: Sequence not found
- `409`: An audience enrollment is already queued or running for this sequence

## Changes

- **2026-10-22** `66405b8b1aca`: 3 info
  - added the new optional request property `audience/includedSubscriberIds`
  - added the optional property `audienceEnrollment/audience/includedSubscriberIds` to the response with the `200` status
  - added the optional property `audienceEnrollment/includedSubscriberCount` to the response with the `200` status
- **2026-10-16** `db3873ca3d4d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sequenzy/apis/sequenzy-api/changes/sequences/:sequenceId/enroll-audience/post.md)

---

[API](https://skmtc.dev/sequenzy/apis/sequenzy-api.md) - [All operations](https://skmtc.dev/sequenzy/apis/sequenzy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sequenzy/apis/sequenzy-api/revisions/8156dc12d8b4?raw)