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

# Build and manage lists

> Group companies, deals, and people into lists to work with them in bulk.

Lists are the spreadsheet-like surface for working with resources in bulk. Use them to assemble a screening universe, track a themed set of targets, or enrich and analyze many records at once.

## Create a list

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.metal.ai/v1/lists \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Industrial automation — Q3 screen" }'
```

The response returns the new list under `data`, including its `id`. Use that `id` to add and read entries.

## Add entries

Entries are the resources a list contains. Add companies, deals, or people by referencing their `id`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.metal.ai/v1/lists/665f1c2a9b1e4a0012a3b4c5/entries \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "entries": [{ "companyId": "665f1c2a9b1e4a0012a3b4c6" }] }'
```

## Read entries

Fetch the entries in a list to read their current values, including any enriched columns. Entries are paginated like other collections.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.metal.ai/v1/lists/665f1c2a9b1e4a0012a3b4c5/entries?limit=100" \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY"
```

<Note>
  Lists can hold many entries. Page through them with `limit` and `lt` as described in [pagination](/guides/pagination).
</Note>

## Manage the list

| Action           | Endpoint                      |
| ---------------- | ----------------------------- |
| List all lists   | `GET /v1/lists`               |
| Get one list     | `GET /v1/lists/{id}`          |
| Rename or update | `PUT /v1/lists/{id}`          |
| Delete           | `DELETE /v1/lists/{id}`       |
| Read entries     | `GET /v1/lists/{id}/entries`  |
| Add entries      | `POST /v1/lists/{id}/entries` |

## A common workflow

<Steps>
  <Step title="Assemble the universe">
    [Search](/guides/search) for relevant companies and add the matches as entries.
  </Step>

  <Step title="Enrich in bulk">
    Enrich at the list level so every entry gets firmographics and financials. See [enrich companies](/guides/enrich-companies).
  </Step>

  <Step title="Screen and export">
    Read entries to rank, filter, or push results back to your own system.
  </Step>
</Steps>

<Tip>
  Lists pair naturally with [workflows](/guides/automate-workflows): run a workflow over a list to screen an entire set of targets in one pass.
</Tip>