# Delete List

`DELETE https://api.getprospect.com/v2/lists/{id}`

Moves a list to Trash, restorable for 90 days, and takes its records out of it; with `with_records=true` the records themselves also move to Trash. Answers a `list_delete` job: 200 with the `done` job when the work ran inline, else 202 with the `running` job and `Location: /v2/jobs/{id}` (poll it after `Retry-After`). One bulk action runs per workspace at a time. Without an `Idempotency-Key`, a retry after the delete answers 404; with one, it answers the same job. Uses 1 unit of the jobs rate limit. Free: costs no credits.

## Authentication

Pass your API key in the `x-api-key` header.

## Path parameters

- `id` (string, required): The list id (24 hex characters). Example: `"66f1a2b3c4d5e6f7a8b9c0d1"`

## Query parameters

- `with_records` (enum, optional, default: "false"): `true` also moves every record of the list to Trash. Allowed values: `true`, `false`.

## Example request

```bash
curl --request DELETE \
  --url https://api.getprospect.com/v2/lists/66f1a2b3c4d5e6f7a8b9c0d1 \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Response 200

Done inline: the `done` job.

```json
{
  "success": true,
  "data": {
    "id": "6703f1c2d4e5f6a7b8c9d0e1",
    "type": "list_delete",
    "status": "done",
    "total": 128,
    "processed": 128,
    "progress_percent": 100,
    "result": {
      "list": true,
      "records_deleted": 0
    },
    "error": null,
    "resource_url": null,
    "created_at": "2026-10-08T12:00:00.000Z",
    "finished_at": "2026-10-08T12:00:00.000Z"
  },
  "metadata": {
    "timestamp": "2026-10-08T12:00:00.000Z"
  }
}
```

## Response 202

Queued: the `running` job; poll `Location`.

```json
{
  "success": true,
  "data": {
    "id": "6703f1c2d4e5f6a7b8c9d0e1",
    "type": "list_delete",
    "status": "running",
    "total": 48210,
    "processed": 0,
    "progress_percent": 0,
    "result": {
      "list": true,
      "records_deleted": 0
    },
    "error": null,
    "resource_url": null,
    "created_at": "2026-10-08T12:00:00.000Z",
    "finished_at": null
  },
  "metadata": {
    "timestamp": "2026-10-08T12:00:00.000Z"
  }
}
```

## Response 400

Invalid query or `Idempotency-Key` (`VALIDATION_ERROR` with `payload.code`).

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "timestamp": "2026-10-08T12:00:00.000Z"
  },
  "errors": [
    {
      "name": "VALIDATION_ERROR",
      "message": "with_records: \"yes\" is not an accepted value. Accepted: true, false",
      "payload": {
        "field": "with_records",
        "code": "value_not_allowed",
        "received_value": "yes",
        "received_type": "string",
        "invalid_values": [
          "yes"
        ],
        "allowed_values": [
          "true",
          "false"
        ],
        "constraints": {
          "isIn": "with_records must be one of the following values: true, false"
        }
      }
    }
  ]
}
```

## Response 401

Missing, unknown or inactive credentials (`UNAUTHORIZED`).

## Response 404

No such list in this workspace (`NOT_FOUND`).

## Response 409

Another bulk action of the workspace is still running (`CONFLICT`, `payload.code: bulk_action_running` with its `job_id`; poll it, then retry); or the `Idempotency-Key` was used for another request (`idempotency_key_reused`), or its first request is still running inline (`idempotency_in_progress`, with `Retry-After`).

```json
{
  "success": false,
  "data": {
    "code": "bulk_action_running",
    "job_id": "6703f1c2d4e5f6a7b8c9d0e1"
  },
  "metadata": {
    "timestamp": "2026-10-08T12:00:00.000Z"
  },
  "errors": [
    {
      "name": "CONFLICT",
      "message": "Another bulk action is still running in this workspace.",
      "payload": {
        "code": "bulk_action_running",
        "job_id": "6703f1c2d4e5f6a7b8c9d0e1"
      }
    }
  ]
}
```

## Response 422

The list holds more than 500,000 records (`LIST_TOO_LARGE`); nothing was changed.

## Response 429

Over the `jobs` rate limit (`RATE_LIMIT`); wait `Retry-After` seconds. Sent only where rate limits are enforced.

## Response 500

Unexpected server error.