Lists (Segments) API - HubSpot docs

Last modified: September 26, 2025

Lists (now called segments) are a collection of records of the same object that can be used for record segmentation, filtering, and grouping to serve your business needs. The v3 Lists API allows you to create, edit, and fetch lists, as well as convert active lists into static 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.

The legacy v1 lists API will be sunset on April 30th, 2026. If you’re using the v1 lists API, review the guide to transition to the v3 API.

List processing types

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.

Create a list

To create a list, make a POST request to /crm/v3/lists. In the request body, you must include the following fields: 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.

// Example request body
{
  "name": "My static list",
  "objectTypeId": "0-1",
  "processingType": "MANUAL"
}

Retrieve lists

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.

Search for a list

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:

// Example request body
{
  "query": "HubSpot",
  "processingTypes": ["MANUAL"]
}

Update lists

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.

Update a list filter branch

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.

Delete and restore a list

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.

Manage list membership

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.

Add records to an existing list

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.

View records in an existing list

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.

Delete records from an existing list

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.

Convert lists from active to static

You can convert existing active lists into static lists by scheduling the conversion for a specific date or based on inactivity. You can use the lists endpoints to schedule conversions, retrieve scheduled or past conversions, and delete scheduled conversions.

Schedule or update a list conversion

To schedule a conversion or update an existing scheduled conversion, make a PUT request to /crm/v3/lists/{listId}/schedule-conversion. In the request body, include one of the following conversionType values and the type’s related fields:

CONVERSION_DATE: schedules the conversion for a specific date. Include year, month, and day fields to specify the desired date. This date must be in the future.
INACTIVITY: schedules the conversion if the list hasn’t been active for a set amount of time, based on when the last record was added or removed. Include the timeUnit field to specify the unit of time (DAY, WEEK, or MONTH) and the offset field to specify the amount of time after which the list is considered inactive. Only one timeUnit can be specified and the offset value must be positive.

For example, to schedule an active list to be converted to a static list on January 31, 2025, your request would look like the following:

JSON

{
  "conversionType": "CONVERSION_DATE",
  "year": 2025,
  "month": 1,
  "day": 31
}

To schedule an active list to be converted to a static list after five days of inactivity, your request would look like the following:

JSON

{
  "conversionType": "INACTIVITY",
  "timeUnit": "DAY",
  "offset": 5
}

Retrieve a list conversion

To retrieve information about a list’s conversion, make a GET request to /crm/v3/lists/{listId}/schedule-conversion. The response will include the requestedConversionTime object with the conversionType and the relevant fields for that type. If the list was already converted, the convertedAt field will be returned with the timestamp of the conversion. For example, for a list that completed a conversion, your response would look similar to the following:

JSON

{
  "listId": "35",
  "requestedConversionTime": {
    "conversionType": "CONVERSION_DATE",
    "year": 2025,
    "month": 1,
    "day": 1
  },
  "convertedAt": "2025-01-01T05:20:34.002Z"
}

Delete a scheduled list conversion

To delete a conversion, make a DELETE request to /crm/v3/lists/{listId}/schedule-conversion. If the conversion does not exist, a 404 will be returned.

​List processing types

​Create a list

​Retrieve lists

​Search for a list

​Update lists

​Update a list filter branch

​Delete and restore a list

​Manage list membership

​Add records to an existing list

​View records in an existing list

​Delete records from an existing list

​Convert lists from active to static

​Schedule or update a list conversion

​Retrieve a list conversion

​Delete a scheduled list conversion