Create an empty prospect list
You can create a prospect list before anyone is on it. Use it when a form, a spreadsheet, or an agent should have a place to put people before the first row arrives.
In the app, open Contacts and choose New list. Name it, pick a color, and save. The list starts empty.
From your own system, send:
POST https://warmysender.com/api/v1/lists
Authorization: Bearer ws_your_api_key_here
Content-Type: application/json
Idempotency-Key: a unique value you choose for this one request
{"name":"Q3 outbound"}
The response includes the new list's id. Add people later with POST /api/v1/prospects and that id as listId.
A retry of the same request with the same Idempotency-Key returns that same list. A new request with the same name creates another list. Two lists are allowed to share a name, so keep the id.
To rename it, send the new name to PATCH /api/v1/lists/{id}. To delete it, use DELETE /api/v1/lists/{id}. Contacts who are only on that list are deleted with it. Contacts who are also on another list stay. If those contacts are still active in a running campaign, the delete is refused until you pause that campaign.
An agent that is connected to your workspace can do the same thing. Ask it:
Create an empty list called Q3 outbound. Check my lists first so you do not add a second list with the same name.
The agent lists your lists, creates one only when you still want it, and can rename or delete it. Deleting asks the agent to confirm, and it will refuse while the people who would be removed are still active in a running campaign. Nothing is sent by creating, renaming, or deleting a list.
The key needs the prospects write permission to create, rename, or delete, and the prospects read permission to list them. Create the key in Settings → API Keys.