Lists

 Lists are a collection of records of the same object type that can be used for record segmentation, filtering, and grouping to serve your business needs. You can create contact, company, deal, or custom object lists. The v3 Lists API allows you to create, edit, and fetch lists. 

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. This type of list is helpful for when you need a set list of records that won't change unless manually updated.

DYNAMIC: this processing type gives the possibility to specify list filters to match records that will become list members. This type of list is processed in the background by HubSpot 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.  This type of list is helpful for when you want to keep a running list that you expect to change over time.

SNAPSHOT: list 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. This type of list is helpful for when you want to create a list of records based on specific criteria, but don't want that list to change automatically after initial processing.

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

In the request body, you must include the following parameters: name, objectTypeId, and processingType. The filterBranch parameter is optional, and can be included to create branching logic for DYNAMIC and SNAPSHOT type lists. Learn more about configuring list filters and branches.

Once created, a listID (the ILS list ID) will be generated. This ID is used for future updates and modifications.

Depending on your use case, there are multiple ways to retrieve lists: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 by name, make a GET request to /crm/v3/lists/object-type-id/{objectTypeId}/name/{listName}. The objectTypeId is the ID that corresponds to the type of object stored by the list. See the full list of object type IDs.
• To retrieve an individual list by ILS list ID, make a GET request to /crm/v3/lists/{listId}. Learn more about finding the ILS list ID below.
• To retrieve multiple listsby ILS list ID, make a GET request to /crm/v3/lists and include a listIds query parameter for each list. For example: ?listIds=940&listIds=938.

When retrieving lists, you can include a query parameter of includeFilters=true to return list filter definitions in the response.

To find a list's ILS list ID, you can navigate to the lists tool in HubSpot, then hover over the list and click Details. Learn more about viewing lists. You can also search for lists by other criteria, then view the list's ID in the response.

You can search for lists by making a POST request to /crm/v3/lists/search. 

In the request body, you'll specify the criteria that you want to search by. For example, to search for lists that contain specific words in their name, you can include the query field. Or, to search for lists of a specific processing type, include a processingTypes array with each of the processing types you want to search by.

For example, to search for all static lists that contain "HubSpot" in the name, your request body would be as follows:

To update a list name, make a PUT request to /crm/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.

You can also include a query parameter of includeFilters=true to return list filter definitions in the response.

To update a DYNAMIC list's filter branches, make a PUT request to /crm/v3/lists/{listId}/update-list-filters. In the request body, include the new filter branch definition. This

A list filter branch can be updated by sending a PUT request to /crm/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. Once the filter branch is updated, the list will begin processing its new memberships. 

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

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

To view and manage records included in a list, you can use the /memberships/ endpoints below. 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 /crm/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 ​/crm/v3​/lists/{listId}/memberships​/add-from​/{sourceListId}, where the sourceListId is the list you're retrieving the records from. You can move a limit of 100,000 records at a time. 

To view all records in an existing list, make a GET request to /crm/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 /crm/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 /crm/v3/lists/{listId}/memberships/remove with a list of recordIDs in the request body. 

If you were previously using any of the v1 list endpoints, you can migrate over to the equivalent endpoints detailed in the sections below. 

To get a static list, make a POST request to /crm/v3/lists/search and include SNAPSHOT and MANUAL within an array provided as the processingTypes parameter in your request body. 

To get a dynamic list, make a POST request to /crm/v3/lists/search and include DYNAMIC within an array provided as the processingTypes parameter in your request body. 

To get a batch of lists by the listIds, make a POST request to /crm/v3/lists/search. In the request, include the desired list IDs in the listIds parameter and specify any additional properties. The response will not include any filter branches.

To include filters in your response, make a GET request to /crm/v3/lists. In the request, append the query parameters includeListFilters=true and the desired list IDs as the listIds parameter. E.g. /crm/v3/lists?includeFilters=true&listIds=42&listIds=51

First, make a GET request to  /crm/v3/lists/{listId}/memberships/join-order to get the record IDs of the list members. Then, make a POST request to /crm/v3/objects/{object}/search for the specific objectTypeId and include the record IDs in the values parameter.

Use the CRM search endpoint to search for records in your HubSpot account. To get all records, make a POST request to /crm/v3/objects/{object}/search with the object you want to search for. 

To get recently modified records, make a POST request to /crm/v3/objects/{object}/search and filter by lastmodifieddate. 

Contact lists have two list IDs: a legacy list ID that corresponds with the legacy v1 lists API endpoint, and one that corresponds with the v3 lists API endpoint.

As the legacy v1 Lists APIwill be sunset starting May 30th, 2025, HubSpot API users must migrate their legacy v1 list IDs to the v3 list IDs. To do so, use the ID mapping endpoints to fetch the v3 list ID (listId) from one or more v1 list IDs (legacyListId). 

To fetch mappings one at a time, make a GET request to /crm/v3/lists/idmapping?legacyListId=<legacyListId> with the v1 list ID in the legacyListID parameter. 

To fetch multiple ID mappings in one batch, make a POST request to /crm/v3/lists/idmapping and include the legacy list ID values within an array. The limit on this API is 10, 000 entries.