---
title: "Create a List"
method: POST
path: "/v1/subscriber_list/"
---

# Create a List

`POST /v1/subscriber_list/`

API to create / manage lists to send notification to a bulk list of users. To create a [Segment List](/docs/segment-lists) — 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`.

## Request body

- object
  - `list_id` string, required — Unique string identifier of the list. Add an id which defines the type of users who are part of the list.
  - `list_name` string — Name of the List. Add a name which defines the type of users in the list.
  - `list_description` string — 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](/docs/segment-lists) whose membership is driven by a SQL query. Defaults to `static_list`.
  - `query` string — 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](/docs/segment-lists) for the full dialect reference.
  - `is_enabled` boolean — 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.

## Response `201`

201

- object
  - `list_id` string — Unique identifier of the list.
  - `list_name` string — Name of the list.
  - `list_description` string — Brief description of the list.
  - `list_type` 'static_list' | 'dynamic_list' — Type of the list.
  - `subscribers_count` integer — number of users in the list
  - `source` string — source info on how the list is updated
  - `is_readonly` boolean — Indicates whether the list is read-only.
  - `is_enabled` boolean — For `dynamic_list` only. Whether the segment is actively refreshing.
  - `query` string — For `dynamic_list` only. The committed SQL query that defines the segment.
  - `status` string — Current status of the list (active or draft).
  - `track_user_entry` boolean — Event `$USER_ENTERED_LIST - <list_id>` is generated when user is added this list. Use this to trigger workflow on user entry.
  - `track_user_exit` boolean — 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_delete` boolean — Indicates whether the list has been requested for deletion.
  - `created_at` string, date-time — Timestamp when the list was created.
  - `updated_at` string, date-time — Timestamp when the list was last updated.
  - `drafts` string, nullable — would show the draft list created to replace list users.
  - `sync_task` object, nullable — For `dynamic_list` only. Metadata about the sync task that runs the segment query, including the currently active version and any uncommitted draft.
    - `id` string — Sync task identifier.
    - `name` string — Sync task name (derived from `list_id`).
    - `is_enabled` boolean — Whether the sync task is currently running.
    - `auto_refresh` boolean — Whether the segment refreshes automatically as data changes.
    - `refresh_interval` string, nullable — Refresh cadence, if configured.
    - `draft_version` object, nullable — The uncommitted draft version, if any. Populated when a new query has been saved but not yet committed.
      - `id` string — Unique identifier of the draft version.
      - `query_text` string — SQL query text saved in this draft.
      - `ai_description` string, nullable — AI-generated natural-language summary of what the draft query matches.
    - `active_version` object, nullable — The currently live (committed) version of the segment query that drives list membership.
      - `id` string — Unique identifier of the active version.
      - `query_text` string — SQL query text currently committed and used to compute list membership.
      - `version_no` integer — Monotonically increasing version number of the active query. Increments each time a new version is committed.
      - `ai_description` string, nullable — AI-generated natural-language summary of what the active query matches.

## Other responses

- `400` — 400

---

[API](https://skmtc.net/suprsend/apis/suprsend-api.md) · [All operations](https://skmtc.net/suprsend/apis/suprsend-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/suprsend/suprsend-api/versions/8bd2574bd2c3/schema)