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.
Overview
A list is a named set of records of a single object, such as a set ofcompany 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.
The Lists API includes the following endpoints:
- List lists
- Create a list
- Get a list
- Update a list
- Delete a list
- List entries
- Get an entry
- Add entries
- Remove entries
Usage
The Lists API is part of the Data API and uses the same base URL, authentication, and rate limits.Sharing
share_status controls who can see and change a list besides its owner:
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 bymatch 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 for
details.
Deleting a list or removing an entry does not delete the underlying records.
Pagination
List endpoints are cursor-paginated. Each response includes anext_cursor
value; pass it as the cursor query parameter to fetch the next page. A null
next_cursor means there are no more results.