Skip to main content
POST
/
api
/
v1
/
leads
/
bulk-delete
curl -X POST https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads/bulk-delete \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "YOUR_CAMPAIGN_ID",
    "leads": [
      { "externalId": "CRM_001" },
      { "externalId": "CRM_002" },
      { "externalId": "CRM_003" }
    ]
  }'

{
  "success": true,
  "data": {
    "deleted": 3,
    "notFound": 0,
    "deletedIdentifiers": [
      "CRM_001",
      "CRM_002",
      "CRM_003"
    ],
    "notFoundIdentifiers": []
  },
  "error": null
}

Documentation Index

Fetch the complete documentation index at: https://lupitor-docs.com/llms.txt

Use this file to discover all available pages before exploring further.

Endpoint Alias: You can also use /api/v1/records/bulk-delete instead of /api/v1/leads/bulk-delete. Both endpoints are functionally identical - use whichever naming convention fits your integration.
Why POST? This endpoint uses POST instead of DELETE because DELETE requests with a body are not universally supported by all HTTP clients and proxies.

​
Lead Lookup

Leads are identified by externalId or phoneNumber, not internal IDs. Each entry in the leads array must have at least one identifier.
Each lead must have at least one of phoneNumber or externalId. If both are provided, externalId takes priority for the lookup.

​
Authentication

​
x-api-key
string
required
Your API key with write scope

​
Request Body

​
campaignId
string
required
The ID of the campaign these leads belong to
​
leads
array
required
Array of lead identifiers to delete (max 1000 per request)

​
Response

​
success
boolean
Whether the request was successful
​
data
object
​
error
string | null
Error message if request failed

​
Examples

Delete multiple leads by external CRM references:
curl -X POST https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads/bulk-delete \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "YOUR_CAMPAIGN_ID",
    "leads": [
      { "externalId": "CRM_001" },
      { "externalId": "CRM_002" },
      { "externalId": "CRM_003" }
    ]
  }'

{
  "success": true,
  "data": {
    "deleted": 3,
    "notFound": 0,
    "deletedIdentifiers": [
      "CRM_001",
      "CRM_002",
      "CRM_003"
    ],
    "notFoundIdentifiers": []
  },
  "error": null
}

​
Limits

Maximum Size: You can delete up to 1000 leads per bulk request. For larger deletions, make multiple requests.

​
Partial Success Handling

The bulk delete endpoint handles missing leads gracefully:
  1. Validates campaign access - Ensures API key has write access to the specified campaign
  2. Processes each lead - Looks up by externalId first, then phoneNumber
  3. Tracks results - Records which leads were deleted vs not found
  4. Returns details - Provides identifiers for both outcomes
No Partial Rollback: If some leads are not found, the ones that exist will still be deleted. The operation does not fail entirely.
This makes bulk delete safe to retry - if a previous request partially succeeded, you can safely send the same request again without issues.

​
Notes

Permanent Deletion: This action cannot be undone. Leads will be permanently deleted.
Need the lead data? The delete response only returns identifiers and counts—not the full lead details. If you need lead information (metadata, status, etc.) before deletion, fetch the leads first using GET /api/v1/leads, then delete them.
Campaign Scope: All leads must belong to the specified campaign. Leads from other campaigns will appear in notFoundIdentifiers.

​
Common Errors

ErrorCauseSolution
campaignId is requiredMissing campaignIdInclude campaignId in request body
leads array is requiredMissing or invalid leadsInclude leads array in request body
leads array cannot be emptyEmpty leads arrayAdd at least one lead to the array
Maximum 1000 leads per bulk delete requestToo many leadsSplit into multiple requests
leads[N]: At least one of phoneNumber or externalId is requiredLead missing both identifiersEach lead needs phoneNumber or externalId
Invalid or inactive API keyWrong API keyCheck your API key
ForbiddenAPI key doesn’t have campaign accessVerify campaignId and API key scope

​
Best Practices

  • Use 100-500 leads per request for optimal performance
  • Don’t max out at 1000 unless necessary
  • Monitor response times and adjust
  • Use externalId when available - it’s more specific
  • Use phoneNumber as fallback for leads without external IDs
  • Don’t mix identifiers for the same lead across requests
  • Check the deleted vs notFound counts
  • Log notFoundIdentifiers for investigation
  • Retry failed requests with exponential backoff
  • Consider archiving leads instead of deleting if audit trail is important
  • Use bulk delete for cleaning up test data
  • Run bulk deletes during off-peak hours for large datasets