> ## Documentation Index > Fetch the complete documentation index at: https://docs.topcalls.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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`. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/leads/bulk-delete openapi: 3.0.3 info: title: TopCalls Voice API description: > TopCalls Voice Gateway API for creating and managing AI-powered phone calls. ## Authentication All API requests require authentication. Include your API key in the `Authorization` header: ``` Authorization: Bearer tc_live_xxxxx ``` ## Rate Limits Direct call creation via `POST /v1/calls` is limited to your account's `max_calls_per_minute` setting (default: 20) per minute. Exceeding it returns `429 Too Many Requests` with a `Retry-After` header. All endpoints are additionally subject to a flat limit of 120 requests per minute per account (all methods). On a `429`, wait for the number of seconds in the `Retry-After` header, then retry the same request. For automated clients, back off progressively on repeated `429`s. Limits are per account and are shared by all API keys. ## Error Format All errors follow RFC 7807 Problem+JSON format: ```json { "type": "https://api.topcalls.ai/errors/insufficient_quota", "title": "Insufficient Quota", "status": 402, "detail": "Not enough remaining call minutes to admit this call" } ``` version: 1.0.0 contact: name: TopCalls Support url: https://topcalls.ai license: name: Proprietary servers: - url: https://api.topcalls.ai description: Production security: [] tags: - name: Calls description: Create and manage phone calls - name: Phone Numbers description: Manage phone numbers and carriers - name: Account description: Account information and usage - name: Webhooks description: Webhook configuration and events - name: Configuration description: Available AI models, voices, and platform capabilities paths: /v1/leads/bulk-delete: post: summary: Bulk delete leads (hybrid sync/async) description: > 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`. requestBody: required: true content: application/json: schema: oneOf: - type: object additionalProperties: false required: - ids properties: ids: type: array minItems: 1 maxItems: 500 items: type: string format: uuid account_id: type: string format: uuid - type: object additionalProperties: false required: - filter properties: filter: type: object additionalProperties: false properties: list_id: type: string format: uuid status: type: string enum: - New - Contacted - Converted - Unsubscribed tag: type: string minLength: 1 maxLength: 64 account_id: type: string format: uuid responses: '200': description: Sync delete completed (count <= 500) content: application/json: schema: type: object required: - kind - deleted - skipped - skipped_payload properties: kind: type: string enum: - sync deleted: type: integer minimum: 0 skipped: type: integer minimum: 0 skipped_payload: type: array items: type: object required: - lead_id - reason properties: lead_id: type: string format: uuid reason: type: string enum: - not_found - cross_account_filtered - constraint_violation '202': description: Async job enqueued (filter mode, count > 500) content: application/json: schema: type: object required: - kind - job_id - status - total_leads - chunks_total properties: kind: type: string enum: - async job_id: type: string format: uuid status: type: string enum: - pending total_leads: type: integer minimum: 1 chunks_total: type: integer minimum: 1 '400': description: Invalid input content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '401': description: Unauthorized content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '403': description: Forbidden content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '413': description: Too many ids (max 500 in ids mode) content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '422': description: Filter resolves to zero rows content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '429': description: Rate limit exceeded content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '500': description: Internal error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - bearerAuth: [] components: schemas: Problem: type: object required: - status - title properties: type: type: string format: uri description: Error type URI title: type: string description: Error title status: type: integer description: HTTP status code detail: type: string description: Human-readable error detail code: type: string description: > Machine-readable error code for programmatic handling. Present on errors that carry a stable identifier (e.g. `PROMPT_SAFETY_FRAUD`, `job_not_found`, `too_many_ids`, `no_matches`). Distinct from the per-field `errors[].code` used for validation failures. Scenario- specific — see each endpoint's response examples for the exact value. instance: type: string format: uuid description: Request instance ID errors: type: array description: Validation errors (for 400 responses) items: type: object properties: path: type: string description: Field path (e.g., "phone_number", "metadata.from_number") message: type: string description: Error message code: type: string description: Error code (e.g., "invalid_string", "custom") details: type: string description: Additional error details (for provider errors) securitySchemes: bearerAuth: type: http scheme: bearer description: | Use `Authorization: Bearer tc_live_xxxxx` ````