> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuco.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Delete Lead List

> Delete a Tuco lead list, keeping or deleting the leads inside it. Bearer-token REST endpoint.

<Warning>
  **The Try it panel runs against production** (`https://app.tuco.ai`) with the key you paste
  into it. There is no sandbox — a request from this page permanently deletes a real list.
</Warning>

<Note>
  A **list** owns leads. `listId` is what you pass to
  [`POST /api/leads`](/api-reference/endpoint/create) to file new leads somewhere specific, and to
  [`POST /api/leads/check-availability`](/api-reference/endpoint/bulk-check-availability) to check a
  whole list at once. These endpoints are how you get a `listId` without opening the dashboard.
</Note>

<Warning>
  The list id goes in the **request body**, not the URL. `DELETE /api/lists` with no body returns
  `400 List ID is required`. Some HTTP clients drop bodies on `DELETE` by default — if you get that
  error with an id you know is correct, that is why.
</Warning>

## Authentication

Pass your workspace API key as a Bearer token, or use a Clerk session token.

```bash theme={null}
Authorization: Bearer tuco_xxxxxxxxxxxxx
```

***

## Request body

<ParamField body="listId" type="string" required>
  The list to delete, from [`GET /api/lists`](/api-reference/endpoint/list-lists).
</ParamField>

<ParamField body="deleteLeads" type="boolean" default="false">
  What happens to the leads inside it.

  | Value | Result |
  | - | - |
  | `false` (default) | The list is removed; its leads stay in the workspace as unassigned. |
  | `true` | The leads are deleted too, along with their activities, messages and conversations. |

  <Warning>
    `deleteLeads: true` is **permanent** and takes the conversation history with it.
  </Warning>
</ParamField>

***

## Example

```bash theme={null}
curl -X DELETE "https://app.tuco.ai/api/lists" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "listId": "6ac3f1a271adb32c88d566f1", "deleteLeads": false }'
```

### Success (`200 OK`)

```json theme={null}
{
  "message": "List deleted successfully",
  "deletedLeads": "leads moved to unassigned"
}
```

With `deleteLeads: true`, `deletedLeads` reads `"all leads deleted"`.

***

## Errors

| Status | When | Body |
| - | - | - |
| `400` | `listId` missing | `{ "error": "List ID is required" }` |
| `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` |
| `404` | No list with that id in your workspace | `{ "error": "List not found" }` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.