# Lists and import

> Create a list, push contacts from your CRM in batches of 500, understand deduplication and turn your columns into first-message variables.

Source: https://docs.whatsetter.com/developers/guides/lists-import/

A list is a batch of contacts meant for a campaign. It is the only door for cold outreach: contacts go through WhatSetter's verification and paced, anti-ban sending, never through a direct send.

## Endpoints

| Method | Path | Scope |
|---|---|---|
| GET | [`/lists`](/api-reference/operations/listlists/) | `lists:read` |
| POST | [`/lists`](/api-reference/operations/createlist/) | `lists:write` |
| POST | [`/lists/{id}/leads`](/api-reference/operations/importleads/) | `lists:write` |

## Create a list

**cURL**

```bash
curl -X POST "https://app.whatsetter.com/api/v1/lists" \
  -H "Authorization: Bearer ws_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"CRM sync, hot leads"}'
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/lists', {
  method: 'POST',
  headers: { Authorization: 'Bearer ws_live_…', 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'CRM sync, hot leads' }),
});
const { data: list } = await res.json();
```

**Python**

```python
import requests

r = requests.post(
    "https://app.whatsetter.com/api/v1/lists",
    headers={"Authorization": "Bearer ws_live_…"},
    json={"name": "CRM sync, hot leads"},
)
lst = r.json()["data"]
```

```json
{
  "data": {
    "id": "66f1a2b3c4d5e6f7a8b9c0a1",
    "name": "CRM sync, hot leads",
    "status": "ready",
    "total_rows": 0,
    "valid_leads": 0,
    "invalid_leads": 0,
    "keep_open": false,
    "created_at": "2026-09-19T08:00:00.000Z"
  }
}
```

`name` is 1 to 255 characters. A workspace holds up to 200 lists; past that, `429 quota_exceeded`.

