Skip to content
HubSpot Developer Changelog

Breaking Change: Expanded Filtering Capabilities and Error Messaging in HubSpot's Search API


To empower our customers with enhanced search capabilities within the CRM, we are pleased to announce that starting August 26, 2024, there will be significant expansions to the filtering options available and error messaging in the Search API. This update is designed to support more complex and granular searches by increasing the limits on filter groups, total filters, and per group.

What's changing?

  • Filter Groups: The maximum number of filter groups increased to five from the previous limit of three. Filter groups allow for the logical grouping of filters to create complex search queries.
  • Total Filters: You can now define up to twenty-five filters in a single search query, a significant increase from the previous limit of nine. This enhancement allows for more detailed and specific search criteria.
  • Filters per Filter Group: Up to ten filters can now be specified within each filter group. This increases from the previous limit of three filters per group, allowing for more complex grouping and condition setting within each group.

Impact and use case

This enhancement is tailored for users requiring more sophisticated search functionality within HubSpot's CRM. Users can now create more detailed and targeted search queries by expanding the number and complexity of filters. This is particularly beneficial for:

  • Advanced Data Segmentation: Users can segment CRM data more precisely, enabling more targeted marketing, sales, and service strategies.
  • Complex Search Needs: Supports intricate search requirements, allowing users to simultaneously filter CRM data based on multiple, detailed criteria.
  • Efficiency Improvements: Reduces the need for multiple searches or external processing to achieve desired segmentation or data extraction, streamlining CRM data management.

Breaking Change: Error Handling for Filter Groups

In line with these new capabilities, we are also improving how our API handles errors for the new filter groups to enhance developer experience and API usability. This new error response provides validation for too many filters per filter group and introduces a new error category, VALIDATION_ERROR. This new error category introduces the breaking change.


Example of Error Response:

// Error response example { "status":"error", "message":"Error validating request.", "correlationId":"0d9e1b08-3d43-410b-87f4-13c18a8d62b3", "errors":[ { "message":"too many total filters across filter groups (count: 30, max allowed: 25)" }, { "message":"too many filters per filter group (count: 12, max allowed: 10)" }, { "message":"too many filters per filter group (count: 18, max allowed: 10)" } ], "category":"VALIDATION_ERROR" }

Developer Actions Required

  • Review and Adjust Queries: Developers should review and adjust their search queries to comply with the new limits (maximum of 25 total filters and 10 filters per group).
  • Update Error Handling: Implement or update error handling logic for the new validation error category. Ensuring applications or integrations can gracefully handle cases with the limit exceeded.

This change aims to make the error response more intuitive and grouped logically, facilitating quicker diagnostics and resolutions for developers utilizing the Search API and filtering capabilities.

Changelog Update

We are providing an important update to this recently announced enhancement to our Search API filtering capabilities, scheduled to go live on August 26th, 2024. Based on further assessments, we have decided to revise the limits on filters to ensure a safer and more stable implementation. The new limits, while still an improvement, offer a balanced approach to enhanced search functionality. For more information, please refer to the July 2024 monthly rollup announcement. 

Questions or comments? Join us in the developer forums.