POST/campaigns/:campaignId/leads/batch-delete
Permanently delete up to 100 leads from a campaign. Irreversible — confirm before calling.
0 credits (no credit refund). Rate class delete_leads_batch (default 10/min). Optional Idempotency-Key (max 128) — server persists a replay when summary.deleted > 0.
Request
POST /campaigns/search-xyz/leads/batch-delete
X-API-Key: sk_live_...
Content-Type: application/json
Idempotency-Key: client-unique-batch-delete-1
{
"leadIds": ["lead_abc", "lead_def"]
}
| Field | Required | Notes |
|---|---|---|
leadIds | Yes | Non-empty array, length 1…100 |
Unknown top-level keys → 400. Soft per-item: bad id, duplicate leadId.
Gates:
- Campaign still finding leads → envelope 409
conflict - Lead already emailed or queued to send → item
failed(not deleted)
Idempotency: array order matters. Re-post of already-deleted ids → item not_found (safe retry).
Response
{
"results": [
{ "index": 0, "leadId": "lead_abc", "status": "deleted" },
{ "index": 1, "leadId": "lead_def", "status": "deleted" }
],
"summary": {
"total": 2,
"deleted": 2,
"not_found": 0,
"validation_error": 0,
"failed": 0
},
"creditsCharged": 0,
"reconciliationFailed": false
}
Per-item status: deleted | not_found | validation_error | failed.
reconciliationFailed: true when post-delete campaign lead-count reconciliation fails (deletes still applied).
Per-id deletes continue after a single failure. If cleanup throws but the lead document is already gone, the item counts as deleted.
Errors
| Error code | When |
|---|---|
validation_error | Empty/leadIds over max / unknown body keys / bad Idempotency-Key |
not_found | Unknown campaign |
conflict | Campaign ingesting leads, or idempotency mismatch / in progress |
upstream_unavailable | Idempotency store unavailable, or hard failure before any durable delete |
Related
- List excluded leads: GET …/leads?excluded=true
- Bulk tag/exclude (non-destructive): POST …/leads/batch-update
- Credits (no refund): Credits and rate limits
MCP
Tool: delete_leads_batch — annotations destructiveHint: true, idempotentHint: true. Confirm with the user before calling.