v2

latestOpenAPI 3.1.12026-07-2613060964.2 KB

Create a List

API to create / manage lists to send notification to a bulk list of users. To create a Segment List — a list whose membership is driven by a SQL query against your users and events tables — pass list_type: dynamic_list along with the query.

post/v1/subscriber_list/

Request body

list_idstring required

Unique string identifier of the list. Add an id which defines the type of users who are part of the list.

list_namestring

Name of the List. Add a name which defines the type of users in the list.

list_descriptionstring

Brief description of the list and the type of users in it.

list_type'static_list' | 'dynamic_list'

Type of the list. Use dynamic_list to create a Segment List whose membership is driven by a SQL query. Defaults to static_list.

querystring

SQL query defining the segment. Required when list_type: dynamic_list. Must return a distinct_id column and reference only the users and events tables. See the Segment Lists doc for the full dialect reference.

is_enabledboolean

Only applies to dynamic_list. When true, the segment starts syncing immediately after create. When false, the query is saved but the segment does not refresh until you enable it.

Example request

{
  "query": "SELECT distinct_id FROM users WHERE CAST(user_properties ->> 'lifetime_value' AS DOUBLE PRECISION) >= 2500"
}

Response

201

list_idstring

Unique identifier of the list.

list_namestring

Name of the list.

list_descriptionstring

Brief description of the list.

list_type'static_list' | 'dynamic_list'

Type of the list.

subscribers_countinteger

number of users in the list

sourcestring

source info on how the list is updated

is_readonlyboolean

Indicates whether the list is read-only.

is_enabledboolean

For dynamic_list only. Whether the segment is actively refreshing.

querystring

For dynamic_list only. The committed SQL query that defines the segment.

statusstring

Current status of the list (active or draft).

track_user_entryboolean

Event $USER_ENTERED_LIST - <list_id> is generated when user is added this list. Use this to trigger workflow on user entry.

track_user_exitboolean

Event $USER_EXITED_LIST - <list_id> is generated when user is removed from this list. Use this to trigger workflow on user exit.

requested_for_deleteboolean

Indicates whether the list has been requested for deletion.

created_atstring date-time

Timestamp when the list was created.

updated_atstring date-time

Timestamp when the list was last updated.

draftsstring nullable

would show the draft list created to replace list users.

Example response

{
  "list_id": "product_updates",
  "list_name": "Product Update",
  "list_description": "Users subscribed to the newsletter",
  "source": "database_sync",
  "is_enabled": true,
  "query": "SELECT distinct_id FROM users WHERE CAST(user_properties ->> 'lifetime_value' AS DOUBLE PRECISION) >= 2500",
  "status": "active",
  "created_at": "2024-02-21T19:10:01.906000Z",
  "updated_at": "2025-04-04T07:25:43.186475Z"
}