> ## Documentation Index > Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt > Use this file to discover all available pages before exploring further. --- id: 31c5bd3b-82aa-4978-ba40-9235e8418537 --- # Lists (Segments) API > Learn how to create and manage segments using the Lists API. export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => { if (!scopes || scopes.length === 0) { return null; } const sortedScopes = scopes.sort((a, b) => a.localeCompare(b)); return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
; }; The legacy v1 lists API has been [sunset as of April 30th, 2026](https://developers.hubspot.com/changelog/upcoming-sunset-v1-lists-api). Calls made to the v1 endpoints will no longer function. If you previously used the v1 endpoints, follow the [migration guide](/api-reference/legacy/crm/lists/v1-list-api-migration-guide) to transition to the latest version of the API. Lists (now called [segments](https://knowledge.hubspot.com/segments/create-active-or-static-lists)) are a collection of records of the same object that can be used for record segmentation, filtering, and grouping to serve your business needs. With the Lists API, you can create, edit, and fetch lists, manage list membership, and convert list types. 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. ## 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](/api-reference/latest/crm/lists/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](/api-reference/latest/crm/lists/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/lists/2026-03`. 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](/api-reference/latest/crm/lists/list-filters). For example, the following request body would create a new static list of contacts: ```json theme={null} { "name": "My static list", "objectTypeId": "0-1", "processingType": "MANUAL" } ``` Once created, a `listId` (the ILS list ID) will be generated. This ID is used for future updates and modifications. The following is an example response with the ILS list ID highlighted: ```json highlight={3} theme={null} { "list": { "listId": "611", "listVersion": 1, "createdAt": "2026-02-02T16:13:48.146Z", "updatedAt": "2026-02-02T16:13:48.146Z", "filtersUpdatedAt": "2026-02-02T16:13:48.146Z", "processingStatus": "COMPLETE", "createdById": "9586504", "updatedById": "9586504", "processingType": "MANUAL", "objectTypeId": "0-1", "name": "My static list", "listPermissions": { "teamsWithEditAccess": [], "usersWithEditAccess": [] }, "membershipSettings": { "membershipTeamId": null, "includeUnassigned": null } } } ``` ## Retrieve lists Depending on your use case, there are multiple ways to retrieve lists. A list can be retrieved via the lists API by its name and object or by its ILS list ID. When retrieving lists, include a query parameter of `includeFilters=true` to return [list filter definitions](/api-reference/latest/crm/lists/list-filters) in the response. To retrieve lists by other criteria (e.g., processing type), you can use the [search API](#retrieve-by-searching-list-details). ### Retrieve by list name To retrieve a list by name, make a `GET` request to `/crm/lists/2026-03/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](/guides/crm/understanding-the-crm#object-type-ids). For example, to retrieve the contact list created above, make a `GET` request to `/crm/lists/2026-03/object-type-id/0-1/name/My%20static%20list`. ### Retrieve by ILS List ID A list's ILS ID is returned in the `listId` field when a new list is created. To find an existing list's ILS ID, you can either: * Navigate to the lists (segments) tool in HubSpot, then hover over the **list** and click **Details**. Learn more about [viewing lists](https://knowledge.hubspot.com/segments/edit-or-delete-lists#preview-segment-details-and-filters). * [Search for a list](#retrieve-by-searching-list-details) by other criteria, then view the `listId` in the response. To retrieve lists by ILS ID: * To retrieve an individual list by ILS list ID, make a `GET` request to `/crm/lists/2026-03/{listId}`. * To retrieve multiple lists by ILS list ID, make a `GET` request to `/crm/lists/2026-03` and include a `listIds` query parameter for each list. For example: `/crm/lists/2026-03?listIds=940&listIds=938`. ### Retrieve by searching list details You can search for lists by other criteria by making a `POST` request to `/crm/lists/2026-03/search`. In the request body, specify the criteria that you want to search by. * To search for lists that contain specific words in their name, include the `query` field. * To search for lists of a specific processing type, include a `processingTypes` array with each of the processing types you want to search by. * To search for lists of a specific object, include the `objectTypeId` field, with the [type ID value](/guides/crm/understanding-the-crm#object-type-ids) for the object (e.g., `0-1` for contacts). For example, to search for contact static lists that contain "HubSpot" in the name, your request body would look like: ```json theme={null} { "query": "HubSpot", "processingTypes": ["MANUAL"], "objectTypeId": "0-1" } ``` ## Update lists You can update a list's name and its filters via the lists API. ### Update list name To update a list's name, make a `PUT` request to `/crm/lists/2026-03/{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 account. You can also include a query parameter of `includeFilters=true` to return list filter definitions in the response. For example, to change a list's name (with the ILS ID `612`) to "January Event Contacts List" and return filters, the request URL would be: `/crm/lists/2026-03/612/update-list-name?listName=January%20Event%20Contacts%20List&includeFilters=true`. Expand the section below to review an example of the expected response. ```json theme={null} { "updatedList": { "listId": "612", "listVersion": 1, "createdAt": "2026-02-02T16:34:48.872Z", "updatedAt": "2026-02-02T16:34:48.872Z", "filtersUpdatedAt": "2026-02-02T16:34:48.872Z", "processingStatus": "COMPLETE", "createdById": "9586504", "updatedById": "9586504", "processingType": "DYNAMIC", "objectTypeId": "0-1", "name": "January Event Contacts List", "filterBranch": { "filterBranches": [ { "filterBranches": [], "filters": [ { "property": "email", "operation": { "operator": "IS_KNOWN", "includeObjectsWithNoValueSet": false, "operationType": "ALL_PROPERTY" }, "filterType": "PROPERTY" }, { "property": "hs_content_membership_email_confirmed", "operation": { "operator": "IS_BETWEEN", "includeObjectsWithNoValueSet": false, "lowerBoundEndpointBehavior": "INCLUSIVE", "upperBoundEndpointBehavior": "INCLUSIVE", "propertyParser": "UPDATED_AT", "lowerBoundTimePoint": { "timezoneSource": "CUSTOM", "zoneId": "US/Eastern", "indexReference": { "referenceType": "TODAY" }, "offset": { "days": -15 }, "timeType": "INDEXED" }, "upperBoundTimePoint": { "timezoneSource": "CUSTOM", "zoneId": "US/Eastern", "indexReference": { "referenceType": "NOW" }, "timeType": "INDEXED" }, "type": "TIME_RANGED", "operationType": "TIME_RANGED" }, "filterType": "PROPERTY" } ], "filterBranchType": "AND", "filterBranchOperator": "AND" } ], "filters": [], "filterBranchType": "OR", "filterBranchOperator": "OR" }, "listPermissions": { "teamsWithEditAccess": [], "usersWithEditAccess": [] }, "membershipSettings": { "membershipTeamId": null, "includeUnassigned": true } } } ``` ### Update a list filter branch To update a `DYNAMIC` list's [filter branches](/api-reference/latest/crm/lists/list-filters), make a `PUT` request to `/crm/lists/2026-03/{listId}/update-list-filters`. In the request body, include the updated filter branch definition. This definition will replace the existing definition, so make sure to include any filters you want to keep from the previous definition. Once the filter branch is updated, the list will begin processing its new memberships. For example, your list includes a filter based on contact's *Likelihood to close* (`hs_predictivecontactscore_v2`) that you want to keep. To add filters to include contacts with a value for `email` who also opted into certain email subscriptions, your request body would look like: ```json theme={null} { "filterBranch": { "filterBranchType": "OR", "filterBranches": [ { "filterBranchType": "AND", "filters": [ { "filterType": "PROPERTY", "operation": { "operationType": "NUMBER", "operator": "IS_GREATER_THAN_OR_EQUAL_TO", "value": 12 }, "property": "hs_predictivecontactscore_v2" }, { "filterType": "PROPERTY", "operation": { "operationType": "ALL_PROPERTY", "operator": "IS_KNOWN" }, "property": "email" }, { "acceptedStatuses": [ "OPT_IN" ], "filterType": "EMAIL_SUBSCRIPTION", "subscriptionIds": [ "81537745", "321981152" ] } ] } ] } } ``` ## Delete and restore a list To delete a list, make a `DELETE` request to `/crm/lists/2026-03/{listId}`. Once deleted, lists can be restored within 90 days of deletion by making a `PUT` request to `/crm/lists/2026-03/{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 that update memberships can only be used on `MANUAL` or `SNAPSHOT` list processing types. `DYNAMIC` lists will add and remove records based on the filter criteria set. You cannot use list membership endpoints to update your list. Instead, edit the list's filters or the record you want to add or remove. ### Retrieve records with list memberships To retrieve records with list memberships, you'll need to make two calls: one to retrieve the records, then another to retrieve their list memberships. First, make a `POST` request to `/crm/objects/2026-03/{objectTypeId}/search` with the object for which you want to search records (e.g.,`0-1` for contacts). You can add [filters](/api-reference/latest/crm/search-the-crm#filter-search-results) to specify the records you want. * To retrieve recently created records, filter by `createdate`. * To retrieve recently updated records, filter by `lastmodifieddate`. You can add properties to retrieve more details about the records as needed. For example, to search for contacts edited after May 31, 2025: ```json theme={null} { "properties": [ "firstname", "lastname", "email", "hs_object_id", "createdate", "lastmodifieddate" ], "filterGroups": [ { "filters": [ { "propertyName": "lastmodifieddate", "operator": "GT", "value": "2025-05-31" } ] } ] } ``` Next, use the object endpoint to retrieve the membership details for the records individually or in bulk. From your search request, use record `id` values to retrieve list membership details. To retrieve an individual record’s memberships, make a `GET` request to `/crm/lists/2026-03/records/{objectTypeId}/{recordId}/memberships`. For example, to retrieve an individual contact’s memberships, your request URL would look like `/crm/lists/2026-03/records/0-1/1234567/memberships`. Your response will look like: ```json theme={null} { "results": [ { "listId": "76", "listVersion": 1, "isPublicList": true, "firstAddedTimestamp": "2025-07-28T13:42:08.595Z", "lastAddedTimestamp": "2025-07-28T13:42:08.595Z" }, { "listId": "78", "listVersion": 1, "isPublicList": true, "firstAddedTimestamp": "2025-07-28T13:42:08.595Z", "lastAddedTimestamp": "2025-07-28T13:42:08.595Z" }, { "listId": "493", "listVersion": 1, "isPublicList": false, "firstAddedTimestamp": "2024-07-23T19:40:36.192Z", "lastAddedTimestamp": "2024-07-23T19:40:36.192Z" }, { "listId": "541", "listVersion": 1, "isPublicList": true, "firstAddedTimestamp": "2025-04-21T14:01:43.475Z", "lastAddedTimestamp": "2025-04-21T14:01:43.475Z" }, { "listId": "492", "listVersion": 1, "isPublicList": false, "firstAddedTimestamp": "2024-07-23T19:36:11.890Z", "lastAddedTimestamp": "2024-07-23T19:36:11.890Z" } ] } ``` To retrieve multiple records’ memberships, make a `POST` request to `/crm/lists/2026-03/records/memberships/batch/read`. In the request, include the `objectTypeId` value of the object for which you’re retrieving records (e.g., `0-1` for contacts) and the `id` values for the records. For example, to retrieve memberships for contacts `12345` and `67890`, your request would look like: ```json theme={null} { "inputs": [ { "objectTypeId": "0-1", "recordId": "12345" }, { "objectTypeId": "0-1", "recordId": "101112" } ] } ``` ### View records in an existing list To view all records in an existing list, make a `GET` request to `/crm/lists/2026-03/{listId}/memberships`. This returns all members of a list ordered by `recordId`. ### Add records to an existing list To add records to an existing list, make a `PUT` request to `/crm/lists/2026-03/{listId}/memberships/add` with a list of record IDs in the request body. For example, your request body would look like: ```json theme={null} [ "55555", "69876", "487888", "46999874" ] ``` ### Remove records from an existing list To remove all records from an existing list, make a `DELETE` request to `/crm/lists/2026-03/{listId}/memberships`. This will not delete the list from your account, but the list will contain no records. To remove specific records from an existing list, make a `PUT` request to `/crm/lists/2026-03/{listId}/memberships/remove` with a list of record IDs in the request body. For example, your request body would look like: ```json theme={null} [ "12345", "55986", "489756" ] ``` ### Add and remove records in the same request To both add records to and remove records from a list at the same time, make a `PUT` request to `/crm/lists/2026-03/{listId}/memberships/add-and-remove`. In the request body, include the `recordIdsToAdd` and `recordIdsToRemove` fields with the IDs of records to add and remove. For example, your request body would look like: ```json theme={null} { "recordIdsToAdd": [ "123", "456", "789" ], "recordIdsToRemove": [ "654", "5555" ] } ``` ### Add records from one list to another To add all records from one list to another list, make a `PUT` request to `/crm/lists/2026-03/{listId}/memberships/add-from/{sourceListId}`. The `listId` is the list to add the records to and the `sourceListId` is the list to retrieve records from. You can move a limit of 100,000 records at a time. ## Convert lists from active to static You can [convert existing active lists into static lists](https://knowledge.hubspot.com/segments/change-list-type) 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/lists/2026-03/{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 theme={null} { "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 theme={null} { "conversionType": "INACTIVITY", "timeUnit": "DAY", "offset": 5 } ``` ### Retrieve a list conversion To retrieve information about a list's conversion, make a `GET` request to `/crm/lists/2026-03/{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 theme={null} { "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/lists/2026-03/{listId}/schedule-conversion`. If the conversion does not exist, a 404 will be returned.