# Delete a lead or remove it from a campaign

`DELETE https://api.versionseven.ai/v1/leads/{lead_id}`

With the `campaign_id` query parameter, removes the lead from that campaign and leaves its record unchanged; a lead that isn't enrolled there answers `404 LEAD_NOT_IN_CAMPAIGN`.

Without `campaign_id`, deletes the lead itself. Its personal and company data is erased in place and it disappears from every read, while an anonymised row remains as the record of the activity that happened.

> **Warning:** Omitting `campaign_id` deletes the lead, not just an enrolment, and the erasure can't be undone. To take a lead out of one campaign, always send `campaign_id`.

- Required scope: `leads:write`

## Request

**cURL**

```bash
curl -X DELETE "https://api.versionseven.ai/v1/leads/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer $VICTORIA_API_KEY"
```

**Node.js**

```javascript
const response = await fetch("https://api.versionseven.ai/v1/leads/a1b2c3d4-e5f6-7890-abcd-ef1234567890", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.VICTORIA_API_KEY}`,
  },
});

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

**Python**

```python
import os

import requests

response = requests.delete(
    "https://api.versionseven.ai/v1/leads/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    headers={
        "Authorization": f"Bearer {os.environ['VICTORIA_API_KEY']}",
    },
)
data = response.json()
```

## Headers

- `Authorization` (string, required): `Bearer` followed by a space and your API key, for example `Bearer vk_…`.

## Path parameters

- `lead_id` (string · uuid, required): ID of the lead.

## Query parameters

- `campaign_id` (string · uuid or null, optional): UUID of the campaign to remove the lead from. Omit to delete the lead itself

## Response

### `200`

```json
{
  "message": "string",
  "lead_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
  "success": true
}
```

- `message` (string, required): Success message
- `lead_id` (string, required): ID of the deleted or removed lead
- `campaign_id` (string or null, optional): ID of the campaign the lead was removed from; null when the lead itself was deleted
- `success` (boolean, optional, default `true`)

## Errors

Errors share one JSON body: `success`, `error`, `message`, optional `details`, and `request_id`. For example:

```json
{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "Invalid or inactive API key",
  "request_id": "734d11a1-54d4-414c-9e8d-4e1ada977db4"
}
```

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | The request didn't match the endpoint's schema: a missing or malformed field, a bad query parameter, or a value out of range. `details.errors` lists each failing field with its `field`, `message` and `type`. |
| 401 | `UNAUTHORIZED` | The `Authorization` header is missing or malformed, or the API key is unknown or has been deactivated. |
| 401 | `API_KEY_EXPIRED` | The API key is past its expiry date. Create a new key in the Victoria AI app. |
| 403 | `INSUFFICIENT_SCOPE` | The API key doesn't have the scope this endpoint requires, such as `leads:write`. |
| 403 | `ORGANIZATION_DEACTIVATED` | The organization that owns this API key has been deactivated. |
| 404 | `LEAD_NOT_FOUND` | No lead with this ID exists in your organization. |
| 404 | `LEAD_NOT_IN_CAMPAIGN` | The lead isn't enrolled in the campaign given by `campaign_id`. |
| 404 | `NOT_FOUND` | No endpoint matches the path. A resource ID in the path that isn't a valid UUID also answers `NOT_FOUND`. |
| 429 | `RATE_LIMITED` | Too many requests for this API key: more than 100 a minute to one endpoint, or 600 a minute in total. Retry after the number of seconds in the `Retry-After` header. See [Rate limits](https://docs.versionseven.ai/guides/rate-limits). |
| 500 | `INTERNAL_ERROR` | Something failed on our side. The response never includes internal details; quote its `request_id` when you contact support. |
| 503 | `UPSTREAM_TIMEOUT` | A service the API depends on timed out. The request is safe to retry. |
| 503 | `AUTH_UNAVAILABLE` | The API key couldn't be checked because the authentication service was unavailable. The request is safe to retry. |

## Response headers

| Header | Description |
| --- | --- |
| `X-Request-ID` | Correlation ID for the request, also returned as `request_id` in error bodies. Send your own `X-Request-ID`, up to 128 letters, digits, `.`, `_`, `:` or `-`, and it's used instead. |
| `RateLimit-Limit` | Requests allowed to this endpoint per minute. |
| `RateLimit-Remaining` | Requests you can still send to this endpoint right now. |
| `RateLimit-Reset` | Seconds until the endpoint's full limit is available again. |
| `Retry-After` | On a `429`: seconds to wait before retrying. |