Required Scopes
Required Scopes
What’s new in 2026-09
In the2026-09 version of the Segments (Lists) API, a new search endpoint (/crm/lists/2026-09/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.
Create segments
To create a segment, make aPOST request to /crm/lists/2026-09/.
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.
Processing types
There are threeprocessingType 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 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 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: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:
Retrieve segments
Depending on your use case, there are multiple ways to retrieve segments. A segment can be retrieved by its name and object or by its ILS list ID. When retrieving segments, include a query parameter ofincludeFilters=true to return segment filter definitions in the response.
Retrieve all segments
To read all segments, sorted by ID, make aPOST request to /crm/lists/2026-09/all.
To retrieve all segments, add an empty request body. To retrieve specific segments, you can include the following optional filters.
Segments are returned in ascending ID order. By default, the following properties are returned for each segment if there are values:
For example, to retrieve active contact segments (five per page) with their descriptions, your request body would look like:
after string, your request body would look like:
/crm/lists/2026-09/all endpoint.
Retrieve by segment name
To retrieve a segment by name, make aGET request to /crm/lists/2026-09/object-type-id/{objectTypeId}/name/{listName}. The objectTypeId is the ID that corresponds to the type of object stored by the segment. See the full list of object type IDs.
For example, to retrieve the contact segment created above, make a GET request to /crm/lists/2026-09/object-type-id/0-1/name/My%20static%20segment.
Retrieve by ILS list ID
A segment’s ILS ID is returned in thelistId field when a new segment is created. To find an existing segment’s ILS ID, you can either:
- Navigate to the segments tool in HubSpot. Hover over the segment, then click Details. Learn more about viewing segments.
- Search for a segment by other criteria, then view the
listIdin the response.
- To retrieve an individual segment by ILS list ID, make a
GETrequest to/crm/lists/2026-09/{listId}. - To retrieve multiple segments by ILS list ID, make a
GETrequest to/crm/lists/2026-09and include alistIdsquery parameter for each segment. For example:/crm/lists/2026-09?listIds=940&listIds=938.
Retrieve by searching segment details
You can search for segments by other criteria by making aPOST request to /crm/lists/2026-09/search.
In the request body, specify the criteria that you want to search by.
- To search for segments that contain specific words in their name, include the
queryfield. - To search for segments of a specific processing type, include a
processingTypesarray with each of the processing types you want to search by. - To search for segments of a specific object, include the
objectTypeIdfield, with the type ID value for the object (e.g.,0-1for contacts).
Update segments
Update segment names
To update a segment’s name, make aPUT request to /crm/lists/2026-09/{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 within 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/612/update-list-name?listName=January%20Event%20Contacts%20Segment&includeFilters=true. Expand the section below to review an example of the expected response.
Update segment filters
To update aDYNAMIC segment’s filter branches, make a PUT request to /crm/lists/2026-09/{listId}/update-list-filters. In the request body, include the updated filter branch definition. This definition will replace the existing definition, so 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:
Delete and restore a segment
To delete a segment, make aDELETE request to /crm/lists/2026-09/{listId}.
Once deleted, segments can be restored within 90 days of deletion by making a PUT request to /crm/lists/2026-09/{listId}/restore. Segments deleted more than 90 days ago cannot be restored.
Manage segment membership
To view and manage records included in a segment, you can use the/memberships/ endpoints below. Segment membership endpoints that update memberships can only be used on MANUAL or SNAPSHOT segment processing types.
DYNAMIC segments will add and remove records based on the filter criteria set. You cannot use segment membership endpoints to update your segment. Instead, edit the segment’s filters or edit the record you want to add or remove.
Retrieve records with segment memberships
To retrieve records with segment memberships, you’ll need to make two calls: one to retrieve the records, then another to retrieve their segment memberships. First, make a search request to the objects API with the object for which you want to search records (e.g.,0-1 for contacts). You can add filters to specify the records you want.
- To retrieve recently created records, filter by
createdate. - To retrieve recently updated records, filter by
lastmodifieddate.
id values to retrieve segment membership details.
To retrieve an individual record’s memberships, make a GET request to /crm/lists/2026-09/records/{objectTypeId}/{recordId}/memberships. For example, to retrieve an individual contact’s memberships, your request URL would look like /crm/lists/2026-09/records/0-1/1234567/memberships.
Your response will look like:
POST request to /crm/lists/2026-09/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 101112, your request would look like:
View records in an existing segment
To view all records in an existing segment, make aGET request to /crm/lists/2026-09/{listId}/memberships. This returns all members of a segment ordered by recordId.
Add records to an existing segment
To add records to an existing segment, make aPUT request to /crm/lists/2026-09/{listId}/memberships/add with a list of record IDs in the request body.
For example, your request body would look like:
Remove records from an existing segment
To remove all records from an existing segment, make aDELETE request to /crm/lists/2026-09/{listId}/memberships. This will not delete the segment from your account, but the segment will contain no records.
To remove specific records from an existing segment, make a PUT request to /crm/lists/2026-09/{listId}/memberships/remove with a list of record IDs in the request body.
For example, your request body would look like:
Add and remove records in the same request
To both add records to and remove records from a segment at the same time, make aPUT request to /crm/lists/2026-09/{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:
Add records from one segment to another
To add all records from one segment to another segment, make aPUT request to /crm/lists/2026-09/{listId}/memberships/add-from/{sourceListId}. The listId is the segment to add the records to and the sourceListId is the segment to retrieve records from. You can move a limit of 100,000 records at a time.
Retrieve members by join order
To retrieve members of a segment ordered by when they joined, make aGET request to /crm/lists/2026-09/{listId}/memberships/join-order.
You can include the following optional query parameters to control pagination:
Convert segments from active to static
You can convert existing active segments into static segments by scheduling the conversion for a specific date or based on inactivity. You can use the segments endpoints to schedule conversions, retrieve scheduled or past conversions, and delete scheduled conversions.Schedule or update a segment conversion
To schedule a conversion or update an existing scheduled conversion, make aPUT request to /crm/lists/2026-09/{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. Includeyear,month, anddayfields to specify the desired date. This date must be in the future.INACTIVITY: schedules the conversion if the segment hasn’t been active for a set amount of time, based on when the last record was added or removed. Include thetimeUnitfield to specify the unit of time (DAY,WEEK, orMONTH) and theoffsetfield to specify the amount of time after which the segment is considered inactive. Only onetimeUnitcan be specified and theoffsetvalue must be positive.
- JSON
- JSON
Retrieve a segment conversion
To retrieve information about a segment’s conversion, make aGET request to /crm/lists/2026-09/{listId}/schedule-conversion. The response will include the requestedConversionTime object with the conversionType and the relevant fields for that type. If the segment was already converted, the convertedAt field will be returned with the timestamp of the conversion.
For example, for a segment that completed a conversion, your response would look similar to the following:
Delete a scheduled segment conversion
To delete a conversion, make aDELETE request to /crm/lists/2026-09/{listId}/schedule-conversion. If the conversion does not exist, a 404 will be returned.
Manage segment folders
Segments can be organized into folders to help you manage large numbers of segments in your account. You can retrieve, create, rename, move, and delete folders using the/folders endpoints.
Retrieve folders
To retrieve your folder structure, make aGET request to /crm/lists/2026-09/folders.
By default, this returns the root folder. To navigate into a specific folder, include the folderId query parameter. The response includes the following fields for the folder:
Create a folder
To create a folder, make aPOST request to /crm/lists/2026-09/folders. In the request body, include the name for the new folder. To nest the folder inside an existing folder, include the parentFolderId of the parent.
For example, to create a folder called “Marketing segments” at the root level, your request body would look like:
42, your request body would look like:
Move a segment to a folder
To move a segment into a folder, make aPUT request to /crm/lists/2026-09/folders/move-list. In the request body, include the listId of the segment to move and the newFolderId of the destination folder.
For example, to move segment 611 into folder 42, your request body would look like:
Rename a folder
To rename a folder, make aPUT request to /crm/lists/2026-09/folders/{folderId}/rename and include the newFolderName query parameter with the new name.
For example, to rename folder 42 to “Q4 campaigns”, the request URL would be: /crm/lists/2026-09/folders/42/rename?newFolderName=Q4%20campaigns.
Move a folder
To move a folder into a different parent folder, make aPUT request to /crm/lists/2026-09/folders/{folderId}/move/{newParentFolderId}, where folderId is the folder to move and newParentFolderId is the destination parent folder.
Delete a folder
To delete a folder, make aDELETE request to /crm/lists/2026-09/folders/{folderId}.
Translate legacy list IDs
If you have existing integrations that use legacy list IDs, you can use the/idmapping endpoints to retrieve the corresponding current ILS list IDs.
Translate a single legacy ID
To retrieve the current ILS list ID for a single legacy list, make aGET request to /crm/lists/2026-09/idmapping with the legacyListId query parameter.
For example: /crm/lists/2026-09/idmapping?legacyListId=123.
The response returns both the legacyListId and the corresponding listId.
Translate multiple legacy IDs
To translate multiple legacy list IDs in a single request, make aPOST request to /crm/lists/2026-09/idmapping with an array of legacy list IDs in the request body.
For example, to translate three legacy IDs, your request body would look like:
legacyListIdsToIdsMapping: an array of objects, each containing thelegacyListIdand its corresponding currentlistId.missingLegacyListIds: an array of any legacy IDs that could not be found.
Retrieve segment size and edit history
To retrieve the historical size data and edit timestamps for a segment over a date range, make aGET request to /crm/lists/2026-09/{listId}/size-and-edits-history/between.
Include the following required query parameters:
The response includes:
sizeHistory: an array of data points showing the segment’s size over time within the requested range.editHistory: an array of timestamps indicating when the segment was edited within the requested range.