> ## 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 Java SDK: create or update lists, and modify users in the list.

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 `suprClient.subscriberLists.create` method to create a new list

<CodeGroup>
  ```java Request theme={"system"}
  import org.json.JSONObject;

  import suprsend.Suprsend;
  import suprsend.SuprsendAPIException;
  import suprsend.SubscriberListBroadcast;
  import suprsend.SuprsendValidationError;

  public class Lists {
    public static void main(String[] args) throws Exception {
      createList();
    }

    private static Subscriber createList() throws SuprsendException {
  		Suprsend suprsendClient = new Suprsend("_workspace_key_", "_workspace_secret_");

      // Create List JSON payload
      JSONObject payload = new JSONObject().put("list_id", "_list_id_");
                                           .put("list_name", "_list_name_ ");
      		                            .put("list_description", "_some sample description for the list_");
          try {
              JSONObject res = suprClient.subscriberLists.create(payload);
              System.out.println(res);
          } catch (SuprsendException e) {
              System.out.println(e);
          }
  	}
  ```

  ```java 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"
  }
  ```
</CodeGroup>

<Note>
  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).
</Note>

## Get list data

You can get the latest information of a list using  `suprClient.subscriberLists.get`  method.

<CodeGroup>
  ```java Request theme={"system"}
    ...
    String listId = "_list_id_";
    JSONObject res = suprClient.subscriberLists.get(listId);
    System.out.println(res);
  ```

  ```java 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"
  }
  ```
</CodeGroup>

## Get all lists

To get the data of all the lists created in your workspace, use `suprClient.subscriberLists.getAll()`  method

<CodeGroup>
  ```java Request theme={"system"}
    ...
      // To get the list of 20 subscriber lists
    JSONObject res = suprClient.subscriberLists.getAll();

    // Get list with offset = 10 and limit = 20
    // JSONObject res = suprClient.subscriberLists.getAll(20,10);
    System.out.println(res);
  ```

  ```java Response theme={"system"}
  {
    "meta": {
      "limit": 20,
      "offset": 0,
      "count": 1
    },
    "results": [
      {
        "list_id": "list-id1",
        "list_name": "List Name1",
        "updated_at": "2022-12-18T10:40:27.268417+00:00",
        "list_description": "List description1"
      },
      {
        "list_id": "list-id2",
        "list_name": "List Name2",
        "updated_at": "2022-12-19T10:40:27.268417+00:00",
        "list_description": "List description2"
      }
    ]
  }
  ```
</CodeGroup>

## Add Subscribers to the list

Use `suprClient.subscriberLists.add()` to add list subscribers. There is no limit to the number of subscribers that you can add to a list.

<CodeGroup>
  ```java Request theme={"system"}

    //Add one or more distinct ids in the list
    String distinctId1 = "id-1";
    String distinctId2 = "id-2";
    String distinctId3 = "id-3";
    ArrayList<String> distinctIds = new ArrayList<>(Arrays.asList(distinctId1,distinctId2,distinctId3));
    try {
      String listId = "l-001";
      JSONObject res = suprClient.subscriberLists.add(listId, distinctIds);
      System.out.println(res);
    }
  ```

  ```java Response theme={"system"}
  {
     "success":true
  }
  ```
</CodeGroup>

## Remove Subscribers from the list

You can remove subscribers from the list using `suprClient.subscriberLists.remove()`

<CodeGroup>
  ```java Request theme={"system"}

    //Add one or more distinct ids in the list
    String distinctId1 = "id-1";
    String distinctId2 = "id-2";
    ArrayList<String> distinctIds = new ArrayList<>(Arrays.asList(distinctId1,distinctId2,distinctId3));
    try {
      String listId = "l-001";
      JSONObject res = suprClient.subscriberLists.remove(listId, distinctIds);
      System.out.println(res);
    }
  ```

  ```java Response theme={"system"}
  {
     "success":true
  }
  ```
</CodeGroup>

## Delete list

You can delete a subscriber list using the `supr_client.subscriberLists.delete()` method.

<CodeGroup>
  ```java Request theme={"system"}
  import org.json.JSONObject;

  import suprsend.Suprsend;
  import suprsend.SuprsendAPIException;
  import suprsend.SubscriberListBroadcast;
  import suprsend.SuprsendValidationError;

  public class Lists {
    public static void main(String[] args) throws Exception {
      deleteList();
    }

    private static void deleteList() throws SuprsendException {
      Suprsend suprsendClient = new Suprsend("_workspace_key_", "_workspace_secret_");

      try {
        String listId = "_list_id_";
        JSONObject res = suprsendClient.subscriberLists.delete(listId);
        System.out.println(res);
      } catch (SuprsendException e) {
        System.out.println(e);
      }
    }
  }
  ```

  ```java Response theme={"system"}
  {
     "success": true
  }
  ```
</CodeGroup>

## Replace users in the List

In case you want to refresh a 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.

<Steps>
  <Step title="Start Sync to create draft version of the list">
    This method will create a draft version of the list where you can add the new set of users to replace users.

    <CodeGroup>
      ```java Request theme={"system"}
      JSONObject data = suprClient.subscriberLists.startSync("_list_id_");
      ```
    </CodeGroup>
  </Step>

  <Step title="Add Subscribers to draft list">
    Add subscribers to the draft version created in Step-1. You'll get `version_id` in the Start Sync response.

    <CodeGroup>
      ```java Request theme={"system"}
      JSONObject data = suprClient.subscriberLists.addToVersion("_list_id_", "01HHCTXXXXXXXXXXX", Arrays.asList("_user_id_1", "_user_id_2"));
      ```
    </CodeGroup>
  </Step>

  <Step title="Remove Subscribers from draft list">
    Remove subscribers from the draft version created in Step-1.

    <CodeGroup>
      ```java Request theme={"system"}
      JSONObject data = suprClient.subscriberLists.removeFromVersion("_list_id_", "01HHCTXXXXXXXXXXX", Arrays.asList("_user_id_1", "_user_id_2"));
      ```
    </CodeGroup>
  </Step>

  <Step title="Finish Sync to make the draft version live">
    Finalize the sync and make the draft version live.

    <CodeGroup>
      ```java Request theme={"system"}
      JSONObject data = suprClient.subscriberLists.finishSync("_list_id_", "01HHCTXXXXXXXXXXX");
      ```
    </CodeGroup>
  </Step>
</Steps>

### Delete Draft list

You can also delete a draft list if it was created by mistake.

<CodeGroup>
  ```java Request theme={"system"}
  JSONObject data = suprClient.subscriberLists.deleteVersion("_list_id_", "01HHCTXXXXXXXXXXX");
  ```
</CodeGroup>