> ## 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.

# Create list

> Create a custom organization-scoped list with no members.

Creates a custom list for the authenticated organization. The Gateway inserts a new row and returns it with `member_count: 0`, `is_default: false`, and null generated-list references. This endpoint does not add members and does not provide an idempotency key or upsert mode.

<ParamField body="name" type="string" required>
  List name. Must contain 1–80 characters. The Gateway trims surrounding whitespace before storing it. Names are not enforced as unique by this route or its database insert.
</ParamField>

<ParamField body="description" type="string">
  Optional description, up to 400 characters. Omit it for `null`; an empty string is stored as `null` after trimming. Send a string when setting it. The current framework can coerce `null` to an empty string; do not use coercion as your client contract.
</ParamField>

The JSON body is an object with only `name` and `description`; unknown top-level fields are stripped by the framework.

## Response schema

`data` is a list object with the fields below. Timestamps are ISO 8601 strings.

| Field                      | Type                        | Nullability and meaning                         |
| -------------------------- | --------------------------- | ----------------------------------------------- |
| `id`                       | string (UUID)               | Never null; use it for stable later references. |
| `name`                     | string                      | Never null.                                     |
| `description`              | string                      | `null` when omitted or blank after trimming.    |
| `is_default`               | boolean                     | Always `false` for a list created here.         |
| `default_key`              | string                      | Always `null` for a list created here.          |
| `source_watch_id`          | string (UUID)               | Always `null` for a list created here.          |
| `member_count`             | integer                     | Always `0` in this response.                    |
| `created_at`, `updated_at` | string (ISO 8601 timestamp) | Never null.                                     |

<ResponseExample>
  ```json 201 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "hot",
      "description": null,
      "is_default": false,
      "default_key": null,
      "source_watch_id": null,
      "member_count": 0,
      "created_at": "2026-09-07T10:00:00.000Z",
      "updated_at": "2026-09-07T10:00:00.000Z"
    }
  }
  ```
</ResponseExample>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --fail-with-body --max-time 30 -X POST "https://api.freshtalent.ai/v1/lists" \
    -H "Authorization: Bearer $FRESHTALENT_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name":"hot","description":"Palantir leavers to contact"}'
  ```

  ```js JavaScript (native fetch) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch("https://api.freshtalent.ai/v1/lists", {
    method: "POST",
    signal: AbortSignal.timeout(30_000),
    headers: {
      Authorization: `Bearer ${process.env.FRESHTALENT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "hot", description: "Palantir leavers to contact" }),
  });
  if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
  const { data: list } = await response.json();
  console.log(list.id);
  ```

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

  payload = json.dumps({"name": "hot", "description": "Palantir leavers to contact"}).encode()
  request = Request(
      "https://api.freshtalent.ai/v1/lists",
      data=payload,
      method="POST",
      headers={
          "Authorization": f"Bearer {os.environ['FRESHTALENT_API_KEY']}",
          "Content-Type": "application/json",
      },
  )
  with urlopen(request, timeout=30) as response:
      list_ = json.load(response)["data"]
  print(list_["id"])
  ```
</RequestExample>

## Errors, side effects, and retry safety

* `400`: request-schema failure, such as a missing name, a name longer than 80 characters, a description longer than 400 characters, or a missing platform-key `X-FreshTalent-Org-Id` UUID. Fix the body/header before retrying.
* `401` (`unauthorized`): provide a valid API key.
* `402` (`payment_required`): restore the organization's entitlement before retrying.
* `429`: back off and retry only after considering whether the first request may have succeeded.
* `5xx`: the outcome may be unknown. This POST is **not idempotent**; a retry can create another list, because the route always inserts and does not enforce name uniqueness. Reconcile with `GET /lists` and use the returned UUIDs before retrying.

A successful `201` has no pagination metadata and no `next` link. Add people separately with [Add list members](/api-reference/lists/add-members).

## Next steps

[Add list members](/api-reference/lists/add-members) or [Get list](/api-reference/lists/get).