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

# Lists

> Create and manage lists of records in Unify.

<Note>
  The Lists API is currently in public beta and may change based on feedback.
  Whenever possible, we will maintain backward compatibility and provide advance
  notice of any breaking changes.
</Note>

## Overview

A *list* is a named set of records of a single object, such as a set of
`company` records to target this quarter. Each list holds records of one
object, set when the list is created. A list is owned by a user and shared
according to its `share_status`.

Each record in a list is a *list entry*. An entry points to a record by
`record_id` and `object`. To read the record itself, use the
[record APIs](/developers/api/data/records/get).

The Lists API includes the following endpoints:

* [List lists](/developers/api/data/lists/list)
* [Create a list](/developers/api/data/lists/create)
* [Get a list](/developers/api/data/lists/get)
* [Update a list](/developers/api/data/lists/update)
* [Delete a list](/developers/api/data/lists/delete)
* [List entries](/developers/api/data/list-entries/list)
* [Get an entry](/developers/api/data/list-entries/get)
* [Add entries](/developers/api/data/list-entries/add)
* [Remove entries](/developers/api/data/list-entries/remove)

## Usage

The Lists API is part of the Data API and uses the same
[base URL, authentication, and rate limits](/developers/api/data/overview#usage).

### Sharing

`share_status` controls who can see and change a list besides its owner:

| Value | Access |
| - | - |
| `ONLY_ME` | Only the owner and users the list was shared with in the Unify app. |
| `ALL_OTHERS_CAN_VIEW` | Everyone in the workspace can view. Only users with manage access can change it. |
| `ALL_OTHERS_CAN_EDIT` | Everyone in the workspace can view and change the list. |

New lists default to `ONLY_ME`. Updating, deleting, and adding or removing
entries require manage access to the list.

### Adding and removing records

Records are added and removed in batches of up to 100 per request. Each record
is identified by its ID or by `match` criteria, such as
`{ "match": { "email": "ada@acme.com" } }` on a person list. The response
reports the outcome for each record, so one missing record does not fail the
whole request. See [add entries](/developers/api/data/list-entries/add) for
details.

Deleting a list or removing an entry does not delete the underlying records.

### Pagination

List endpoints are cursor-paginated. Each response includes a `next_cursor`
value; pass it as the `cursor` query parameter to fetch the next page. A `null`
`next_cursor` means there are no more results.


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