> ## Documentation Index > Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a 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`. ## OpenAPI ````yaml POST /v1/subscriber_list/ openapi: 3.1.1 info: title: SuprSend API description: APIs supported on suprsend platform version: 1.2.2 servers: - url: https://hub.suprsend.com security: - sec0: [] - BearerAuth: [] paths: /v1/subscriber_list/: post: summary: Create a List description: >- 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`. operationId: create-list requestBody: content: application/json: schema: type: object required: - list_id properties: list_id: type: string description: >- Unique string identifier of the list. Add an id which defines the type of users who are part of the list. default: _list_id_ list_name: type: string description: >- Name of the List. Add a name which defines the type of users in the list. default: _list_name_ list_description: type: string description: Brief description of the list and the type of users in it. default: _some sample description_ list_type: type: string description: >- 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`. enum: - static_list - dynamic_list default: static_list query: type: string description: >- 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. example: >- SELECT distinct_id FROM users WHERE CAST(user_properties ->> 'lifetime_value' AS DOUBLE PRECISION) >= 2500 is_enabled: type: boolean description: >- 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. default: true responses: '201': description: '201' content: application/json: examples: Static list: value: list_id: product_updates list_name: Product Update list_description: Users subscribed to the newsletter list_type: static_list subscribers_count: 3 source: database_sync is_readonly: false status: active track_user_entry: false track_user_exit: false requested_for_delete: false created_at: '2024-02-21T19:10:01.906000Z' updated_at: '2025-04-04T07:25:43.186475Z' drafts: null Segment (dynamic) list: value: list_id: high_ltv_q1 list_name: High LTV Q1 list_description: Users with lifetime value >= 2500 list_type: dynamic_list subscribers_count: 30 source: suprsend is_readonly: false is_enabled: true query: >- SELECT distinct_id FROM users WHERE CAST(user_properties ->> 'lifetime_value' AS DOUBLE PRECISION) >= 2500 status: active track_user_entry: false track_user_exit: false requested_for_delete: false created_at: '2026-07-14T13:25:07.883000Z' updated_at: '2026-07-14T13:28:33.405495Z' drafts: null sync_task: id: 01KXGCBW5W29TC5FJ47JPA982W name: high_ltv_q1-01KXGCBW5G9WA1D6Y6081KGCMF is_enabled: true auto_refresh: true refresh_interval: null draft_version: null active_version: id: st_v_01KXGCR07KCG2PS48PRYJ5EPQP query: >- SELECT distinct_id FROM users WHERE CAST(user_properties ->> 'lifetime_value' AS DOUBLE PRECISION) >= 2500 version_no: 1 ai_description: Users whose lifetime value is at least 2500. schema: type: object properties: list_id: type: string description: Unique identifier of the list. example: product_updates list_name: type: string description: Name of the list. example: Product Update list_description: type: string description: Brief description of the list. example: Users subscribed to the newsletter list_type: type: string description: Type of the list. enum: - static_list - dynamic_list subscribers_count: type: integer description: number of users in the list source: type: string description: source info on how the list is updated example: database_sync is_readonly: type: boolean description: Indicates whether the list is read-only. example: false is_enabled: type: boolean description: >- For `dynamic_list` only. Whether the segment is actively refreshing. example: true query: type: string description: >- For `dynamic_list` only. The committed SQL query that defines the segment. example: >- SELECT distinct_id FROM users WHERE CAST(user_properties ->> 'lifetime_value' AS DOUBLE PRECISION) >= 2500 status: type: string description: Current status of the list (active or draft). example: active track_user_entry: type: boolean description: >- Event `$USER_ENTERED_LIST - ` is generated when user is added this list. Use this to trigger workflow on user entry. track_user_exit: type: boolean description: >- Event `$USER_EXITED_LIST - ` is generated when user is removed from this list. Use this to trigger workflow on user exit. requested_for_delete: type: boolean description: >- Indicates whether the list has been requested for deletion. example: false created_at: type: string format: date-time description: Timestamp when the list was created. example: '2024-02-21T19:10:01.906000Z' updated_at: type: string format: date-time description: Timestamp when the list was last updated. example: '2025-04-04T07:25:43.186475Z' drafts: type: string nullable: true description: would show the draft list created to replace list users. sync_task: type: object nullable: true description: >- For `dynamic_list` only. Metadata about the sync task that runs the segment query, including the currently active version and any uncommitted draft. properties: id: type: string description: Sync task identifier. name: type: string description: Sync task name (derived from `list_id`). is_enabled: type: boolean description: Whether the sync task is currently running. auto_refresh: type: boolean description: >- Whether the segment refreshes automatically as data changes. refresh_interval: type: string nullable: true description: Refresh cadence, if configured. draft_version: type: object nullable: true description: >- The uncommitted draft version, if any. Populated when a new query has been saved but not yet committed. properties: id: type: string description: Unique identifier of the draft version. query: type: string description: SQL query text saved in this draft. ai_description: type: string nullable: true description: >- AI-generated natural-language summary of what the draft query matches. active_version: type: object nullable: true description: >- The currently live (committed) version of the segment query that drives list membership. properties: id: type: string description: Unique identifier of the active version. query: type: string description: >- SQL query text currently committed and used to compute list membership. version_no: type: integer description: >- Monotonically increasing version number of the active query. Increments each time a new version is committed. ai_description: type: string nullable: true description: >- AI-generated natural-language summary of what the active query matches. '400': description: '400' content: application/json: examples: Result: value: code: 400 error_code: error type: ValidationError message: '{"list_id": ["This field may not be blank."]}' detail: list_id: - This field may not be blank. schema: type: object description: error code and related message detailing out the error deprecated: false security: - BearerAuth: [] components: securitySchemes: sec0: type: apiKey in: header name: Authorization x-bearer-format: bearer description: >- Bearer authentication header of the form `Bearer `, where is your auth token. BearerAuth: type: http scheme: bearer bearerFormat: API_Key description: >- Pass as `Bearer `. Get API Key from SuprSend dashboard Developers -> API Keys section. ````