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

# Delete Lead

> Delete a single lead from your campaign

<Note>
  **Endpoint Alias**: You can also use `/api/v1/records` instead of `/api/v1/leads`. Both endpoints are functionally identical - use whichever naming convention fits your integration.
</Note>

## Lead Lookup

Leads are identified by `externalId` or `phoneNumber`, not internal IDs. This matches how you created the lead.

<Info>
  **At least one of `phoneNumber` or `externalId` is required.** 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>

## Query Parameters

<ParamField query="campaignId" type="string" required>
  The ID of the campaign the lead belongs to
</ParamField>

<ParamField query="phoneNumber" type="string">
  Phone number in E.164 format (e.g., +15555551234).

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

<ParamField query="externalId" type="string">
  Your CRM's internal ID for this lead.

  **Required if `phoneNumber` is not provided.**
</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="boolean">
      Always `true` if the request succeeded
    </ResponseField>
  </Expandable>
</ResponseField>

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

## Examples

<Tabs>
  <Tab title="By External ID">
    Delete by external CRM reference:

    <RequestExample>
      ```bash cURL theme={null}
      curl -X DELETE "https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads?campaignId=YOUR_CAMPAIGN_ID&externalId=CRM_12345" \
        -H "x-api-key: YOUR_API_KEY"
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch(
        'https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads?campaignId=YOUR_CAMPAIGN_ID&externalId=CRM_12345',
        {
          method: 'DELETE',
          headers: {
            'x-api-key': 'YOUR_API_KEY'
          }
        }
      );

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

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

      response = requests.delete(
          'https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads',
          params={
              'campaignId': 'YOUR_CAMPAIGN_ID',
              'externalId': 'CRM_12345'
          },
          headers={'x-api-key': 'YOUR_API_KEY'}
      )

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

  <Tab title="By Phone Number">
    Delete by phone number:

    <RequestExample>
      ```bash cURL theme={null}
      curl -X DELETE "https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads?campaignId=YOUR_CAMPAIGN_ID&phoneNumber=%2B15555551234" \
        -H "x-api-key: YOUR_API_KEY"
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch(
        'https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads?campaignId=YOUR_CAMPAIGN_ID&phoneNumber=%2B15555551234',
        {
          method: 'DELETE',
          headers: {
            'x-api-key': 'YOUR_API_KEY'
          }
        }
      );

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

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

      response = requests.delete(
          'https://YOUR_DEPLOYMENT.lupitor.com/api/v1/leads',
          params={
              'campaignId': 'YOUR_CAMPAIGN_ID',
              'phoneNumber': '+15555551234'
          },
          headers={'x-api-key': 'YOUR_API_KEY'}
      )

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

<ResponseExample>
  ```json Success Response theme={null}
  {
    "success": true,
    "data": {
      "deleted": true
    },
    "error": null
  }
  ```

  ```json Error Response - Not Found theme={null}
  {
    "success": false,
    "data": null,
    "error": "Lead not found"
  }
  ```

  ```json Error Response - Missing Parameter theme={null}
  {
    "success": false,
    "data": null,
    "error": "At least one of phoneNumber or externalId query parameter is required"
  }
  ```
</ResponseExample>

## Notes

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

<Tip>
  **Need the lead data?** The delete response only confirms deletion—it doesn't return the lead's details. If you need the lead information (metadata, status, etc.), fetch the lead first using `GET /api/v1/leads`, then delete it.
</Tip>

<Warning>
  **URL Encoding**: When passing phone numbers in the URL, remember to URL-encode the `+` sign as `%2B`.
</Warning>

<Info>
  **Access Control**: You can only delete leads that belong to campaigns your API key has access to.
</Info>

## Common Errors

| Error                                                                   | Cause                             | Solution                           |
| ----------------------------------------------------------------------- | --------------------------------- | ---------------------------------- |
| `campaignId query parameter is required`                                | Missing campaignId                | Include campaignId in query string |
| `At least one of phoneNumber or externalId query parameter is required` | Missing both identifiers          | Include phoneNumber or externalId  |
| `Lead not found`                                                        | Lead doesn't exist in campaign    | Verify identifier and campaign     |
| `Invalid or inactive API key`                                           | Wrong API key                     | Check your API key                 |
| `Forbidden`                                                             | API key doesn't have write access | Use an API key with write scope    |