# Lists

> Keep people and companies in lists for campaigns and exports, or upload your own from a CSV.

Every section below does the same job: in the dashboard (Guide), from your code (API) or through an AI assistant (MCP).

## Guide — In the dashboard

Source: /docs/leads/lists

Lists hold the people or companies you want to work with together: send them a campaign, export them, or upload your own contacts from a CSV.

<DemoFrame guide="leads-lists" to="/identify/{workspace}?tab=lists" />

1. **Leads → Lists → + New list**, or **Upload CSV**.
2. **Add leads** from the table: tick them → **Add to list**.
3. **Open a list** to see who is in it, or download it as a CSV.

### Every control on this screen [#every-control-on-this-screen]

Every button, field and switch, with what it does.

<ScreenControls screens={["leads-lists", "leads-upload-csv", "list-legacy"]} />


---

## API — From your code

Source: /docs/leads/lists/api

Authenticated with `?privateKey=YOUR_KEY` (see [Authentication](/docs/authentication)).

<Endpoints ops={["GET /admin/lists", "POST /admin/lists", "GET /admin/lists/{id}", "DELETE /admin/lists/{id}", "DELETE /admin/lists/{id}/items", "POST /admin/lists/export-csv/{listId}", "PUT /v3/lists/{listId}/name"]} />

<ApiPlayground
  ops={["GET /admin/lists", "POST /admin/lists", "GET /admin/lists/{id}", "DELETE /admin/lists/{id}", "DELETE /admin/lists/{id}/items", "POST /admin/lists/export-csv/{listId}", "PUT /v3/lists/{listId}/name"]}
  method="get"
  path="/admin/lists"
  tool="list_lists"
  args={`{
  "websiteId": "64b7f0a1c2d3e4f5a6b7c8d9",
  "listType": "contact"
}`}
/>

### Use case: Create a list and export it [#use-case-create-a-list-and-export-it]

`POST /admin/lists?listType=contact` with `{ "websiteId": …, "name": "Q4 founders" }`, then `POST /admin/lists/export-csv/{listId}?listType=contact` — the file is emailed to you.


---

## MCP — AI agents

Source: /docs/leads/lists/mcp

Connect the [MCP server](/docs/mcp#quickstart), then just ask.

<Tools names={["list_lists", "create_list", "get_list", "delete_list", "remove_list_items", "export_list_csv", "rename_list"]} />

### Use case [#use-case]

> Make a list called “Q4 founders”.

<McpToolCall name="create_list">

```json
{
  "websiteId": "64b7f0a1c2d3e4f5a6b7c8d9",
  "listType": "contact",
  "name": "Q4 founders"
}
```

</McpToolCall>