> Reverse Contact API documentation. This is the Markdown copy of https://docs.reversecontact.com/endpoints/list-delete
> Every page is listed at https://docs.reversecontact.com/llms.txt, every endpoint with its credit cost and status at https://docs.reversecontact.com/catalog.json

# Delete a List

> Permanently delete a List, its members, stored data and Pending Intake for free, and handle LIST_BUSY while imports or searches still run.

- Endpoint: `DELETE https://api.reversecontact.com/v2/lists/:listId`
- Credits: Free.
- Answer: synchronous.
- Available in: REST API, MCP tool `delete_list`, TypeScript and Python SDKs.
- Last verified: 2026-11-04

## Introduction

The Delete a List endpoint deletes a List for good: its members, the data the List stored for them and its [Pending Intake](https://docs.reversecontact.com/guides/lists#pending-intake). Export the List first with [Export a List](https://docs.reversecontact.com/endpoints/list-export) if you need to keep a copy. To take some members out and keep the List, use [Remove members](https://docs.reversecontact.com/endpoints/list-members-remove).

Deleting a List is **free** (0 credits). While an import is queued, running or paused on the List, while the lines of a cancelled import still wait for their result, or while a Search of the app is still adding people to it, the request returns `409 LIST_BUSY`: wait for the import to end, or [cancel it](https://docs.reversecontact.com/endpoints/list-operation-cancel) and wait for its last results, then delete again.

The API key needs the `lists` permission (see [API key management](https://docs.reversecontact.com/guides/api-key-management)).

## Authorization

| Name     | Type   | Required | Description                                                                                         |
| -------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| `apikey` | string | Yes      | Your API key from the developer dashboard. Pass it via `Authorization: Bearer YOUR_API_KEY` header. |

## Request

The route is `DELETE /v2/lists/:listId`.

### Path parameters

| Name     | Type   | Required | Description             |
| -------- | ------ | -------- | ----------------------- |
| `listId` | string | Yes      | Id (UUID) of the List to delete |

The request has no body.

## Response structure

| Field     | Type    | Description                                      |
| --------- | ------- | ------------------------------------------------ |
| `success` | boolean | `true` if the List was deleted                   |
| `error`   | `null`  | Always `null` on success                         |

**data** (ListDeleted): Deletion acknowledgement

| Field     | Type    | Description  |
| --------- | ------- | ------------ |
| `deleted` | boolean | Always `true` |

`quotas` and `metadata` are the blocks of every V2 response: see [Usage](https://docs.reversecontact.com/endpoints/usage#response-structure).

## Errors

| Status | Code             | Meaning                                                  |
| ------ | ---------------- | -------------------------------------------------------- |
| `404`  | `LIST_NOT_FOUND` | No List with this id in your workspace                   |
| `404`  | `LISTS_NOT_ACTIVATED` | The workspace has never had a List                  |
| `409`  | `LIST_BUSY`      | An operation is queued, running or paused on the List, or its last results are still on their way |

## Code examples

**Code Examples**

```bash [cURL]
curl -X DELETE https://api.reversecontact.com/v2/lists/3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40 \
  -H "Authorization: Bearer YOUR_API_KEY"
```
```javascript [JavaScript]
const listId = "3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40";
const response = await fetch(`https://api.reversecontact.com/v2/lists/${listId}`, {
  method: "DELETE",
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});

console.log("Deleted:", (await response.json()).data.deleted);
```
```python [Python]
import requests

list_id = "3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40"
response = requests.delete(
    f"https://api.reversecontact.com/v2/lists/{list_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

print("Deleted:", response.json()["data"]["deleted"])
```

## Example response

**Example Response**

```json [200 - Success]
{
  "success": true,
  "data": {
    "deleted": true
  },
  "error": null,
  "quotas": {
    "creditsConsumed": 0,
    "workspace": {
      "id": "ws_abc123",
      "credits": { "total": 10000, "used": 4521, "left": 5479 }
    }
  },
  "metadata": {
    "requestId": "929ada6c-7ea9-4808-a45f-71480493965e",
    "executionTimeMs": 61
  }
}
```