Create a List

POST

subscriber_list

Create a List

curl --request POST \
  --url https://hub.suprsend.com/v1/subscriber_list/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "list_id": "_list_id_",
  "list_name": "_list_name_",
  "list_description": "_some sample description_",
  "list_type": "static_list",
  "query": "SELECT distinct_id FROM users WHERE CAST(user_properties ->> 'lifetime_value' AS DOUBLE PRECISION) >= 2500",
  "is_enabled": true
}
EOF

import requests

url = "https://hub.suprsend.com/v1/subscriber_list/"

payload = {
    "list_id": "_list_id_",
    "list_name": "_list_name_",
    "list_description": "_some sample description_",
    "list_type": "static_list",
    "query": "SELECT distinct_id FROM users WHERE CAST(user_properties ->> 'lifetime_value' AS DOUBLE PRECISION) >= 2500",
    "is_enabled": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    list_id: '_list_id_',
    list_name: '_list_name_',
    list_description: '_some sample description_',
    list_type: 'static_list',
    query: 'SELECT distinct_id FROM users WHERE CAST(user_properties ->> \'lifetime_value\' AS DOUBLE PRECISION) >= 2500',
    is_enabled: true
  })
};

fetch('https://hub.suprsend.com/v1/subscriber_list/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://hub.suprsend.com/v1/subscriber_list/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'list_id' => '_list_id_',
    'list_name' => '_list_name_',
    'list_description' => '_some sample description_',
    'list_type' => 'static_list',
    'query' => 'SELECT distinct_id FROM users WHERE CAST(user_properties ->> \'lifetime_value\' AS DOUBLE PRECISION) >= 2500',
    'is_enabled' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://hub.suprsend.com/v1/subscriber_list/"

	payload := strings.NewReader("{\n  \"list_id\": \"_list_id_\",\n  \"list_name\": \"_list_name_\",\n  \"list_description\": \"_some sample description_\",\n  \"list_type\": \"static_list\",\n  \"query\": \"SELECT distinct_id FROM users WHERE CAST(user_properties ->> 'lifetime_value' AS DOUBLE PRECISION) >= 2500\",\n  \"is_enabled\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://hub.suprsend.com/v1/subscriber_list/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"list_id\": \"_list_id_\",\n  \"list_name\": \"_list_name_\",\n  \"list_description\": \"_some sample description_\",\n  \"list_type\": \"static_list\",\n  \"query\": \"SELECT distinct_id FROM users WHERE CAST(user_properties ->> 'lifetime_value' AS DOUBLE PRECISION) >= 2500\",\n  \"is_enabled\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://hub.suprsend.com/v1/subscriber_list/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"list_id\": \"_list_id_\",\n  \"list_name\": \"_list_name_\",\n  \"list_description\": \"_some sample description_\",\n  \"list_type\": \"static_list\",\n  \"query\": \"SELECT distinct_id FROM users WHERE CAST(user_properties ->> 'lifetime_value' AS DOUBLE PRECISION) >= 2500\",\n  \"is_enabled\": true\n}"

response = http.request(request)
puts response.read_body

{
  "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
}

Authorizations

Authorization

string

header

required

Pass as Bearer <API_KEY>. Get API Key from SuprSend dashboard Developers -> API Keys section.

Body

application/json

list_id

string

default:_list_id_

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

default:_list_name_

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

list_description

string

default:_some sample description_

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

list_type

enum<string>

default:static_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.

Available options:

static_list,

dynamic_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 for the full dialect reference.

Example:

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

is_enabled

boolean

default:true

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

list_id

string

Unique identifier of the list.

Example:

"product_updates"

list_name

string

Name of the list.

Example:

"Product Update"

list_description

string

Brief description of the list.

Example:

"Users subscribed to the newsletter"

list_type

enum<string>

Type of the list.

Available options:

static_list,

dynamic_list

subscribers_count

integer

number of users in the list

source

string

source info on how the list is updated

Example:

"database_sync"

is_readonly

boolean

Indicates whether the list is read-only.

Example:

false

is_enabled

boolean

For dynamic_list only. Whether the segment is actively refreshing.

Example:

true

query

string

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

string

Current status of the list (active or draft).

Example:

"active"

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.

Example:

false

created_at

string<date-time>

Timestamp when the list was created.

Example:

"2024-02-21T19:10:01.906000Z"

updated_at

string<date-time>

Timestamp when the list was last updated.

Example:

"2025-04-04T07:25:43.186475Z"

drafts

string | null

would show the draft list created to replace list users.

sync_task

object | null

For dynamic_list only. Metadata about the sync task that runs the segment query, including the currently active version and any uncommitted draft.

Show child attributes

Add Users to ListAPI to add users to the list by passing their distinct_ids.

⌘I

Create a List

curl --request POST \
  --url https://hub.suprsend.com/v1/subscriber_list/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "list_id": "_list_id_",
  "list_name": "_list_name_",
  "list_description": "_some sample description_",
  "list_type": "static_list",
  "query": "SELECT distinct_id FROM users WHERE CAST(user_properties ->> 'lifetime_value' AS DOUBLE PRECISION) >= 2500",
  "is_enabled": true
}
EOF

import requests

url = "https://hub.suprsend.com/v1/subscriber_list/"

payload = {
    "list_id": "_list_id_",
    "list_name": "_list_name_",
    "list_description": "_some sample description_",
    "list_type": "static_list",
    "query": "SELECT distinct_id FROM users WHERE CAST(user_properties ->> 'lifetime_value' AS DOUBLE PRECISION) >= 2500",
    "is_enabled": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    list_id: '_list_id_',
    list_name: '_list_name_',
    list_description: '_some sample description_',
    list_type: 'static_list',
    query: 'SELECT distinct_id FROM users WHERE CAST(user_properties ->> \'lifetime_value\' AS DOUBLE PRECISION) >= 2500',
    is_enabled: true
  })
};

