Skip to content
Dashboard

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.

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.

Method Path Scope
GET /lists lists:read
POST /lists lists:write
POST /lists/{id}/leads lists:write
Terminal window
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"}'
{
"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. Anything but a boolean answers 422.

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

Terminal window
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" }
]
}'
{
"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.

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.

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.

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

{
"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.

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=.

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.

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

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.