Lists (BETA)

Lists are a collection of records of the same type. For example, you can create contact lists, company lists, or custom object lists. Lists can be used for record segmentation, filtering, and grouping to serve your business needs. 

A list consists of a list definition and list memberships:

• List definition: stores essential information about the list. 
• List memberships: mappings between the list and object record. 

There are three types of list processing types: MANUAL, DYNAMIC, and SNAPSHOT. 

MANUAL: this processing type indicates that object records can only be added to or removed from the list via manual actions by the user or API call. There is no list processing or list membership management done in the background by HubSpot's systems.

DYNAMIC: this processing type gives the possibility to specify filters to match records that will become list members. This type of list is processed in the background by HubSpot systems to ensure that the list only contains records that match the list's filters. Whenever a record changes, it is reevaluated against the list's filters and either added to or removed from it. 

SNAPSHOT: filters are specified at the time of list creation. After initial processing is completed, records can only be added to or removed from the list by manual actions.

Filters are used together with filter branches to define the list criteria. This criteria determines how records will be added to either a SNAPSHOT or DYNAMIC list. Learn more about filters and how to define them here. 

To create a list, make a POST request to /v3/lists.

In your request, you must include the following parameters: name, objectTypeId, and processingType. The filterBranch parameter is optional. Once created, a listID (the ILD list ID) will be generated. This ID is used for future updates and modifications.

A list can be retrieved by using either the ILS list ID or the name and object type for the list.

To retrieve a list using the ILS list ID, make a GET request to /v3/lists/{listId}.

To retrieve a list using a list name, make a GET request to /v3/lists/object-type-id/{objectTypeId}/name/{listName}. The objectTypeId is the ID that corresponds to the type of object stored by the list. Review the list of objectTypeIDs here. 

When retrieving a list, an optional query param flag, includeFilters, can be set to true if the list definitions in the response should include the filter branch definition.

Multiple lists can be fetched in a single request by sending a GET request to /v3/lists with the list IDs to fetch as the listIDs parameter.

An optional query param flag, includeFilters, can be set to true if the list definitions in the response should include the filter branch definition.

To update a list name, make a PUT request to /v3/lists/{listId}/update-list-name with the listName query parameter. If the list with the provided ILS list ID exists, then its name will be updated to the provided listName. The listName must be unique amongst all other public lists in the portal.

An optional query param flag, includeFilters, can be set to true if the list definitions in the response should include the filter branch definition.

This endpoint can only be used for lists with a DYNAMIC processing type. 

A list filter branch can be updated by sending a PUT request to /v3/lists/{listId}/update-list-filters with a request body containing the new filter branch definition. If the list with the provided ILS list ID exists, then its filter branch definition will be updated to the provided filter branch. Oncethe filter branch is updated, the list will begin processing its new memberships. 

Lists can be searched by list name by sending a POST request to /v3/lists/search.  If no name is provided, then the endpoint will provide all lists in the portal up to the count provided in the request.

To delete a list, make a DELETE request to /v3/lists/{listId}.

Once deleted, lists can be restored within 90 days of deletion by making a PUT request to /v3/lists/{listID}/restore. Lists deleted more than 90 days ago cannot be restored.

List membership endpoints can only be used on MANUAL or SNAPSHOT list processing types. DYNAMIC lists will add and remove records based on the filter criteria set. 

To add records to an existing list, make a PUT request to /v3/lists/{listId}/memberships/add with a list of recordIDs in the request body. 

To add records from one list to another, make a PUT request to ​/v3​/lists/{listId}/memberships​/add-from​/{sourceListId}, where the sourceListId is the list you're retrieving the records from. 

To view all records in an existing list, make a GET request to /v3/lists/{listId}/memberships. This returns all members of a list ordered by recordId.

To remove all records from an existing list, make a DELETE request to /v3/lists/{listId}/memberships. This will not delete the list from your account. 

To remove specific records from an existing list, make a PUT request to /v3/lists/{listId}/memberships/remove with a list of recordIDs in the request body.