> Reverse Contact API documentation. This is the Markdown copy of https://docs.reversecontact.com/endpoints/list-create
> Every page is listed at https://docs.reversecontact.com/llms.txt, every endpoint with its credit cost and status at https://docs.reversecontact.com/catalog.json

# Create a List

> Create an empty List of people or companies in your workspace for free, and use an Idempotency-Key header to retry without creating duplicates.

- Endpoint: `POST https://api.reversecontact.com/v2/lists`
- Credits: Free.
- Answer: synchronous.
- Available in: REST API, MCP tool `create_list`, TypeScript and Python SDKs.
- Last verified: 2026-11-04

## Introduction

The Create a List endpoint creates an empty List of people or of companies. A List never mixes both: its `entity` decides which Signals it accepts and which data families it can hold. Fill it afterwards with [Add members](https://docs.reversecontact.com/endpoints/list-members-add) or [Import members and data](https://docs.reversecontact.com/endpoints/list-intake-signals).

Creating a List is **free** (0 credits). A workspace holds at most 200 Lists, and 1 on the free trial: past that, the request returns `409 LIST_LIMIT_REACHED`. When the name is already taken, the List is created as `Name (2)`.

The first List of a workspace also sets up where its Lists are stored. While that runs, the request returns `503 LISTS_PREPARING`, with `error.details.retryAfterSeconds`: send the same request again a few seconds later, with the same `Idempotency-Key`.

The API key needs the `lists` permission (see [API key management](https://docs.reversecontact.com/guides/api-key-management)).

## Authorization

| Name     | Type   | Required | Description                                                                                         |
| -------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| `apikey` | string | Yes      | Your API key from the developer dashboard. Pass it via `Authorization: Bearer YOUR_API_KEY` header. |

## Request body

| Name     | Type   | Required | Description                                |
| -------- | ------ | -------- | ------------------------------------------ |
| `name`   | string | Yes      | List name, 1 to 200 characters. Spaces around it are removed. |
| `entity` | string | Yes      | `persons` for people, `companies` for companies |

### Retry safely with Idempotency-Key

Send an `Idempotency-Key` header (1 to 200 printable ASCII characters, no spaces) to make the creation safe to retry: a second request with the same key returns the List the first one created, with `201`, instead of creating `Name (2)`. Reusing the key for the other `entity` returns `409 IDEMPOTENCY_KEY_REUSED`.

## Response structure

The response has status `201`.

| Field     | Type    | Description                                      |
| --------- | ------- | ------------------------------------------------ |
| `success` | boolean | `true` if the List was created                   |
| `error`   | `null`  | Always `null` on success                         |

**data** (List): The List created, or the List this Idempotency-Key created

| Field                | Type           | Description                                          |
| -------------------- | -------------- | ---------------------------------------------------- |
| `id`                 | string         | List id (UUID): keep it to fill and read the List    |
| `name`               | string         | List name, suffixed when the name was already taken  |
| `entity`             | string         | `persons` or `companies`                             |
| `memberCount`        | number         | List Members, `0` for a new List                     |
| `pendingIntakeCount` | number         | Pending Intake lines, `0` for a new List             |
| `revision`           | number         | Raised by every change to the members                |
| `archivedAt`         | `null`         | `null` for an active List                            |
| `createdAt`          | string         | Creation date (ISO 8601)                             |
| `updatedAt`          | string         | Last update date (ISO 8601)                          |
| `originQuery`        | `null`         | `null` for a List created through the API            |
| `originLastFind`     | `null`         | `null` for a List created through the API            |

`quotas` and `metadata` are the blocks of every V2 response: see [Usage](https://docs.reversecontact.com/endpoints/usage#response-structure).

## Errors

| Status | Code                     | Meaning                                                          |
| ------ | ------------------------ | ---------------------------------------------------------------- |
| `400`  | `LIST_INVALID_INPUT`     | The `Idempotency-Key` header is malformed, or `name` holds only spaces |
| `409`  | `LIST_LIMIT_REACHED`     | The workspace already has 200 Lists (1 on the free trial)        |
| `409`  | `IDEMPOTENCY_KEY_REUSED` | The key already created a List of the other `entity`             |
| `422`  | `VALIDATION_ERROR`       | `name` is missing or too long, or `entity` is not a known value  |
| `503`  | `LISTS_PREPARING`        | The first List of the workspace is being set up: retry in a few seconds |

## Code examples

**Code Examples**

```bash [cURL]
curl -X POST https://api.reversecontact.com/v2/lists \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-sync-2026-10-28" \
  -d '{ "name": "Q4 sales leaders", "entity": "persons" }'
```
```javascript [JavaScript]
const response = await fetch("https://api.reversecontact.com/v2/lists", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": "crm-sync-2026-10-28"
  },
  body: JSON.stringify({ name: "Q4 sales leaders", entity: "persons" })
});

const { data: list } = await response.json();
console.log("List created:", list.id);
```
```python [Python]
import requests

response = requests.post(
    "https://api.reversecontact.com/v2/lists",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "crm-sync-2026-10-28"
    },
    json={"name": "Q4 sales leaders", "entity": "persons"}
)

print("List created:", response.json()["data"]["id"])
```

## Example response

**Example Response**

```json [201 - Created]
{
  "success": true,
  "data": {
    "id": "3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40",
    "name": "Q4 sales leaders",
    "entity": "persons",
    "memberCount": 0,
    "pendingIntakeCount": 0,
    "revision": 1,
    "archivedAt": null,
    "createdAt": "2026-10-28T09:12:44.000Z",
    "updatedAt": "2026-10-28T09:12:44.000Z",
    "originQuery": null,
    "originLastFind": null
  },
  "error": null,
  "quotas": {
    "creditsConsumed": 0,
    "workspace": {
      "id": "ws_abc123",
      "credits": { "total": 10000, "used": 4521, "left": 5479 }
    }
  },
  "metadata": {
    "requestId": "b4777f52-42fd-44e7-abc5-19955b65c753",
    "executionTimeMs": 52
  }
}
```
```json [409 - Limit reached]
{
  "success": false,
  "data": null,
  "error": {
    "code": "LIST_LIMIT_REACHED",
    "message": "This workspace already has 200 lists"
  },
  "quotas": {
    "creditsConsumed": 0,
    "workspace": {
      "id": "ws_abc123",
      "credits": { "total": 10000, "used": 4521, "left": 5479 }
    }
  },
  "metadata": {
    "requestId": "3f594ff6-5425-4f46-b2b9-8c65acebd9f0",
    "executionTimeMs": 21
  }
}
```