Lists

Use these endpoints to retrieve, create, and rename lists in your team's Apollo workspace. You can also add or remove saved contacts and accounts, and change an account list's book of business status.

Key concepts

Lists	Lists are saved groups of contacts or accounts that your team can organize and work with together. Creating a list creates an empty group; adding contacts or accounts populates it.
Contact and account lists	The `modality` parameter determines whether a list holds `contacts` or `accounts`. You can't change this value after creating the list. Use saved contact or account IDs when adding or removing members.
List names and IDs	List names must be unique within each modality in your team's workspace. Use a list's `id` to rename it or change its book of business status. Use list names in `label_names` to add or remove members. These endpoints refer to lists as labels in parameter names.
List membership	Adding or removing members changes which contacts or accounts belong to a list. Removing members doesn't delete the contacts or accounts. Adding members to a list name that doesn't exist creates the list automatically for the specified modality.

Choose an endpoint

I want to . . .	Use this
Retrieve the lists in my team's Apollo workspace	Get a list of all lists
Create an empty contact or account list	Create a list
Rename a list or change an account list's book of business status	Update a list
Add saved contacts or accounts to one or more lists	Add records to a list
Remove contacts or accounts from one or more lists	Remove records from a list

Build a contact list

Group saved contacts for a campaign, event, or other shared purpose.

Call search for contacts to find the contacts you want to include. Retain each contact's id.
Call create a list with a name and modality set to contacts. Retain the list's name and returned id.
Pass the contact IDs as entity_ids, the list name in label_names, and modality set to contacts to add records to a list.

You can skip creating an empty list if you don't need that separate step. Add records to a list creates the list automatically when the name doesn't exist. To build an account list, use saved account IDs and set modality to accounts.

Learn more: Use the create a list and add records to a list references to dig in to the workflow.

Move contacts between lists

Move contacts to a different group as their campaign or follow-up needs change.

Call get a list of all lists to identify the current and destination contact list names.
Call search for contacts to identify the contacts you want to move. Retain their id values.
Pass those IDs as entity_ids, the destination name in label_names, and modality set to contacts to add records to a list.
After the addition completes, pass the same IDs and the original list name to remove records from a list, with modality set to contacts.

The contacts remain saved in your workspace. If you rename either list later, use its new name in membership requests.

Learn more: Use the add records to a list and remove records from a list references to explore membership updates.