> For the complete documentation index, see [llms.txt](https://developer.parvenu.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.parvenu.io/manage-lists/create-a-list.md).

# Create a List

Create an empty list by name, ready to add contacts to.

<mark style="color:green;">`POST`</mark> `/list_create`

Creates an empty list called `listname`. Nothing is sourced or enriched. The list is ready for [Add a Contact](/manage-lists/add-a-contact.md), [Add Contacts in Bulk](/manage-lists/add-contacts-in-bulk.md) or any enrichment that writes to a list.

{% hint style="info" %}
**Free.** `credits_used` is always `0`.
{% endhint %}

{% hint style="success" %}
**Safe to repeat.** If a list with that name already exists, nothing changes and `list_created` comes back `false`. The existing list and its contacts are left exactly as they were.
{% endhint %}

You do not have to create a list before adding to it. The add endpoints create a missing list for you unless you send `create_list: false`.

## Headers

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |

## Body

| Name       | Type   | Description                                                                          |
| ---------- | ------ | ------------------------------------------------------------------------------------ |
| `api_key`  | string | **Required.** Your API key.                                                          |
| `listname` | string | **Required.** The name of the list. One word, not `list_name`. Up to 200 characters. |

## Response

| Field               | Description                                                     |
| ------------------- | --------------------------------------------------------------- |
| `status`            | `success`.                                                      |
| `data.list_name`    | The list's name.                                                |
| `data.list_created` | `true` when the list was made, `false` when it already existed. |
| `credits_used`      | Always `0`.                                                     |

## Example

{% tabs %}
{% tab title="Input" %}

```json
{
  "api_key": "your_api_key",
  "listname": "Q4 Roofers"
}
```

{% endtab %}

{% tab title="Output" %}

```json
{
  "status": "success",
  "credits_used": 0.0,
  "credits_remaining": 6042.2,
  "message": "Created an empty list called 'Q4 Roofers'.",
  "data": {
    "list_name": "Q4 Roofers",
    "list_created": true
  }
}
```

{% endtab %}
{% endtabs %}

Sending the same call again returns `list_created: false` and leaves the list untouched.