lists

Fill a List from a Segment

POST /v1/lists/{id}/members

Auth required api.lists.manage

Copies a Segment's current members into the List, as a point-in-time snapshot. {id} resolves as a List id or its org-unique key; segment as a Segment id or its key.

This is a snapshot, not a subscription. A Segment is a live predicate re-evaluated as contact data changes; a List is an assignment log. Nothing re-runs this call, and the List does not track the Segment afterwards — a drip workflow with add to list is the standing version of the same idea.

Additive only. Members the Segment does not match are left in the List, and members already in it are counted in already_members and left alone. So member_count can exceed added + already_members. Removing members is the contacts surface.

Path parameters

id string required

The List's UUID or, when the value does not parse as a UUID, its org-unique key. Unknown handles read as 404 not_found. Accepted on every List route, read and write alike.

Request body

Content type: application/json

segment string required

The Segment to copy members from, by id or by its org-unique key.

Responses

Errors follow the RFC 7807 problem format — see the error reference.

200 The fill result application/json

list_id string<uuid> required

segment_id string<uuid> required

segment_key string required

added integer required

Memberships this call created.

already_members integer required

Segment members that were already in the List and were left alone.

member_count integer<int64> required

The List's total after the fill. Can exceed added + already_members: the fill is additive, so members the Segment does not match are still in the List and still counted.

401 Missing, malformed, or unknown API key application/problem+json

403 Key lacks the required scope or plan limit violated application/problem+json

404 Resource not found application/problem+json

422 A query parameter, path value or body field failed validation. The body is a validation_failed Problem. When the refusal is about a reference — a segment key, template slug, topic or attribute name the organization does not have — it additionally carries validation_code, field, line/column, missing, candidates and next_step, so a client can correct the call without a second round of guessing. See ValidationProblem. application/problem+json

429 Per-org rate limit exceeded application/problem+json

500 Unexpected server-side failure. The code is internal_error. The request_id field can be quoted to SendOps support to investigate. application/problem+json