---
title: "List opt-out lists"
description: "Returns all opt-out lists on your account, default lists first and then by name. Every\naccount has at least one default list. Not paginated.\n"
version: "v2"
---

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

Path: touchSMS API › Opt-out lists

`GET /v2/optout-lists`

Returns all opt-out lists on your account, default lists first and then by name. Every
account has at least one default list. Not paginated.

## Authentication

- `basicAuth`, http, header `Authorization`

## Code samples

### cURL

```bash
curl --request GET \
  --url https://app.touchsms.com.au/api/v2/optout-lists \
  --header 'Authorization: Basic <credentials>'
```

### TypeScript

```typescript
const url = 'https://app.touchsms.com.au/api/v2/optout-lists';
const options = {method: 'GET', headers: {Authorization: 'Basic <credentials>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://app.touchsms.com.au/api/v2/optout-lists"

headers = {"Authorization": "Basic <credentials>"}

response = requests.get(url, headers=headers)

print(response.text)
```

## Responses

### 200

All opt-out lists.

#### Example

```json
{
  "data": [
    {
      "id": 2,
      "name": "Marketing Opt-Outs",
      "is_default": false,
      "opt_out_count": 89,
      "created_at": "2024-03-10T14:30:22.000000Z",
      "updated_at": "2024-03-15T09:45:18.000000Z"
    }
  ]
}
```

- `data` (`listOptoutLists.response.200.data`; array<object>, optional)
  - `id` (`listOptoutLists.response.200.data.id`; integer, optional)
  - `name` (`listOptoutLists.response.200.data.name`; string, optional)
  - `is_default` (`listOptoutLists.response.200.data.is_default`; boolean, optional) — Whether this is your default opt-out list.
  - `opt_out_count` (`listOptoutLists.response.200.data.opt_out_count`; integer, optional) — Number of opt-outs in the list.
  - `created_at` (`listOptoutLists.response.200.data.created_at`; string, optional)
    - format `date-time`
  - `updated_at` (`listOptoutLists.response.200.data.updated_at`; string, optional)
    - format `date-time`

### 401

Missing, malformed or invalid API credentials.

#### Example

```json
{
  "message": "Unauthenticated."
}
```

- `message` (`listOptoutLists.response.401.message`; string, required)


Source: https://dev.touchsms.com.au/api/optout-lists/list/index.md