Skip to main content

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.

All filter definitions must start with a root-level OR filterBranchType (see filter branch types for more details). This root level OR filter branch must then have one or more AND sub-filter branches.

The root-level OR filter branch can be thought of as the parent filter branch while the AND sub-filter branches can be thought of as child filter groups. Together, these branches make up the base filter branch structure.

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.

and-or-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.

and-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.
  • C annot 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.

An AND filter branch accepts a record if the record is accepted by all of its nested filter branches and the record passes all filters in the filter branch.

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.

ParameterAccepted Values
operatorHAS_COMPLETED, HAS_NOT_COMPLETED

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.

ParameterAccepted Values
operatorIN_LIST
associationCategoryHUBSPOT_DEFINED, USER_DEFINED, INTEGRATOR_DEFINED

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.

ParameterDescription
ADS_TIMEEvaluates whether a contact has seen any ads in the timeframe defined by the pruningRefineBy parameter.
ADS_SEARCHEvaluates whether a contact has performed the ad interactions as defined by the filter.
CTAEvaluates whether a contact has or has not interacted with a specific call-to-action as defined by the filter.
EMAIL_EVENTEvaluate the opt-in status of a contact for specific email subscriptions as defined by the filter.
EVENTEvaluates whether a contact has or does not have a specific event as defined by the filter.
FORM_SUBMISSIONEvaluates whether a contact has or has not filled out a specific form or any form as defined by the filter.
FORM_SUBMISSION_ON_PAGEEvaluates whether a contact has or has not filled out a specific or any form on a specific page as defined by the filter.
IN_LISTEvaluates whether a record is or is not a member of a specific list, import, or workflow as defined by the filter.
PAGE_VIEWEvaluates whether a contact has or has not viewed a specific page as defined by the filter.
PRIVACYEvaluates whether a contact does or does not have privacy consent for a specific privacy type as defined by the filter.
PROPERTYEvaluates whether a record’s property value satisfies the property filter operation as defined by the filter. See the property filter operations section for more details.
SURVEY_MONKEYEvaluates whether a contact has or has not responded to a specific Survey Monkey survey as defined by the filter.
SURVEY_MONKEY_VALUEEvaluates whether a contact has or has not responded to a specific Survey Monkey survey’s question with a specified value as defined by the filter.
WEBINAREvaluates whether a contact has or has not registered or attended any webinars or a specific webinar as defined by the filter.
INTEGRATION_EVENTIntegration event filters can be used to filter specific contacts based on whether or not they have interacted with integration events that have properties as specified by the filter lines.

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.

OperationTypeSupported operatorsDescription
ALL_PROPERTYStringUsed to determine whether a property value is known or is unknown as defined by the property operation.
BOOLStringUsed to determine whether a current (or historical) boolean property value is or is not (or has or has not) equaled a specific value.
ENUMERATIONStringUsed to determine whether an enumeration/multi-select property value is any of, is none of, is exactly, is not exactly, contains all of, does not contain all of, has ever been any of, has never been any of, has ever been exactly, has never been exactly, has ever contained all, or has never contained all of a given set of values as defined by the property operation.
MULTISTRINGStringUsed to determine whether a string property value is equal to, is not equal to, contains, does not contain, starts with, or ends with any of a given set of values as defined by the property operation.
NUMBERStringUsed to determine whether a current (or historical) number property value is or is not (or has or has not) equaled a specific value as defined by the property operation.
STRINGStringUsed to determine whether a current (or historical) string property value is or is not (or has or has not) equaled a specific value as defined by the property operation.
TIME_POINTStringUsed to determine if a property has been updated before or after a specific time. That time can be specified as a specific date or relative to the current day. This operation also allows the comparison of two properties or their last updated time.
TIME_RANGEDStringUsed to determine if a property has been updated between or outside of two specific times. These times can be specified as a specific date or relative to the current day.

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.

ParameterDescription
comparisonWhether the data's timestamp is before or after the defined timestamp. Values include:BEFORE, AFTER

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.

ParameterDescription
rangeTypeWhether the data's timestamp is between or not between the defined lowerTimestampand upperTimestamp. Values include:BETWEEN, NOT_BETWEEN

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.

ParameterDescription
comparisonWhether the data's timestamp is before or after the defined timeOffset values. Values include: BEFORE, AFTER
offsetDirectionValues include:PAST, FUTURE
timeUnitValues include:DAYS, WEEKS
amountA number value.

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.

ParameterDescription
rangeTypeWhether the data's timestamp is between or not between the defined timeOffset values. Values include: BETWEEN, NOT_BETWEEN
offsetDirectionValues include:PAST, FUTURE
timeUnitValues include:DAYS, WEEKS
amountA number value.

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.

ParameterDescription
NUM_OCCURRENCESUsed to determine whether an object in the relevant dataset PASSED the filter evaluation at least a minimum number of times (or zero times if a minimum is not provided) and at most a maximum number of times (or any number of times if a maximum is not provided) as defined by the refine by operation.

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.