List filters

If you select a SNAPSHOT or DYNAMIC list processing type when creating a list, use filters to determine which records are members of the list.

• List filters have conditional logic that is defined by filter branches which have AND or OR operation types. This is defined by the filterBranchType parameter.
• Within these branches, there are groups of individual filters that contain logic to assess records to determine if they should be included in the list. These are defined by the filterType parameter. 
• Filter branches can also have nested filter branches.

There are a variety of different filter types that can be used to build out filters in a list's filter definition. These filters types can be used together in different combinations to construct the logic that is needed for a particular list definition structure. 

HubSpot uses PASS/FAIL logic with filters to determine if a record should be in a list. If a record passes all filters, it will be a member of the list.

To determine which records pass a list's filters, the following steps occur in order:

1. Select or fetch the relevant records based on the filter selected. For example, the property values for all records being evaluated for a property filter. 
2. If applicable, use the pruningRefineBy parameter to refine the data to a specific time range (see Refine By Operation section). 
3. Apply the filtering rules against the refined data to determine if the records PASS or FAIL. For example, if the filter "First Name is equal to "John"" is selected, PASS all records that have "John" for their First Name contact property.
4. If applicable, use the coalescingRefineBy parameter to further refine the data to a specific number of occurrences. For example, the filter "contact has filled out a form at least 2 times". 
   • If a coalescingRefineBy parameter is present, then PASS records that meet the number of occurrences selected.
   • If no coalescingRefineBy parameter is present, then records PASS or FAIL based on the criteria set in step 3. 

A filter branch is a data structure used to build out the conditional logic of a list's definition. Filter branches are defined by a specific type, an operator, a list of filters, and a list of sub-branches.

The filter branch's operator OR or AND dictate how the filter branch will be evaluated relative to the rest of the branches. The list of filters and sub-filter branches determine which records will be members of a list.

• If the filter branch has an AND operator, then the record is accepted by the branch if it passes all the branch's filters and is accepted by all the sub-filter branches.
• If the filter branch has an OR operator, then the record is accepted by the branch if it passes any of the branch's filters or is accepted by any of the branch's sub-filter branches. 

A record is a member of a list if it is accepted by the root filter branch in the list definition. 

For example, to create a list of contacts who have the first name "John" OR do not have the last name "Smith", the POST body would be:

In the above example, there is one parent OR filterBranchType parameter with two nested AND filterBranchType parameters. The nested filter branches each have one filterType that sets the criteria for the list.

In the HubSpot user interface, the above code would look like the image below. Any contacts that meet either of the criteria will be a member of the list. 

To create a list of contacts who have the first name "John" and the last name "Smith":

In the above example, there is one parent OR filterBranchType with one nested AND filterBranchType. The AND filterBranchType has two filterType parameters, one for each criteria. 

In the HubSpot user interface, the above code would look like the image below. Any contacts that meet the criteria will be a member of the list. 

There are two special versions of AND filterBranchType parameters:

• UNIFIED_EVENTS: used to filter on events.
• ASSOCIATION: used to filter on records that are associated with the primary record being evaluated.

These branches should be used within an AND filter branch. For example: 

Below, review the different filterBranchType parameters that can be used to construct your list's filter definition structure.

Begin your filter definition structure with an OR filterBranchType. It is used to apply OR conditional logic against records that are accepted by the nested AND filter branches. 

OR filter branches:

• Must have one or more AND type sub-filter branches.
• Cannot have any filters.

If a record is accepted by any of its nested filter branches, an OR filter branch will accept the record as well. 

The AND filterBranchType is used as a nested filter branch within the parent OR filter branch. All filter definitions must have at least one AND filter branch for it to be valid. It is used to apply AND conditional logic against the records that pass evaluation as defined by its filters and have also been accepted by nested filter branches. 

AND filter branches:

• Can have zero or more filters.
• Can have zero or more nested UNIFIED_EVENTS and/or ASSOCIATION filterBranchType parameters.

