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

# Build lists

> Keep people in lists and folders, add your own rows, and page through them.

Lists hold the people you work with, and folders keep the lists in order. Every list and folder call is free.

## Create a list

```bash theme={null}
curl https://api.outbound.dev/v1/lists \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Portugal freight ops"}'
```

```json theme={null}
{
  "id": "6a1f0c2b9d4e8a7f3c5b2e20",
  "name": "Portugal freight ops",
  "type": "people",
  "rowCount": 0,
  "createdAt": "2026-11-14T10:05:00.000Z"
}
```

A list holds people unless you send `"type": "company"`, and its kind cannot change later. No two lists of an organization share a name: a name in use answers `409` with `list_name_taken`.

## Add your own rows

`POST /v1/lists/{listId}/rows` adds up to 500 people from what you know about them. Each row needs at least one of `email`, `linkedinUrl`, `firstName` and `lastName`:

```bash theme={null}
curl https://api.outbound.dev/v1/lists/6a1f0c2b9d4e8a7f3c5b2e20/rows \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows": [{"firstName": "Ana", "lastName": "Costa", "email": "ana.costa@example.com", "companyName": "Northwind Freight"}, {"linkedinUrl": "https://www.linkedin.com/in/rui-almeida", "jobTitle": "Fleet Manager"}]}'
```

```json theme={null}
{ "addedCount": 2, "personIds": ["6a1f0c2b9d4e8a7f3c5b2e22", "6a1f0c2b9d4e8a7f3c5b2e23"] }
```

* **Nothing is looked up.** An email address is kept as sent, unchecked.
* **Every row becomes a new person**, even one already in your workspace. Sending the same call twice adds everyone twice.
* **Only people lists take rows.** A company list answers `422` with `people_list_required`.

## Add people already in your workspace

To put the same people in another list, send their ids: the `personIds` an upload answered with, or the `id` of their row in another list. Up to 5,000 a call:

```bash theme={null}
curl https://api.outbound.dev/v1/lists/6a1f0c2b9d4e8a7f3c5b2e30/people \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"personIds": ["6a1f0c2b9d4e8a7f3c5b2e22", "6a1f0c2b9d4e8a7f3c5b2e23"]}'
```

```json theme={null}
{ "submittedCount": 2, "addedCount": 1 }
```

People already in the list are skipped, so sending the call again adds nobody twice. `DELETE /v1/lists/{listId}/people` with the same body takes people out of a list: they stay in your workspace and in their other lists.

## Read a list's rows

`GET /v1/lists/{listId}/rows` answers one page of rows, up to 1,000 at a time, in the order `sortBy` and `sortOrder` ask for:

```bash theme={null}
curl "https://api.outbound.dev/v1/lists/6a1f0c2b9d4e8a7f3c5b2e20/rows?pageSize=100&sortBy=lastName&sortOrder=asc" \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

Each row carries the person's name, title, company, emails and phones, the lists they are in, and `columnValues`: the values of the list's own columns, by column id. For the next page, send `pagination.nextCursor` as `cursor` with the same sort and filters. See [Pagination](https://docs.outbound.dev/pagination.md).

### Filter the rows

`filters` is a JSON object in which a row must match every key, and any of a key's values. Text keys such as `title`, `companyName` or `country` take an array of values, or `include` and `exclude` arrays:

```bash theme={null}
curl -G https://api.outbound.dev/v1/lists/6a1f0c2b9d4e8a7f3c5b2e20/rows \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  --data-urlencode 'filters={"companyName": ["northwind"], "enrichedEmail": {"include": ["enriched"]}}'
```

Values for `level`, `dept`, `industryName` and `country` are the people search's own, from `GET /v1/people/filters`. A key the list's kind does not take, or a value of the wrong shape, answers `422` with `invalid_row_filters`. Every key is in [List a list's rows](https://docs.outbound.dev/api-reference/lists/list-a-lists-rows.md).

## Keep lists in folders

```bash theme={null}
curl https://api.outbound.dev/v1/folders \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Iberia"}'
```

```json theme={null}
{ "id": "6a1f0c2b9d4e8a7f3c5b2e21", "name": "Iberia", "type": "people" }
```

Move a list into it by the folder's id, or by its name with `folderName`, which creates the folder when there is none:

```bash theme={null}
curl -X PATCH https://api.outbound.dev/v1/lists/6a1f0c2b9d4e8a7f3c5b2e20 \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folderId": "6a1f0c2b9d4e8a7f3c5b2e21"}'
```

* **A folder holds one kind of list.** A people list goes only into a folder for people lists: any other folder answers `404` with `folder_not_found`.
* **`"folderId": null`** takes a list out of every folder.
* **`GET /v1/lists?folderId=...`** answers the lists in one folder, and `GET /v1/folders` every folder for one kind of list.
* **Deleting a folder keeps its lists**, out of every folder.

## Delete a list

`DELETE /v1/lists/{listId}` deletes a list and its own columns. Its people stay in your workspace and in every other list they are in.

## Keys and limits

Reading lists, rows and folders works with any key that has the lists scope, read-only keys included. Creating, changing and deleting them needs a key that can write. Every list and folder call shares one [rate limit](https://docs.outbound.dev/rate-limits.md): 120 calls a minute and 10,000 a day.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.