Skip to content
Dashboard
POST
/lists
curl --request POST \
--url https://app.whatsetter.com/api/v1/lists \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "name": "CRM sync, hot leads", "keep_open": false }'

Creates an empty list you can then push leads into. A workspace holds at most 200 lists (429 quota_exceeded beyond that: delete unused lists first). Requires scope lists:write.

Media typeapplication/json
object
name
required
string
<= 255 characters
keep_open

Keep the list open: once its campaign has written to every contact, leads you push later go out on their own, with the same pacing and daily quota. Off, a finished list waits for Resume in the dashboard. Also set in the dashboard: Lists › list › Sending › Keep the list open.

boolean

Created

Media typeapplication/json
object
data
object
id
string
name
string | null
status
string | null
total_rows
integer
valid_leads
integer
invalid_leads
integer
keep_open

Leads pushed after the campaign wrote to everyone go out on their own (see POST /lists).

boolean
created_at
string format: date-time
Examplegenerated
{
"data": {
"id": "example",
"name": "example",
"status": "example",
"total_rows": 1,
"valid_leads": 1,
"invalid_leads": 1,
"keep_open": true,
"created_at": "2026-04-15T12:00:00Z"
}
}

Missing, unknown or revoked API key

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

Invalid parameter or body (also an invalid or expired cursor)

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

The workspace already holds 200 lists

Media typeapplication/json
object
error
object
code
string
message
string
Example
{
"error": {
"code": "quota_exceeded",
"message": "List limit reached (200 per workspace). Delete unused lists first."
}
}