The UNIFIED_EVENTS filterBranchType can only be used as a nested filter branch within an AND filterBranchType. It is used to determine which records have or have not completed a given unified event. 

UNIFIED_EVENTS type filter branches:

• Can have one or more PROPERTY type filters.
• Cannot have any additional filter branches.

A UNIFIED_EVENTS filter branch accepts a record if the record passes all filters on the filter branch and the criteria defined by the UNIFIED_EVENTS filter branch.

The ASSOCIATION filterBranchType can only be used as a nested filter branch within an AND filterBranchType. It is used to filter on records which are associated with the primary record being evaluated.

ASSOCIATION filter branches:

• Must have one or more filters.
• Cannot have any additional nested filter branches.

An ASSOCIATION filter branch accepts a record if it is accepted by all of its nested filter branches and if the record PASSES all filters of the filter branch.

You can only have additional filterBranches in the case of a CONTACT to LINE_ITEM association. 

Review the table below for the different types of filters that can be used. The filterType parameter is used to define the filter within the filterBranch. 

For more information, see the list filters reference page.

When filtering for records with the PROPERTY, INTEGRATION_EVENT, or  SURVEY_MONKEY_VALUE filter type, you'll include an operation object to define the parameters of the filter. This object can contain the following fields:

• operationType: the type of operator that you're filtering by (e.g., NUMBER). Each type of property supports a set of operation types, and each operation type supports a set of operators, which you'll define with the operator field. (e.g., IS and IS_NOT).
• operator: the operator that will be applied to operationType (e.g., IS and IS_NOT). Each property type supports a set of operators. Learn more about property types and their supporter operators in the table below.
• value / values: the value or values to filter by. Some operators can accept one value, while others can accept multiple values in an array.
• includeObjectsWithNoValueSet: defines how the operation should treat records that do not have a value set for the defined property.
  • If true, a record without a value for the evaluated property will be accepted.
  • If false (default), a record without a value for the evaluated property will be rejected.

For example, the filter below would filter for contacts with a firstname property value of John.

The table below gives an overview of the available operation types. For more information, along with example code, check out the property operation definitions reference.

Below, review some examples when using the TIME_POINT and TIME_RANGED parameter. These parameters can be used in both time-referenced and property-referenced requests.  For more information, see the 

The request below filters for Last activity date is equal to 03/11/2024 (EDT). 

The example below filters for Last activity date is less than 3 days ago. 

The example below filters for Last activity date is less than 5 days from now. 

The example below filters for Last activity date updated in last 7 days. 

To filter for Last activity date not updated in last 7 days, change the operator parameter to IS_NOT_BETWEEN.  

The example below filters for Last activity date is after 03/04/2024 (EST). 

The example below can either represent Last activity date is more than x days from now or Last activity date is more than x days ago. 

To filter for the latter, set the value for the offset parameter to <=0.

The example below compares the values where Last activity date is before Latest Open Lead Date. 

To filter for Last activity date is after Latest Open Lead Date: set the operator value to IS_AFTER.

To filter for when the Latest Open Lead Date was updated: set the referenceType value to UPDATED_AT. 

There are two types of refine by operations that can be used in certain filters:

• pruningRefineBy: refine the data set to a particular timeframe.
• coalescingRefineBy: determines whether the record PASSES the filter the number of times defined. 

Pruning refine by operations are used to narrow down the dataset that will be used for filter evaluation by refining the dataset to a particular timeframe. Pruning refine by operations are classified into two types: relative and absolute.

• Relative: narrow the dataset down based on a time offset of a number of days or weeks in the past or in the future.
• Absolute: narrow the dataset down based on the data being before or after a specific timestamp

For both relative and absolute refine by operations, there are ranged and comparative derivatives.

Used to narrow the relevant dataset down based on whether the timestamp of the data being evaluated is before or after a specific timestamp as defined by the refine by operation.

