Segments API (BETA) - HubSpot docs

Scope requirements

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 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

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.
`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:

{
  "processingTypes": ["DYNAMIC"],
  "objectTypeId": "0-1",
  "count": 5,
  "additionalProperties": ["hs_description"]
}

Your response would look like:

{
  "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:

{
  "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.

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 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:

{
  "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:

{
  "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.

Show Example response

{
  "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, 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:

{
  "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.

​What’s new in 2026-09-beta

​Read all segments

​Validation errors

​Create segments

​Processing types

​Example

​Update segments

​Update segment names

​Update a segment filter branch

​Delete and restore a segment