Bulk delete leads (hybrid sync/async)

curl --request POST \
  --url https://api.topcalls.ai/v1/leads/bulk-delete \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

{
  "kind": "sync",
  "deleted": 1,
  "skipped": 1,
  "skipped_payload": [
    {
      "lead_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ]
}

Leads

Bulk delete leads (hybrid sync/async)

Delete leads in bulk. Polymorphic body: pass `ids: uuid[]` (max 500, sync only) OR `filter: {list_id?, status?, tag?}` (any size; gateway recounts then auto-routes sync if <=500 / async via job table if >500). Sync mode (200) returns `{kind:'sync', deleted, skipped, skipped_payload}`. Async mode (202) returns `{kind:'async', job_id, status:'pending', total_leads, chunks_total}` — a background worker drains the job in 1000-row chunks; client polls or watches notifications for terminal status. Hard delete: `lead_list_assignments` cascades automatically; `calls.lead_id` becomes NULL via existing FK. There is no undo. Requires scope: `leads:write`.

POST

leads

bulk-delete

curl --request POST \
  --url https://api.topcalls.ai/v1/leads/bulk-delete \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

{
  "kind": "sync",
  "deleted": 1,
  "skipped": 1,
  "skipped_payload": [
    {
      "lead_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ]
}

Authorizations

Authorization

string

header

required

Use Authorization: Bearer tc_live_xxxxx

Body

application/json

Option 1
Option 2

ids

string<uuid>[]

required

Required array length: 1 - 500 elements

account_id

string<uuid>

Response

Sync delete completed (count <= 500)

kind

enum<string>

required

Available options:

sync

deleted

integer

required

Required range: x >= 0

skipped

integer

required

Required range: x >= 0

skipped_payload

object[]

required

Show child attributes

Bulk import leads

List campaigns