Used to narrow the relevant dataset down based on whether the timestamp of the data being evaluated is between or is not between an upper and lower bound timestamp as defined by the refine by operation.

Used to narrow the relevant dataset down based on whether the timestamp of the data being evaluated is before or after a certain number of days or weeks in the past or future relative to the current timestamp as defined by the refine by operation.

Used to narrow the relevant dataset down based on whether the timestamp of the data being evaluated is between or is not between an upper and lower bound time offset relative to the current timestamp. The time offsets are a certain number of days or weeks in the past or the future as defined by the refine by operation.

Coalescing refine by operations are used once the filter criteria has been applied to the relevant dataset. The only coalescing refine by operation supported by the Lists API is a “number of occurrences” operation that determines whether an object in the dataset PASSED the filter evaluation at least a minimum number of times and less than a maximum number of times.

If you're using the v1 lists API, the way that you filter lists is similar to the v3 API. However, there are minor differences in syntax and options available. Learn more about v1 list filters below.

Filter branches are AND / OR clauses that contain sets of filters and other filter branches. The only supported filterType for v1 lists is PROPERTY. Below,

For any property, filters for whether the property value is known or unknown. Available operators are: IS_KNOWN and IS_NOT_KNOWN.

Operations for string type properties.

Available operators are: IS_EQUAL_TO, IS_NOT_EQUAL_TO, CONTAINS, DOES_NOT_CONTAIN, STARTS_WITH, ENDS_WITH, HAS_EVER_BEEN_EQUAL_TO, HAS_NEVER_BEEN_EQUAL_TO, HAS_EVER_CONTAINED, HAS_NEVER_CONTAINED.

Operations for multiple string values.

Available operators are: IS_EQUAL_TO, IS_NOT_EQUAL_TO, CONTAINS, DOES_NOT_CONTAIN, STARTS_WITH, ENDS_WITH.

Operations for number type properties.

Available operators are: IS_EQUAL_TO, IS_NOT_EQUAL_TO, CONTAINS, DOES_NOT_CONTAIN, STARTS_WITH, ENDS_WITH, HAS_EVER_BEEN_EQUAL_TO, HAS_NEVER_BEEN_EQUAL_TO, IS_BETWEEN, IS_NOT_BETWEEN.

To filter for ranges, include a lowerBound and upperBound.

Operations for boolean type properties. Can only filter for a value of true or false.

Available operators are: IS_EQUAL_TO, IS_NOT_EQUAL_TO, HAS_EVER_BEEN_EQUAL_TO, HAS_NEVER_BEEN_EQUAL_TO.

Operations for enumeration type properties.

Available operators are: IS_EQUAL_TO, IS_NOT_EQUAL_TO, HAS_EVER_BEEN_ANY_OF, HAS_NEVER_BEEN_ANY_OF.

There are five different operation types for datetime properties, as set by the propertyType field:

• datetime: compares the property value to a specific datetime stamp. Available operators are: IS_EQUAL_TO, IS_BEFORE_DATE (millisecond of day's start), IS_AFTER_DATE (last millisecond of day's end).

• datetime-comparative: compares the property value to another other datetime property on the contact record. Available operators are: IS_BEFORE, IS_AFTER.

• datetime-ranged: compares the property value to a specific timestamp range. Available operators are: IS_BETWEEN, IS_NOT_BETWEEN.

• datetime-rolling: compares the property value to a rolling number of days. Available operators are: IS_LESS_THAN_X_DAYS_AGO, IS_MORE_THAN_X_DAYS_AGO, IS_LESS_THAN_X_DAYS_FROM_NOW, IS_MORE_THAN_X_DAYS_FROM_NOW.

• rolling-property-updated: compares the last time the property was updated to a rolling number of days. Available operators are: UPDATED_IN_LAST_X_DAYS, NOT_UPDATED_IN_LAST_X_DAYS.