> ## 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.
# Lists
> Manage subscriber lists with NodeJS SDK: create/update list, add/remove/replace users.
The Lists SDK methods lets you create / manage list of subscribers. You can then send [broadcast](/docs/broadcast) to all the users in the list or create a workflow that triggers when a new user enters / exits list.
## Create / Update List
You can use `supr_client.subscribers_list.create` method to create a new list
```javascript Request theme={"system"}
const { Suprsend } = require("@suprsend/node-sdk");
const supr_client = new Suprsend("workspace_key", "workspace_secret");
// create list API call
const response = supr_client.subscriber_lists.create({
list_id: "_list_id_",
list_name: "_list_name_",
list_description: "_some sample descritpion for list_",
});
data.then((res) => console.log(res)).catch((err) => console.log(err));
```
```javascript Response theme={"system"}
{
"list_id":"_list_id_",
"list_name":"_list_name_",
"list_description":"_some sample description for the list_",
"list_type":"static_list",
"subscribers_count":0,
"source":"None",
"is_readonly":false,
"status":"active",
"track_user_entry":false,
"track_user_exit":false,
"requested_for_delete":false,
"created_at":"2025-03-14T13:42:45.641000Z",
"updated_at":"2025-03-14T13:42:45.641000Z",
"drafts":"None"
}
```
Guidelines on defining the list\_id
* `list_id` is case-insensitive. Suprsend first converts list\_id to lowercase before storing it or doing any sort of comparison on it.
* `list_id `can be of max 64 characters.
* It can contain characters \[a-z0-9\_-] that is alphanumeric characters, \_(underscore) and -(hyphen).
## Get list data
You can get the latest information of a list using `supr_client.subscribers_list.get` method.
```javascript Request theme={"system"}
const data = supr_client.subscriber_lists.get("_list_id_");
```
```javascript Response theme={"system"}
{
"list_id": "list-id",
"list_name": "List Name",
"updated_at": "2022-12-18T10:40:27.268417+00:00",
"list_description": "List description"
}
```
## Get list of lists
To get the data of all the lists created in your workspace, use `supr_client.subscribers_list.get_all()` method
```javascript Request theme={"system"}
const data = supr_client.subscriber_lists.get_all(); // default limit 20
const data = supr_client.subscriber_lists.get_all({limit:20, offset:0}); // max limit 1000
```
```javascript Response theme={"system"}
{
"meta": {
"count": 14,
"limit": 20,
"offset": 0
},
"results": [
{
"list_id": "newsletter_subscribers",
"list_name": "Newsletter Subscribers",
"list_description": "all users who opted in to receive product updates",
"list_type": "static_list",
"subscribers_count": 0,
"source": "None",
"is_readonly": false,
"status": "active",
"track_user_entry": false,
"track_user_exit": false,
"requested_for_delete": false,
"created_at": "2025-01-14T13:42:45.641000Z",
"updated_at": "2025-01-14T13:42:45.641000Z",
"drafts": "None"
},
{
"list_id": "abandoned_application",
"list_name": "Signups abandoned application",
"list_description": "Users who didn’t finish application",
"list_type": "static_list",
"subscribers_count": 0,
"source": "None",
"is_readonly": false,
"status": "active",
"track_user_entry": true,
"track_user_exit": true,
"requested_for_delete": false,
"created_at": "2025-02-14T13:42:45.641000Z",
"updated_at": "2025-02-14T13:42:45.641000Z",
"drafts": "None"
}
...
]
}
```
## Add subscribers to list
Use `supr_client.subscribers_list.add()` to add list subscribers. There is no limit to the number of subscribers that you can add to a list.
```javascript Request theme={"system"}
const list_id = "_list_id_";
const subscribers = ["_distinct_id1_","_distinct_id2_", ..... ];
const data = supr_client.subscriber_lists.add(list_id, subscribers);
```
```javascript Response theme={"system"}
{
"success":true
}
```
## Remove subscribers from list
You can remove subscribers from the list using `supr_client.subscribers_list.remove()`
```javascript Request theme={"system"}
const list_id = "_list_id_";
const subscribers = ["_distinct_id1_","_distinct_id2_", ..... ];
const data = supr_client.subscriber_lists.remove(list_id, subscribers);
```
```javascript Response theme={"system"}
{
"success":true
}
```
## Delete list
```javascript Request theme={"system"}
const data = supr_client.subscriber_lists.delete("_list_id_");
```
## Replace users in the list
In case you want to refresh list with a new set of users completely, you can replace users by creating a draft version of the list and updating users in it.
This method will create a draft version of the list where you can add the new set of users to replace users.
```javascript Request theme={"system"}
const data = supr_client.subscriber_lists.start_sync("_list_id_");
```
You can use this method to add subscribers to List draft version created in the Step-1. You'll get `version_id` in start sync response.
```javascript Request theme={"system"}
const data = supr_client.subscriber_lists.add_to_version("_list_id_", "01HHCTXXXXXXXXXXX", ["_user_id_1","user_id_2"])
```
You can use this method to remove subscribers from List draft version created in Step-1. You'll get `version_id` in start sync response.
```javascript Request theme={"system"}
const data = supr_client.subscriber_lists.remove_from_version("_list_id_", "01HHCTXXXXXXXXXXX", ["_user_id_1","_user_id_2"])
```
Once your subscribers are updated in the list, use this method to finish sync and make the draft version updated in above steps live.
```javascript Request theme={"system"}
const data = supr_client.subscriber_lists.finish_sync("_list_id_", "01HHCTXXXXXXXXXXX")
```
***
### Delete draft list
You can also delete draft list if it's created by mistake.
```python Request theme={"system"}
const data = supr_client.subscriber_lists.delete_version("_list_id_", "01HHCTXXXXXXXXXXX");
```