Lists
Group leads to add them to campaigns together. 4 endpoints, each also a tool for your AI through MCP. Authentication and errors are on the overview.
Lead lists with counts
GET/api/v1/lists
MCP tool list_lead_listsRead-only
Returns
listsrequiredobject[]totalLeadsrequirednumberunlistedrequirednumber
curl https://ballast.to/api/v1/lists \
-H "Authorization: Bearer $BALLAST_API_KEY"Create a list
POST/api/v1/lists
MCP tool create_lead_list
Parameters
namerequiredstring
Returns
idrequiredstringnamerequiredstring
curl -X POST https://ballast.to/api/v1/lists \
-H "Authorization: Bearer $BALLAST_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"<name>"}'Rename a list
PATCH/api/v1/lists/{id}
MCP tool rename_lead_list
Parameters
idrequiredpath · stringnamerequiredstring
Returns
idrequiredstringnamerequiredstring
curl -X PATCH https://ballast.to/api/v1/lists/<id> \
-H "Authorization: Bearer $BALLAST_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"<name>"}'Delete a list
DELETE/api/v1/lists/{id}
The list goes; with deleteLeads its leads are deleted too, otherwise they stay in the workspace.
MCP tool delete_lead_listMCP asks to confirm
Parameters
idrequiredpath · stringdeleteLeadsquery · boolean
Returns
okrequiredtruedeletedLeadsrequirednumber
curl -X DELETE https://ballast.to/api/v1/lists/<id> \
-H "Authorization: Bearer $BALLAST_API_KEY"