Skip to content

Docs

Get API key

Lists

Create a list

POST/lists

A new, empty list. Names can repeat, as in the app; send an Idempotency-Key to retry safely.

Try itSend a real request with your API key

Headers

Idempotency-Keystring
Any unique value up to 255 characters, like a UUID. The request runs once; repeats within 24 hours get the first answer, with Idempotent-Replayed: true. Up to 255 characters.

Body

namestringRequired
Up to 100 characters.

Answer

201 Created The new list.

dataListRequired
Inside it
- idstringRequired
  List ID.
- namestringRequired
- createdAtstring · date-timeRequired
- leadsintegerRequired
  People in the list.
- campaignsarray of objectRequired
  Campaigns that take people from this list.
  Each item
  - idstringRequired
  - namestringRequired
  - statusstringRequired
    draft: not launched. active: running. paused: stopped by the owner. completed: finished. One of draft, active, paused, completed.

Errors

400 Bad requestinvalid_request invalid_json duplicate_in_request
401 Unauthorizedunauthorized
404 Not foundnot_found not_in_campaign
409 Conflictconflict idempotency_in_progress workspace_busy campaign_finished campaign_without_list tag_limit lead_has_history campaign_not_launched campaign_cannot_resume ambiguous_email
413 Too largetoo_large
415 Wrong content typeunsupported_media_type
422 Can’t processidempotency_key_reused
429 Too many requestsrate_limited
500 Server errorserver_error

Every error has the same shape. See Errors.

POST /lists

curl -X POST "https://app.salesteam.dev/api/v1/lists" \
  -H "Authorization: Bearer $SALESTEAM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "Tier 1 founders"
}'

const response = await fetch("https://app.salesteam.dev/api/v1/lists", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SALESTEAM_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "name": "Tier 1 founders"
  }),
});
console.log(response.status, await response.json());

import os, uuid
import requests

response = requests.post(
    "https://app.salesteam.dev/api/v1/lists",
    headers={"Authorization": f"Bearer {os.environ['SALESTEAM_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "name": "Tier 1 founders",
    },
)
print(response.status_code, response.json())

201 answer

{
  "data": {
    "id": "list_5a1b",
    "name": "Tier 1 founders",
    "createdAt": "2026-11-12T10:30:00.000Z",
    "leads": 0,
    "campaigns": []
  }
}