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

# Lists

> Curated sets of companies, people, or investors

Lists are curated sets of companies, people, or investors you want to track and pull on demand. Build a list once — in the Specter app or via the API — then read its members' full, current records through a single call, and maintain it programmatically.

## What you can do

* Create and name a list, add or remove members, and delete it.
* Pull the full current records for everything on a list in one call.
* Keep lists in sync with your own systems (CRM, warehouse) without touching the app.

## Sharing a list with the API

A list is reachable from the API when it is created by the API, explicitly shared to the API (the "Share to API" toggle on the list in the app), or a global list curated by Specter. A list shared only within your team is not reachable, and lists that aren't shared won't appear in the API.

## Endpoints

Each list type — companies, people, investors — exposes the same six operations.

### Company lists

| Method   | Endpoint                                                                                      | Returns                                           |
| -------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `GET`    | [Get all company lists](/api-reference/company-lists/get-all-company-lists)                   | Your company lists and their sizes                |
| `POST`   | [Create a new company list](/api-reference/company-lists/create-a-new-company-list)           | The new list                                      |
| `GET`    | [Get specific company list info](/api-reference/company-lists/get-specific-company-list-info) | A list's metadata and member company IDs          |
| `PATCH`  | [Modify a company list](/api-reference/company-lists/modify-a-company-list)                   | The updated list                                  |
| `DELETE` | [Delete a company list](/api-reference/company-lists/delete-a-company-list)                   | Removes the list (irreversible)                   |
| `GET`    | [Get company list results](/api-reference/company-lists/get-company-list-results)             | The full current records for the list's companies |

### People lists

| Method   | Endpoint                                                                                   | Returns                                        |
| -------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------- |
| `GET`    | [Get all people lists](/api-reference/people-lists/get-all-people-lists)                   | Your people lists and their sizes              |
| `POST`   | [Create a new people list](/api-reference/people-lists/create-a-new-people-list)           | The new list                                   |
| `GET`    | [Get specific people list info](/api-reference/people-lists/get-specific-people-list-info) | A list's metadata and member person IDs        |
| `PATCH`  | [Modify a people list](/api-reference/people-lists/modify-a-people-list)                   | The updated list                               |
| `DELETE` | [Delete a people list](/api-reference/people-lists/delete-a-people-list)                   | Removes the list (irreversible)                |
| `GET`    | [Get people list results](/api-reference/people-lists/get-people-list-results)             | The full current records for the list's people |

### Investor lists

| Method   | Endpoint                                                                                         | Returns                                           |
| -------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| `GET`    | [Get all investor lists](/api-reference/investor-lists/get-all-investor-lists)                   | Your investor lists and their sizes               |
| `POST`   | [Create a new investor list](/api-reference/investor-lists/create-a-new-investor-list)           | The new list                                      |
| `GET`    | [Get specific investor list info](/api-reference/investor-lists/get-specific-investor-list-info) | A list's metadata and member investor IDs         |
| `PATCH`  | [Modify an investor list](/api-reference/investor-lists/modify-an-investor-list)                 | The updated list                                  |
| `DELETE` | [Delete an investor list](/api-reference/investor-lists/delete-an-investor-list)                 | Removes the list (irreversible)                   |
| `GET`    | [Get investor list results](/api-reference/investor-lists/get-investor-list-results)             | The full current records for the list's investors |

## How to use the API

Get started analysing a set of companies:

1. **Create or pick a list** — build it in the app, or create one with [Create a new company list](/api-reference/company-lists/create-a-new-company-list). List names must be unique.
2. **Make sure it's shared** — created via the API, or "Share to API" on in the app.
3. **Find it** — [Get all company lists](/api-reference/company-lists/get-all-company-lists) to get its `listId` and size.
4. **Pull the records** — [Get company list results](/api-reference/company-lists/get-company-list-results) returns the full current profile for every company on the list, paginated.
5. **Maintain it** — [Modify a company list](/api-reference/company-lists/modify-a-company-list) to add or remove members; [Delete a company list](/api-reference/company-lists/delete-a-company-list) when done.

**Chain into the rest of the API.** List results (and the "list info" member IDs) give you company, person, or investor IDs — follow them to [Get company by ID](/api-reference/companies/get-company-by-id), [Get person info by ID](/api-reference/people/get-person-info-by-id), or [Get investor by ID](/api-reference/investors/get-investor-by-id) for deeper detail.

## Good to know

* A list must be created by the API, explicitly shared to the API via "Share to API", or a global list curated by Specter to be reachable. Lists shared only within your team are not accessible from the API.
* List names must be unique (this rule applies to lists, not saved searches).
* Results are paginated; the record shape matches the underlying product object (company / person / investor).
* Deleting a list is irreversible.