fetch('https://hub.suprsend.com/v1/subscriber_list/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://hub.suprsend.com/v1/subscriber_list/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'list_id' => '_list_id_',
    'list_name' => '_list_name_',
    'list_description' => '_some sample description_',
    'list_type' => 'static_list',
    'query' => 'SELECT distinct_id FROM users WHERE CAST(user_properties ->> \'lifetime_value\' AS DOUBLE PRECISION) >= 2500',
    'is_enabled' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://hub.suprsend.com/v1/subscriber_list/"

	payload := strings.NewReader("{\n  \"list_id\": \"_list_id_\",\n  \"list_name\": \"_list_name_\",\n  \"list_description\": \"_some sample description_\",\n  \"list_type\": \"static_list\",\n  \"query\": \"SELECT distinct_id FROM users WHERE CAST(user_properties ->> 'lifetime_value' AS DOUBLE PRECISION) >= 2500\",\n  \"is_enabled\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://hub.suprsend.com/v1/subscriber_list/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"list_id\": \"_list_id_\",\n  \"list_name\": \"_list_name_\",\n  \"list_description\": \"_some sample description_\",\n  \"list_type\": \"static_list\",\n  \"query\": \"SELECT distinct_id FROM users WHERE CAST(user_properties ->> 'lifetime_value' AS DOUBLE PRECISION) >= 2500\",\n  \"is_enabled\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://hub.suprsend.com/v1/subscriber_list/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"list_id\": \"_list_id_\",\n  \"list_name\": \"_list_name_\",\n  \"list_description\": \"_some sample description_\",\n  \"list_type\": \"static_list\",\n  \"query\": \"SELECT distinct_id FROM users WHERE CAST(user_properties ->> 'lifetime_value' AS DOUBLE PRECISION) >= 2500\",\n  \"is_enabled\": true\n}"

response = http.request(request)
puts response.read_body

{
  "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
}

API Reference

USERS

TRIGGER WORKFLOWS

EVENTS

MESSAGES

OBJECTS

TEMPLATES

TENANTS

PREFERENCE

LISTS

BROADCAST

Authorizations

Body

Response