Skip to content
Docs

Bulk Delete Leads

Delete many leads at once and stop them in every campaign.

POST/api/v1/leads/bulk/delete

Requires an API key with the write scope.

Up to 1,000 selected leads run inside the request and the job comes back completed (200). More than that is queued: the response is 202 with a pending job; poll Get Job until it is completed.

Deleting a lead is a soft delete that also cancels it in every campaign and removes its queued emails. It cannot be undone for campaign membership: importing the same address again restores the lead but not its place in a campaign. Run Bulk Delete Impact first to see which running campaigns would lose leads.

Body Parameters#

leadIdsstring[]body
Lead IDs, up to 50,000. Send this or filter, not both.
filterobjectbody
Select leads by filter instead. Keys: search, status, tags (comma separated; a lead must carry all of them), provider, interestStatus, labelId. Matches at most 50,000 leads, newest first.

Response#

dataobject

The job. See Get Job for every field.

Show Job object
idstring
Job identifier.
typestring
lead_bulk.
statusstring
completed when the call finished the work (200), pending when it was queued (202).
totalItemsinteger
Leads selected.
resultobject
{ "deleted": 2 } once the job is completed.

Errors#

StatusDescription
401Missing, invalid, revoked or expired API key
403API key does not have the required scope: write
422Neither or both of leadIds and filter were sent

Rate Limit#

  • 100 requests per minute, shared by every bulk call in your workspace. Fixed 60-second window.
  • Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix epoch seconds) and X-RateLimit-Bucket (bulk).
  • A 429 response includes a Retry-After header (seconds until the bucket resets).

For client-side patterns (Retry-After, exponential backoff, monitoring X-RateLimit-Remaining), see Rate Limiting.

Was this page helpful?
View as MarkdownLast updated November 4, 2026