Skip to main content
PATCH
Update a list

Authorizations

Authorization
string
header
required

Project-scoped secret API key (sk_…). Pass in the Authorization: Bearer <key> header. Grants access to the project the key was issued for.

Path Parameters

listId
integer | null

Numeric list identifier.

Example:

91

Body

application/json

Update an existing list. Only name is required; other fields are merged.

name
string
required

Updated human-readable list name.

Minimum string length: 1
rule
object

Updated rule tree for dynamic lists. Ignored on static lists.

tags
string[] | null

Tags applied to the list. Used for organisation and filtering.

published
boolean | null

Set to true to mark the list as published. Once published, edits trigger a re-materialisation for dynamic lists.

Response

The updated list.

A static or dynamic group of users. Used to send campaigns and as a segment input.

id
integer
required

Numeric list identifier.

Example:

91

project_id
integer
required

Identifier of the project the list belongs to.

Example:

42

name
string
required

Human-readable list name.

Example:

"Newsletter subscribers — Q2 2026"

type
enum<string>
required

A static list has explicit members. A dynamic list is materialised from a rule tree.

Available options:
static,
dynamic
state
enum<string>
required

Current list state. loading while a refresh is in progress; ready once members are materialised.

Available options:
draft,
ready,
loading
version
integer
required

Monotonically incrementing version. Bumped on rule edits.

Example:

3

is_visible
boolean
required

Whether the list is shown in the in-product UI list directory.

created_at
string | null
required

Time the list was created. ISO 8601.

updated_at
string | null
required

Time the list was last modified. ISO 8601.

rule
object

Membership rule tree for dynamic lists. Absent on static lists.

rule_id
integer | null

Internal identifier of the persisted root rule, when present.

users_count
integer | null

Cached size of the list. May lag a few seconds behind reality.

Example:

12584

tags
string[] | null

Tags applied to the list. Used for organisation and filtering.

refreshed_at
string | null

Time the dynamic list was last refreshed.