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

# Get list

> Retrieve list metadata and every membership in one response.

Returns one list and all of its memberships for the authenticated organization. The path value is trimmed and resolves either an exact UUID or a case-insensitive list name. If a name matches more than one list, the Gateway chooses the most recently updated match, so use the UUID for stable references.

<ParamField path="id" type="string" required>
  List UUID or case-insensitive name. The value must not be empty. UUIDs are the stable choice when names can change or collide.
</ParamField>

This endpoint has no pagination parameters. `data.members` contains every member, ordered by `updated_at` descending. There is no `meta.next`; for the members-only route, use `GET /lists/:id/members`, which likewise returns all members with `meta.count`.

## Response schema

`data` contains the list fields plus `members`:

| Field                      | Type                        | Nullability and meaning              |
| -------------------------- | --------------------------- | ------------------------------------ |
| `id`                       | string (UUID)               | Never null.                          |
| `name`                     | string                      | Never null.                          |
| `description`              | string                      | Nullable.                            |
| `is_default`               | boolean                     | Whether the list is Gateway-managed. |
| `default_key`              | string                      | Nullable.                            |
| `source_watch_id`          | string (UUID)               | Nullable.                            |
| `member_count`             | integer                     | Count of memberships.                |
| `created_at`, `updated_at` | string (ISO 8601 timestamp) | Never null.                          |
| `members`                  | object\[]                   | Never null; can be empty.            |

Each member object is:

| Field                                                                      | Type                        | Nullability and meaning                                                     |
| -------------------------------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------- |
| `id`, `list_id`                                                            | string (UUID)               | Never null.                                                                 |
| `person_linkedin_url`                                                      | string                      | Never null; the membership upsert key.                                      |
| `person_slug`, `person_full_name`, `person_headline`, `person_picture_url` | string                      | Nullable enrichment fields.                                                 |
| `stage`                                                                    | string enum                 | One of `to-contact`, `contacted`, `responded`, `passed`.                    |
| `notes`                                                                    | string                      | Never null in API responses; an unset database value is normalized to `""`. |
| `added_at`, `updated_at`                                                   | string (ISO 8601 timestamp) | Never null.                                                                 |

<ResponseExample>
  ```json 200 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": 1,
      "created_at": "2026-09-07T10:00:00.000Z",
      "updated_at": "2026-09-07T10:00:00.000Z",
      "members": [
        {
          "id": "8c5f6a6b-5cb7-4e3f-a1fd-9aabf2d2c6e0",
          "list_id": "550e8400-e29b-41d4-a716-446655440000",
          "person_linkedin_url": "https://www.linkedin.com/in/derek-morrow",
          "person_slug": "derek-morrow",
          "person_full_name": "Derek Morrow",
          "person_headline": null,
          "person_picture_url": null,
          "stage": "to-contact",
          "notes": "",
          "added_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 "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 listName = encodeURIComponent("hot");
  const response = await fetch(`https://api.freshtalent.ai/v1/lists/${listName}`, {
    signal: AbortSignal.timeout(30_000), headers: { Authorization: `Bearer ${process.env.FRESHTALENT_API_KEY}` },
  });
  if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
  const { data } = await response.json();
  for (const member of data.members) console.log(member.person_slug, member.stage);
  ```

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

  request = Request(
      "https://api.freshtalent.ai/v1/lists/" + quote("hot", safe=""),
      headers={"Authorization": f"Bearer {os.environ['FRESHTALENT_API_KEY']}"},
  )
  with urlopen(request, timeout=30) as response:
      data = json.load(response)["data"]
  print([(m["person_slug"], m["stage"]) for m in data["members"]])
  ```
</RequestExample>

## Errors and recovery

* `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 the organization's entitlement.
* `404` (`not_found`): the UUID/name is not visible in this organization; check the identifier with [List lists](/api-reference/lists/list).
* `429` or `5xx`: retry with backoff. A successful read is safe to repeat.

## Related

| Method   | Path                               | Purpose                                                  |
| -------- | ---------------------------------- | -------------------------------------------------------- |
| `GET`    | `/lists/:id/members`               | Return memberships only, with `meta.count`.              |
| `POST`   | `/lists/:id/members`               | [Add list members](/api-reference/lists/add-members)     |
| `PATCH`  | `/lists/:id/members/:membershipId` | [Update list member](/api-reference/lists/update-member) |
| `DELETE` | `/lists/:id`                       | [Delete list](/api-reference/lists/delete)               |
| `DELETE` | `/lists/:id/members/:membershipId` | Remove one member; returns `204`.                        |

`:membershipId` can be a membership UUID or a person slug when using the member routes.

**Next:** [Add list members](/api-reference/lists/add-members).