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

# Delete list

> Permanently delete a custom list and its memberships.

Deletes one custom list for the authenticated organization. The database foreign key cascades to `list_memberships`, so all memberships in the list are deleted with it. This does not delete the underlying people or any membership those people have on a Target or another list.

If a person was visible to Monitoring only through this list, deleting the list removes that list-based tracking membership. A Target membership continues to be tracked independently.

<ParamField path="id" type="string" required>
  List UUID or case-insensitive name. Use the UUID to avoid ambiguity when names collide.
</ParamField>

## Response

`204 No Content` with an empty body. There is no response JSON, pagination metadata, or `next` link.

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --fail-with-body --max-time 30 -i -X DELETE "https://api.freshtalent.ai/v1/lists/hot" \
    -H "Authorization: Bearer $FRESHTALENT_API_KEY"
  ```

  ```js JavaScript (native fetch) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch("https://api.freshtalent.ai/v1/lists/hot", {
    method: "DELETE",
    signal: AbortSignal.timeout(30_000), headers: { Authorization: `Bearer ${process.env.FRESHTALENT_API_KEY}` },
  });
  if (!response.ok && response.status !== 404) {
    throw new Error(`${response.status}: ${await response.text()}`);
  }
  console.log(response.status === 204 ? "deleted" : "already absent");
  ```

  ```python Python (stdlib) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  from urllib.error import HTTPError
  from urllib.request import Request, urlopen

  request = Request(
      "https://api.freshtalent.ai/v1/lists/hot",
      method="DELETE",
      headers={"Authorization": f"Bearer {os.environ['FRESHTALENT_API_KEY']}"},
  )
  try:
      with urlopen(request, timeout=30) as response:
          print(response.status)  # 204
  except HTTPError as error:
      if error.code != 404:
          raise
      print("already absent")
  ```
</RequestExample>

## Errors and retry safety

* `400` (`invalid_request`): when using the platform API key, provide a valid `X-FreshTalent-Org-Id` UUID.
* `401` (`unauthorized`): provide a valid API key.
* `402` (`payment_required`): restore entitlement.
* `403` (`forbidden`): the list is Gateway-managed (`is_default: true`) and cannot be deleted.
* `404` (`not_found`): no matching list exists in the organization.
* `429` or `5xx`: the outcome can be unknown. Reconcile with [List lists](/api-reference/lists/list) before retrying. Once deletion has succeeded, a repeat returns `404`, so clients that want delete-if-present semantics can treat a confirmed `404` as already complete.

Deletion is irreversible for the list and its memberships. Do not retry after an unknown response until you have checked whether the list still exists.

## Next steps

[Get list](/api-reference/lists/get) before deletion to capture any data you need, or [List lists](/api-reference/lists/list) to verify absence afterward.