---
title: Lists
description: Your own segmentation, and adding or removing members.
---

Lists are how you group contacts for your own purposes. They are not
permission: see [core concepts](/guide/concepts#list).

## List lists

`GET /v1/lists`

```bash
curl https://api.zevcampaign.com/v1/lists \
  -H "Authorization: Bearer sk_live_your_key_here"
```

```json
{
  "data": [
    {
      "id": "ls_4m2kx9",
      "name": "Lagos customers",
      "description": "Anyone who has bought from the Lagos store.",
      "brand_id": "br_3nf8q1",
      "member_count": 412,
      "created_at": "2026-02-01T08:00:00.000Z"
    }
  ],
  "meta": { "limit": 20, "has_more": false, "next_cursor": null }
}
```

## Add members

`POST /v1/lists/{id}/members`

```bash
curl https://api.zevcampaign.com/v1/lists/ls_4m2kx9/members \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "contact_ids": ["ct_8vq2xk4m", "ct_1p9wz3"] }'
```

```json
{
  "data": { "added": 2, "already_members": 0, "member_count": 414 }
}
```

Idempotent. A contact already on the list counts under
`already_members` rather than failing the call, so a retry is safe.

## Remove members

`DELETE /v1/lists/{id}/members`

```bash
curl -X DELETE https://api.zevcampaign.com/v1/lists/ls_4m2kx9/members \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "contact_ids": ["ct_8vq2xk4m"] }'
```

```json
{
  "data": { "removed": 1, "member_count": 413 }
}
```

Removing somebody from a list does **not** unsubscribe them. They keep
every topic subscription they had; you have only changed your own
segmentation. To stop mailing somebody entirely, see
[suppressions](/api/suppressions).

## Membership does not grant permission

Adding a contact to a list does not let you mail them about anything
they have not consented to.

A campaign sent to a list still only reaches the people on it who are
subscribed to that campaign's topic. If you add 500 contacts to a list
and 200 of them are not subscribed to the topic, 300 get the campaign.

This surprises people, so it is worth saying plainly: the list narrows
*who you are considering*, the topic decides *who you may send to*.