> ## 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.

# Bulk Delete Records

> Delete multiple records in a single request

<Note>
  **Endpoint Alias**: This endpoint is an alias for `/api/v1/leads/bulk-delete`. Both endpoints are functionally identical - use whichever naming convention fits your integration.
</Note>

<Info>
  **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.
</Info>

## Record Lookup

Records are identified by `externalId` or `phoneNumber`, not internal IDs.

<Info>
  **Each record must have at least one of `phoneNumber` or `externalId`.** If both are provided, `externalId` takes priority for the lookup.
</Info>

## Authentication

<ParamField header="x-api-key" type="string" required>
  Your API key with `write` scope
</ParamField>

## Request Body

<ParamField body="campaignId" type="string" required>
  The ID of the campaign these records belong to
</ParamField>

<ParamField body="leads" type="array" required>
  Array of record identifiers to delete (max 1000 per request)

  <Expandable title="Record Identifier Properties">
    <ParamField body="phoneNumber" type="string">
      Phone number in E.164 format.

      **Required if `externalId` is not provided.**
    </ParamField>

    <ParamField body="externalId" type="string">
      Your CRM's internal ID.

      **Required if `phoneNumber` is not provided.**
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="deleted" type="number">
      Number of records successfully deleted
    </ResponseField>

    <ResponseField name="notFound" type="number">
      Number of records that were not found in the campaign
    </ResponseField>

    <ResponseField name="deletedIdentifiers" type="array">
      Array of identifiers for deleted records
    </ResponseField>

    <ResponseField name="notFoundIdentifiers" type="array">
      Array of identifiers that were not found
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if request failed
</ResponseField>

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://YOUR_DEPLOYMENT.lupitor.com/api/v1/records/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" },
        { "phoneNumber": "+15555551234" }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://YOUR_DEPLOYMENT.lupitor.com/api/v1/records/bulk-delete', {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      campaignId: 'YOUR_CAMPAIGN_ID',
      leads: [
        { externalId: 'CRM_001' },
        { externalId: 'CRM_002' },
        { phoneNumber: '+15555551234' }
      ]
    })
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://YOUR_DEPLOYMENT.lupitor.com/api/v1/records/bulk-delete',
      headers={
          'x-api-key': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'campaignId': 'YOUR_CAMPAIGN_ID',
          'leads': [
              {'externalId': 'CRM_001'},
              {'externalId': 'CRM_002'},
              {'phoneNumber': '+15555551234'}
          ]
      }
  )

  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response - All Deleted theme={null}
  {
    "success": true,
    "data": {
      "deleted": 3,
      "notFound": 0,
      "deletedIdentifiers": [
        "CRM_001",
        "CRM_002",
        "+15555551234"
      ],
      "notFoundIdentifiers": []
    },
    "error": null
  }
  ```

  ```json Success Response - Partial Delete theme={null}
  {
    "success": true,
    "data": {
      "deleted": 2,
      "notFound": 1,
      "deletedIdentifiers": [
        "CRM_001",
        "CRM_002"
      ],
      "notFoundIdentifiers": [
        "+15555551234"
      ]
    },
    "error": null
  }
  ```
</ResponseExample>

## Notes

<Warning>
  **Permanent Deletion**: This action cannot be undone. Records will be permanently deleted.
</Warning>

<Tip>
  **Need the record data?** Fetch the records first, then delete them.
</Tip>

<Info>
  For full documentation including best practices, see [Bulk Delete Leads](/api-reference/leads/bulk-delete).
</Info>