# Create a list

Source: https://docs.emelia.io/docs/lists/create-list

Guide: [Lists & contacts](https://docs.emelia.io/docs/lists.md)

`POST https://api.emelia.io/lists/list`

Creates an empty list with source `API` and status `mapped`, immediately ready to receive contacts through `POST /lists/list/{listId}/contacts` or the batch route. List names do not need to be unique: calling this twice creates two lists, so store the returned `listId`.

To make the contacts of the list enter a campaign, attach the list to the campaign (in the app or through the Campaigns API). Contacts added afterwards flow into the campaigns that use the list.

Do not send `source`: the value `Manual` is reserved to the web app and starts the list with most columns hidden, which removes their fields from `GET /lists/list/{listId}/rows` until contacts fill them.

## Authentication

Send your API key in the `Authorization` header: `Authorization: <your API key>`.

## Request body

Content type: `application/json`, required.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | List name, trimmed. Must not be empty. Min length 1. |

```json
{
  "name": "Acme prospects Q4"
}
```

## Example request

**cURL**

```bash
curl -X POST "https://api.emelia.io/lists/list" \
  -H "Authorization: $EMELIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme prospects Q4"
}'
```

**JavaScript**

```js
const response = await fetch('https://api.emelia.io/lists/list', {
  method: 'POST',
  headers: { Authorization: process.env.EMELIA_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "name": "Acme prospects Q4"
  }),
});
console.log(await response.json());
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://api.emelia.io/lists/list",
    headers={"Authorization": os.environ["EMELIA_API_KEY"]},
    json={
        "name": "Acme prospects Q4"
    },
)
print(response.json())
```

## Responses

### 201: List created.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | boolean | yes |  |
| `listId` | string | yes |  |
| `name` | string | yes |  |

```json
{
  "success": true,
  "listId": "66f1c0ffee5a7d3b2c4e8a10",
  "name": "Acme prospects Q4"
}
```

### 401: Missing, unknown or disabled API key, or the account of the key no longer exists. Note the body shape: `error` and `code`, not `message`.

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | string | yes |  |
| `code` | enum: `AUTH_REQUIRED`, `ACCOUNT_NOT_FOUND` | yes |  |

```json
{
  "error": "string",
  "code": "AUTH_REQUIRED"
}
```

### 422: Missing or empty name.

| Field | Type | Required | Description |
|---|---|---|---|
| `message` | string | yes | English, human-readable message. |
| `code` | string | no | Stable error code, when available (for example `PAYLOAD_TOO_LARGE`, `INVALID_JSON`, `export_too_large`, `companies_only`, `enrichment_running`). |
| `params` | object | no |  |
| `error` | string | no | Raw internal message (unexpected errors only). |

```json
{
  "message": "name is required"
}
```

### 500: Unexpected server error. `error`, when present, is a raw internal message: do not parse it. Retry later.

| Field | Type | Required | Description |
|---|---|---|---|
| `message` | string | yes | English, human-readable message. |
| `code` | string | no | Stable error code, when available (for example `PAYLOAD_TOO_LARGE`, `INVALID_JSON`, `export_too_large`, `companies_only`, `enrichment_running`). |
| `params` | object | no |  |
| `error` | string | no | Raw internal message (unexpected errors only). |

```json
{
  "message": "Hmm... Something went wrong. Please try again later."
}
```