Add `"keep_open": true` for a list your CRM keeps feeding: see [A list that keeps growing](#a-list-that-keeps-growing). Anything but a boolean answers `422`.

## Import leads

Up to 500 leads per call. Each lead needs a `phone` in international format. `name`, `email` and `custom_variables` are optional.

**cURL**

```bash
curl -X POST "https://app.whatsetter.com/api/v1/lists/66f1a2b3c4d5e6f7a8b9c0a1/leads" \
  -H "Authorization: Bearer ws_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      { "phone": "+33612345678", "name": "Julien", "email": "julien@example.com",
        "custom_variables": { "city": "Lyon", "plan": "Pro" } },
      { "phone": "+33698765432", "name": "Marie" }
    ]
  }'
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/lists/66f1a2b3c4d5e6f7a8b9c0a1/leads', {
  method: 'POST',
  headers: { Authorization: 'Bearer ws_live_…', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    leads: [
      { phone: '+33612345678', name: 'Julien', email: 'julien@example.com',
        custom_variables: { city: 'Lyon', plan: 'Pro' } },
      { phone: '+33698765432', name: 'Marie' },
    ],
  }),
});
const { data: result } = await res.json();
```

**Python**

```python
import requests

r = requests.post(
    "https://app.whatsetter.com/api/v1/lists/66f1a2b3c4d5e6f7a8b9c0a1/leads",
    headers={"Authorization": "Bearer ws_live_…"},
    json={
        "leads": [
            {"phone": "+33612345678", "name": "Julien", "email": "julien@example.com",
             "custom_variables": {"city": "Lyon", "plan": "Pro"}},
            {"phone": "+33698765432", "name": "Marie"},
        ]
    },
)
result = r.json()["data"]
```

```json
{
  "data": {
    "imported": 2,
    "duplicates_in_list": 0,
    "rejected": [],
    "lead_ids": ["66f1a2b3c4d5e6f7a8b9c0b1", "66f1a2b3c4d5e6f7a8b9c0b2"],
    "list_status": "processing"
  }
}
```

The status is `201` as soon as at least one lead was importable. `lead_ids` are the imported rows, in the order they were created. `name` and `email` are cut at 255 characters. `list_status` is the list after the import: `ready` (not launched yet), `processing` (sending), `paused` or `completed`.

### Deduplication and rejections

| Case | What happens |
|---|---|
| Same number twice in the batch | The first one is kept, the other is listed in `rejected` with reason `duplicate_in_batch`. |
| Number already in this list | Not created again, counted in `duplicates_in_list`. |
| Invalid number | Listed in `rejected` with a reason starting with `invalid_phone`. A valid number is 8 to 15 digits, with or without `+`, spaces, dots, dashes or parentheses. |
| `custom_variables` is not an object | Rejected with reason `custom_variables must be an object`. |
| `custom_variables` over 2000 characters once serialized | Rejected with reason `custom_variables exceeds 2000 characters`. |

`rejected` entries carry the `index` of the lead in your array, so you can log or retry precisely.

> **Deduplication is per list**
The API deduplicates inside the batch and against this list. The campaign engine then applies its own protection before sending: a contact that any agent of the team already wrote to, or already talks with, never gets a cold first message.

### Custom columns become variables

Every key of `custom_variables` becomes a per-lead variable your agent can use in its first message, written `{{lead:key}}` in the prompt editor. Keys are normalized to a slug: accents removed, lowercase, anything that is not a letter or digit becomes `_`. `Ville du client` and `ville_du_client` are the same variable.

With the example above, the prompt can say `{{lead:city}}` and `{{lead:plan}}`. A key missing on a given lead is reported as not provided to the agent, which is told never to invent a value.

## Pagination

`GET /lists` returns the 100 most recent lists of the workspace, newest first, in `data`. There is no cursor on this endpoint.

```json
{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0a1",
      "name": "CRM sync, hot leads",
      "status": "ready",
      "total_rows": 2,
      "valid_leads": 0,
      "invalid_leads": 0,
      "keep_open": false,
      "created_at": "2026-09-19T08:00:00.000Z"
    }
  ]
}
```

`valid_leads` and `invalid_leads` are filled as WhatSetter verifies the numbers after import.

## How a list feeds a campaign

Importing does not send anything. The list is picked up by the campaign it is attached to in the dashboard: rows are verified, then sent at a human pace, within the number's daily quota. Attach the list from your campaign in the dashboard, then follow the leads with [`GET /leads?campaign_id=`](/developers/guides/leads/).

> **One import at a time per list**
Rows are numbered in order and the sender follows that order. Do not run two imports into the same list in parallel; sequential calls, or parallel calls into different lists, are safe.

## A list that keeps growing

Once its campaign has written to every contact, a list is finished (`status: completed`). Pushing new leads into it reopens it, exactly as adding contacts in the dashboard does:

| The list | What the import does |
|---|---|
| Kept open (`keep_open: true`) | Sends again at once, with the same pacing and daily quota. `list_status: processing`. |
| Not kept open (the default) | Waits for **Resume** in the dashboard. `list_status: paused`. |
| Paused by hand, or still sending | Left as it is: the new leads join the queue. |

To feed one list from a sheet or a CRM over weeks, create it with `"keep_open": true`, or switch on *Lists › your list › Sending › Keep the list open* in the dashboard. `GET /lists` returns `keep_open` on every list.

## Opt-in leads: the other door

When a person just signed up on your funnel and expects a message now, use [`POST /campaigns/{id}/leads`](/developers/guides/campaigns/) instead. It sends a personalized first message right away, with the same anti-ban protections, and lets you attach an `external_reference`.

## Errors you will meet

| HTTP | `code` | When |
|---|---|---|
| 401 | `missing_api_key`, `invalid_api_key` | Key absent, unknown or revoked. |
| 403 | `insufficient_scope` | The key lacks `lists:read` or `lists:write`. |
| 404 | `not_found` | Unknown list, or a list of another workspace. |
| 422 | `validation_error` | Missing or too long `name`; `leads` not an array of 1 to 500; no importable lead in the batch (the message gives the first reason). |
| 429 | `quota_exceeded` | 200 lists already exist in the workspace. |
| 429 | `rate_limited` | Too many requests this minute. Honor `Retry-After`. |

## Related

- [Campaigns: pause, resume, opt-in leads](/developers/guides/campaigns/)
- [Leads](/developers/guides/leads/)
- [Lists in the dashboard](/dashboard/lists/)
- [Anti-ban protection](/dashboard/anti-ban/)
