> ## Documentation Index
> Fetch the complete documentation index at: https://usegately.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Contact Lists

> Create and manage contact lists, and add or remove members

Contact lists are static groups you manually curate. Use them to target specific audiences in email campaigns.

## Authentication

All endpoints require:

* `Authorization: Bearer YOUR_API_KEY`
* `X-Project-ID: YOUR_PROJECT_ID` (or encoded in the API key)

## Endpoints

| Method   | Path                                 | Description                  |
| -------- | ------------------------------------ | ---------------------------- |
| `GET`    | `/api/v1/contacts/lists`             | List all contact lists       |
| `POST`   | `/api/v1/contacts/lists`             | Create a list                |
| `GET`    | `/api/v1/contacts/lists/:id`         | Get a single list            |
| `PATCH`  | `/api/v1/contacts/lists/:id`         | Update a list                |
| `DELETE` | `/api/v1/contacts/lists/:id`         | Delete a list                |
| `GET`    | `/api/v1/contacts/lists/:id/members` | Get list members             |
| `POST`   | `/api/v1/contacts/lists/:id/members` | Add a contact to a list      |
| `DELETE` | `/api/v1/contacts/lists/:id/members` | Remove a contact from a list |

***

## List All Contact Lists

```bash theme={null}
GET https://api.usegately.com/api/v1/contacts/lists
```

```typescript SDK theme={null}
const lists = await crm.listContactLists()
```

**Response**

```json theme={null}
[
  {
    "id": "list-uuid",
    "project_id": "proj-uuid",
    "name": "Newsletter Subscribers",
    "description": "Monthly newsletter opt-ins",
    "created_at": "2025-01-01T00:00:00.000Z"
  }
]
```

***

## Create a List

```bash theme={null}
POST https://api.usegately.com/api/v1/contacts/lists
```

**Body**

```json theme={null}
{ "name": "Newsletter Subscribers", "description": "Monthly newsletter opt-ins" }
```

```typescript SDK theme={null}
const list = await crm.createContactList({
  name: 'Newsletter Subscribers',
  description: 'Monthly newsletter opt-ins',
})
```

***

## Update a List

```bash theme={null}
PATCH https://api.usegately.com/api/v1/contacts/lists/LIST_ID
```

```typescript SDK theme={null}
await crm.updateContactList('LIST_ID', { name: 'Weekly Newsletter' })
```

***

## Delete a List

Deletes the list. Contacts are **not** deleted.

```bash theme={null}
DELETE https://api.usegately.com/api/v1/contacts/lists/LIST_ID
```

```typescript SDK theme={null}
await crm.deleteContactList('LIST_ID')
```

***

## Get List Members

```bash theme={null}
GET https://api.usegately.com/api/v1/contacts/lists/LIST_ID/members?page=1&limit=100
```

```typescript SDK theme={null}
const members = await crm.getListMembers('LIST_ID', { page: 1, limit: 100 })
```

**Response**

```json theme={null}
[
  {
    "contact_id": "contact-uuid",
    "list_id": "list-uuid",
    "added_at": "2025-03-01T10:00:00.000Z",
    "crm_contacts": { "id": "contact-uuid", "name": "Jane Smith", "email": "jane@example.com" }
  }
]
```

***

## Add Contact to List

```bash theme={null}
POST https://api.usegately.com/api/v1/contacts/lists/LIST_ID/members
```

**Body**

```json theme={null}
{ "contact_id": "CONTACT_ID" }
```

```typescript SDK theme={null}
await crm.addContactToList('LIST_ID', 'CONTACT_ID')
```

***

## Remove Contact from List

```bash theme={null}
DELETE https://api.usegately.com/api/v1/contacts/lists/LIST_ID/members?contact_id=CONTACT_ID
```

```typescript SDK theme={null}
await crm.removeContactFromList('LIST_ID', 'CONTACT_ID')
```

***

## TypeScript Type

```typescript theme={null}
interface ContactList {
  id: string
  project_id: string
  name: string
  description?: string | null
  created_at: string
  updated_at?: string
}
```