# Create a list

`POST https://app.whatsetter.com/api/v1/lists`

Creates an empty list you can then push leads into. A workspace holds
at most 200 lists (`429 quota_exceeded` beyond that: delete unused
lists first). Requires scope `lists:write`.

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes |  |
| `keep_open` | boolean | no | Keep the list open: once its campaign has written to every contact, leads you push later go out on their own, with the same pacing and daily quota. Off, a finished list waits for **Resume** in the dashboard. Also set in the dashboard: *Lists › list › Sending › Keep the list open*.  |

```json
{
  "name": "",
  "keep_open": false
}
```

## Example request

```bash
curl --request POST \
  --url 'https://app.whatsetter.com/api/v1/lists' \
  --header 'Authorization: Bearer ws_live_…'
  --header 'Content-Type: application/json' \
  --data '{"name":"","keep_open":false}'
```

## Responses

### 201: Created

```json
{
  "data": {
    "id": "",
    "name": "",
    "status": "",
    "total_rows": 0,
    "valid_leads": 0,
    "invalid_leads": 0,
    "keep_open": false,
    "created_at": ""
  }
}
```

### 401: Missing, unknown or revoked API key

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 422: Invalid parameter or body (also an invalid or expired `cursor`)

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 429: The workspace already holds 200 lists

```json
{
  "error": {
    "code": "quota_exceeded",
    "message": "List limit reached (200 per workspace). Delete unused lists first."
  }
}
```


Source: https://docs.whatsetter.com/api-reference/operations/createlist/
