Skip to main content
POST
Create a contact list

Authorizations

Authorization
string
header
required

Workspace API key, e.g. Authorization: Bearer tented_.... Create keys in Workspace Settings → API Keys.

Body

application/json
name
string
required

List name (1-255 chars). Must be unique within the workspace.

Required string length: 1 - 255
kind
enum<string>
required

static = membership managed manually via the member endpoints; dynamic = membership computed continuously from rules. Immutable after creation.

Available options:
static,
dynamic
description
string | null

Optional description (max 1,000 chars). Pass null to clear.

Maximum string length: 1000
rules
object | null

Segment rule tree for a dynamic list (a dynamic list without rules has no members). Must be omitted or null for static lists. email_step conditions are not allowed.

contact_ids
string<uuid>[]

Initial members for a static list (max 500 per request; add more via the members endpoint). Not allowed for dynamic lists.

Maximum array length: 500

Response

Contact list created.

list_id
string<uuid>
required

Contact list ID.

name
string
required

List name. Unique within the workspace.

kind
enum<string>
required

static = membership managed manually via the member endpoints; dynamic = membership computed continuously from rules; system = auto-managed by the platform (read-only). Immutable after creation.

Available options:
static,
dynamic,
system
created_at
string<date-time>
required

Creation time.

updated_at
string<date-time>
required

Last update.

slug
string | null

URL-safe identifier derived from the name.

description
string | null

Optional description.

rules
object | null

Segment rule tree for dynamic lists; null for static lists.

member_count
integer | null

Stored member count for static lists; null for dynamic lists — use GET /v1/contact-lists/{listId}/member-count for a live count.

owner_campaign_id
string<uuid> | null

Set when the list is a blast's inline audience; null for user-created lists.