> ## 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: 174d5e58-cbbd-4c54-9991-14434f734813 --- # Segments API (BETA) > Retrieve, create, and manage segments (lists). 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}
)}
; }; Use the Segments (Lists) API to create and manage segments. For example, create a segment of good-fit leads to send a marketing email or group high-priority deals. Learn more about using [segments](https://knowledge.hubspot.com/segments/create-active-or-static-lists) in HubSpot. ## What’s new in 2026-09-beta In the `2026-09-beta` version of the Segments (Lists) API, a new search endpoint (`/crm/lists/2026-09-beta/all`) was added that sorts results by segment ID in ascending order. Pagination for this endpoint uses a cursor (`after`), so you can page through all segments by making additional calls with the cursor. Learn more about [reading segments](#read-all-segments). ## Read all segments To read all segments, sorted by ID, make a `POST` request to `/crm/lists/2026-09-beta/all`. To retrieve all segments, add an empty request body. To retrieve specific segments, you can include the following optional filters. | Filter | Type | Description | | ---------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `objectTypeId` | String | The CRM object for which to return segments. You can find a full list of object type IDs [here](https://developers.hubspot.com/docs/api-reference/latest/crm/understanding-the-crm#object-type-ids). | | `processingTypes` | Array | The types of segment to view: `MANUAL`, `DYNAMIC`, or `SNAPSHOT`. | | `count` | Number | Set the number of results per page. By default, 20 segments are returned per page, but you can request up to 500 per page. | | `additionalProperties` | Array | Other segment properties to return for each segment in the response. | | `after` | String | In subsequent requests, include the `after` value returned in the response to retrieve the next page of results. | Segments are returned in ascending ID order. By default, the following properties are returned for each segment if there are values: | Field | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `listId` | The segment's ILS ID. | | `listVersion` | The current version of the segment. | | `createdAt` | The date and time the segment was created. | | `updatedAt` | The date and time of the latest update to the segment. | | `filtersUpdatedAt` | The date and time of the latest update to the segment's filters. | | `processingStatus` | The segment's processing status: `COMPLETE`, `PAUSED`, or `PROCESSING`. | | `createdById` | The ID of the user that created the segment. | | `updatedById` | The ID of the user that last updated the segment. | | `processingType` | The type of segment: `MANUAL`, `DYNAMIC`, or `SNAPSHOT`. | | `objectTypeId` | The ID of the type of the object in the segment. | | `name` | The name of the segment. | | `additionalProperties` | An object with additional segment metadata. Includes `hs_list_size` and `hs_list_reference_count` by default, and will include other properties if there are values, including: `hs_folder_name`, `hs_last_record_added_at`, and `hs_last_record_removed_at`. You can request other specific properties by including `additionalProperties` in your request. | For example, to retrieve active contact segments (five per page) with their descriptions, your request body would look like: ```json theme={null} { "processingTypes": ["DYNAMIC"], "objectTypeId": "0-1", "count": 5, "additionalProperties": ["hs_description"] } ``` Your response would look like: ```json expandable theme={null} { "results": [ { "listId": "53", "listVersion": 2, "createdAt": "2020-01-09T20:47:03.539Z", "updatedAt": "2020-12-24T02:47:16.212Z", "filtersUpdatedAt": "2020-01-09T20:47:03.539Z", "processingStatus": "COMPLETE", "createdById": "9586504", "processingType": "DYNAMIC", "objectTypeId": "0-1", "name": "Tech Companies", "additionalProperties": { "hs_description": "Good-fit tech companies", "hs_list_reference_count": "0", "hs_last_record_added_at": "1740405014244", "hs_last_record_removed_at": "1769941583344", "hs_list_size": "68" } }, { "listId": "55", "listVersion": 2, "createdAt": "2020-01-15T15:10:16.823Z", "updatedAt": "2020-12-24T02:47:16.212Z", "filtersUpdatedAt": "2020-01-15T15:10:16.823Z", "processingStatus": "COMPLETE", "createdById": "9586504", "processingType": "DYNAMIC", "objectTypeId": "0-1", "name": "MQLs", "additionalProperties": { "hs_list_reference_count": "0", "hs_last_record_added_at": "1726766929847", "hs_last_record_removed_at": "1732133659385", "hs_list_size": "24" } }, { "listId": "57", "listVersion": 2, "createdAt": "2020-01-15T15:12:45.348Z", "updatedAt": "2020-12-24T02:47:16.212Z", "filtersUpdatedAt": "2020-01-15T15:12:45.348Z", "processingStatus": "COMPLETE", "createdById": "9586504", "processingType": "DYNAMIC", "objectTypeId": "0-1", "name": "Customers", "additionalProperties": { "hs_list_reference_count": "1", "hs_last_record_added_at": "1744036843676", "hs_last_record_removed_at": "1777623926634", "hs_list_size": "0" } }, { "listId": "58", "listVersion": 2, "createdAt": "2020-01-15T15:14:13.180Z", "updatedAt": "2020-12-24T02:47:16.212Z", "filtersUpdatedAt": "2020-01-15T15:14:13.180Z", "processingStatus": "COMPLETE", "createdById": "9586504", "processingType": "DYNAMIC", "objectTypeId": "0-1", "name": "Sales Job Titles", "additionalProperties": { "hs_list_reference_count": "0", "hs_last_record_removed_at": "1671038817928", "hs_list_size": "0" } }, { "listId": "59", "listVersion": 1, "createdAt": "2025-02-10T17:12:18.294Z", "updatedAt": "2025-02-10T17:12:18.294Z", "filtersUpdatedAt": "2025-02-10T17:12:18.294Z", "processingStatus": "COMPLETE", "createdById": "9586504", "updatedById": "9586504", "processingType": "DYNAMIC", "objectTypeId": "0-1", "name": "Recent marketing email opens", "additionalProperties": { "hs_description": "Contacts with recent marketing email opens (last 30 days)", "hs_list_reference_count": "0", "hs_list_size": "0" } } ], "paging": { "next": { "after": "eyJsaXN0SWQiOiI1OSIsIm9iamVjdFR5cGVJZCI6IjAtMSIsInByb2Nlc3NpbmdUeXBlcyI6WyJEWU5BTUlDIl19" } } } ``` To request the next page of results, using the `after` string, your request body would look like: ```json theme={null} { "processingTypes": ["DYNAMIC"], "objectTypeId": "0-1", "count": 5, "after": "eyJsaXN0SWQiOiI1OSIsIm9iamVjdFR5cGVJZCI6IjAtMSIsInByb2Nlc3NpbmdUeXBlcyI6WyJEWU5BTUlDIl19", "additionalProperties": ["hs_description"] } ``` ### Validation errors You may run into the following validation errors when using the `/crm/lists/2026-09-beta/all` endpoint. | Status | Validation error subcategory | Description | | ------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `INVALID_CURSOR` | This occurs when the `after` token is malformed or invalid, or if the `objectTypeId` or `processingTypes` filters changed between pages. Verify you're using the correct `after` value from the response and the same filters from your previous request body. | | `400` | `INVALID_PROCESSING_TYPE` | This occurs when one or more values in the `processingTypes` filter do not match a known processing type. Use one of the supported `processingTypes` options in your filter: `MANUAL`, `DYNAMIC`, or `SNAPSHOT`. | ## Create segments To create a segment, make a `POST` request to `/crm/lists/2026-09-beta/`. 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 segments. Learn more about [configuring segment filters and branches](/docs/api-reference/latest/crm/lists/list-filters). ### Processing types There are three `processingType` values for segments: `MANUAL`, `DYNAMIC`, and `SNAPSHOT`. * `MANUAL`: records can only be added to or removed from the segment via manual actions by the user or API call. There is no segment processing or segment membership management done in the background by HubSpot's systems. This type of segment is helpful for when you need a set group of records that won't change unless manually updated. * `DYNAMIC`: [filters](/docs/api-reference/latest/crm/lists/list-filters) are used to determine which records become segment members. This type of segment is processed in the background by HubSpot to ensure that the segment only contains records that match the filters. Whenever a record changes, it is reevaluated against the filters and is either added or removed. This type of segment is helpful for when you want to keep a running group that you expect to change over time. * `SNAPSHOT`: [filters](/docs/api-reference/latest/crm/lists/list-filters) are specified at the time of segment creation. After initial processing is completed, records can only be added to or removed from the segment by manual actions. This type of segment is helpful for when you want to create a group of records based on specific criteria, but don't want that segment to change automatically after initial processing. ### Example For example, the following request body would create a new static segment of contacts: ```json theme={null} { "name": "My static segment", "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 segment", "listPermissions": { "teamsWithEditAccess": [], "usersWithEditAccess": [] }, "membershipSettings": { "membershipTeamId": null, "includeUnassigned": null } } } ``` ## Update segments ### Update segment names To update a segment's name, make a `PUT` request to `/crm/lists/2026-09-beta/{listId}/update-list-name` with the `listName` query parameter. If the segment 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 segments in the account. You can also include a query parameter of `includeFilters=true` to return segment filter definitions in the response. For example, to change a segment's name (with the ILS ID `612`) to "January Event Contacts Segment" and return filters, the request URL would be: `/crm/lists/2026-09-beta/612/update-list-name?listName=January%20Event%20Contacts%20Segment&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 Segment", "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 segment filter branch To update a `DYNAMIC` segment's [filter branches](/docs/api-reference/latest/crm/lists/list-filters), make a `PUT` request to `/crm/lists/2026-09-beta/{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 segment will begin processing its new memberships. For example, your segment 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 segment To delete a segment, make a `DELETE` request to `/crm/lists/2026-09-beta/{listId}`. Once deleted, segments can be restored within 90 days of deletion by making a `PUT` request to `/crm/lists/2026-09-beta/{listId}/restore`. Segments deleted more than 90 days ago cannot be restored.