There's a new version of the HubSpot API

We're also working on a new documentation website, you're invited to check it out and give us your feedback.

Contact Lists API Overview

Contact lists are used to segment contacts into groups.  There are two main types of lists: dynamic (usually referred to as "active") and static.

Dynamic lists

Dynamic lists automatically add or remove contacts based on the list criteria. List membership is managed automatically and is updated whenever data changes for a contact. This means contacts can't be manually added or removed from a dynamic list.

Static lists

Static lists can also automatically include contacts, but only when the list is first created. After that, list membership won't change unless contacts are manually added or removed.

Syncing records

When syncing contact records through an integration, lists can be used to filter which records you're syncing. A dynamic list could be created to only include contacts with properties that matter to your integration (and you can use the API to poll for contacts in that list) instead of pulling all contacts and then filtering for that criteria separately.

More details about lists can be found in the here

Each list record will contain the following data. See creating a list for more details about the different filters that can be used.

{
  "parentId": 0,
      // Integer, read-only; The ID of the folder that the list belongs to.  Currently folders can only be managed in the HubSpot app.
  "dynamic": true,
      // Boolean; true if the list is a dynamic (active) list, false if static.
  "metaData": {
    "processing": "DONE",
        // String, read-only, one of DONE, REFRESHING, INITIALIZING, or PROCESSING;
        // DONE indicates the list has finished processing, any other value indicates that list membership is being evaluated.
    "size": 201,
        // Integer, read-only; The approximate number of contacts in the list.
    "error": "",
        // String, read-only; Any errors that happened the last time the list was processed.
    "lastProcessingStateChangeAt": 1477518645996,
        // Integer, read-only; A Unix timestamp (in milliseconds) of the last time that the processing state changed.
    "lastSizeChangeAt": 1479413042495
        // Integer, read-only; A Unix timestamp (in milliseconds) of the last time that the size of the list changed.
        // A value of 0 indicates that the list hasn't changed size since its creation.
  },
  "name": "test emails",
      // String; The name of the list.
  "filters": [
      // This is a list of filters used to determine list membership. See creating a list for more details.
      // This field may be an empty list, for lists with no criteria.
    [
      {
        "withinTimeMode": "PAST",
        "checkPastVersions": false,
        "filterFamily": "PropertyValue",
        "type": "string",
        "property": "email",
        "value": "test",
        "operator": "STR_STARTS_WITH"
      }
    ]
  ],
  "portalId": 62515,
      // Integer, read-only; The Hud ID that the list belongs to.
  "createdAt": 1335448813688,
      // Integer, read-only; A Unix timestamp (in milliseconds) of the time the list was created.
  "listId": 1,
      // Integer, read-only; The unique ID of the list.  This ID will not change, and should always be used to reference the list.
  "updatedAt": 1477944356444,
      // Integer, read-only; A Unix timestamp (in milliseconds) of the time that the list was last modified.
  "listType": "DYNAMIC",
      // String, read-only, one of DYNAMIC or STATIC;
      // DEPRECATED, use the 'dynamic' field to determine if the list is dynamic or static.
  "internalListId": 220441,
      // Integer, read-only; DEPRECATED, this is an internal field and should not be used. Use the 'listId' to reference the list.
  "deleteable": true
      // Boolean, read-only; If this is false, this is a system list and cannot be deleted.
      // This value may not be present for all lists. In those cases, this value may be treated as true (the list may be deleted).
      // When this value is true, you may still get an error deleting the list if it's in use by other lists or workflows.
      // See the documentation for deleting a list for more details.
}

Filter Branches

Filter branches are AND / OR clauses that contain sets of filters and other filter branches.

   "filterBranch":{
"filterBranchType":"AND",
"filters":[
{
"property":"amount",
"operation":{
"value":50,
"operator":"IS_GREATER_THAN",
"propertyType":"number"
},
"filterType":"PROPERTY"
}
],
"filterBranches":[
],
}

Property Filters

The only supported filter type to start is a Property Filter. Property Filters are defined as:

{
"filterType": "PROPERTY",
"property": "the_property_name",
"operation": {
...
}
}

All Property Types Operations

{
"filterType": "PROPERTY",
"property": "any_property",
"operation": {
"propertyType": "alltypes",
"operator": "IS_KNOWN"
}
}

Operators: IS_KNOWN, IS_NOT_KNOWN

String Operations

{
"filterType": "PROPERTY",
"property": "string_property_name",
"operation": {
"propertyType": "string",
"operator": "CONTAINS",
"value": "def"
}
}

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

Multi-String Operations

{
"filterType": "PROPERTY",
"property": "string_property_name",
"operation": {
"propertyType": "multistring",
"operator": "CONTAINS",
"values": ["def", "abc", "123"]
}
}

Operators: IS_EQUAL_TO, IS_NOT_EQUAL_TO, CONTAINS, DOES_NOT_CONTAIN, STARTS_WITH, ENDS_WITH

Historical versions of all these operators are available.

{
"filterType": "PROPERTY",
"property": "string_property_name",
"operation": {
"propertyType": "multistring",
"operator": "CONTAINS",
"values": ["def", "abc", "123"],
"pruningRefineBy": {"type": "AllHistoryRefineBy"}
}
}

By default, this will use HAS_EVER type semantics for positive operators (e.g. a single match in the history will INCLUDE) and HAS_NEVER type semantics for negative operators (e.g. a single match in the history will EXCLUDE). This can be overridden, but api is still in flux; documentation coming as it settles down

Number Operations

{
"filterType": "PROPERTY",
"property": "number_property_name",
"operation": {
"propertyType": "number",
"operator": "IS_GREATER_THAN",
"value": 100
}
}

Operators: IS_EQUAL_TO, IS_NOT_EQUAL_TO, IS_GREATER_THAN, IS_GREATER_THAN_OR_EQUAL_TO, IS_LESS_THAN, IS_LESS_THAN_OR_EQUAL_TO, HAS_EVER_BEEN_EQUAL_TO, HAS_NEVER_BEEN_EQUAL_TO

  • Ranged operations
{
"filterType": "PROPERTY",
"property": "datetime_property_name",
"operation": {
"propertyType": "number-ranged",
"operator": "IS_BETWEEN",
"lowerBound": 0,
"upperBound": 10
}
}

Operators: IS_BETWEEN, IS_NOT_BETWEEN

Boolean Property Operations

{
"filterType": "PROPERTY",
"property": "boolean_property_name",
"operation": {
"propertyType": "bool",
"operator": "IS_EQUAL_TO",
"value": true
}
}

Operations: IS_EQUAL_TO, IS_NOT_EQUAL_TO, HAS_EVER_BEEN_EQUAL_TO, HAS_NEVER_BEEN_EQUAL_TO Values: true, false

Enumeration Property Operations

{
"filterType": "PROPERTY",
"property": "enumeration_property_name",
"operation": {
"propertyType": "enumeration",
"operator": "IS_ANY_OF",
"values": [
"abc",
"def",
"xyz"
]
}
}

Operations: IS_ANY_OF, IS_NONE_OF, HAS_EVER_BEEN_ANY_OF, HAS_NEVER_BEEN_ANY_OF

Datetime Property Operations

There are three different operation types for datetime properties to better distinguish the necessary criteria of each.

  • Datetime property operations
{
"filterType": "PROPERTY",
"property": "datetime_property_name",
"operation": {
"propertyType": "datetime",
"operator": "IS_EQUAL_TO",
"timestamp": 1504703360618
}
}

Operator: IS_EQUAL_TO, IS_BEFORE_DATE, IS_AFTER_DATE

timestamp must follow the same guidelines as contact lists for IS_BEFORE_DATE (millisecond of day's start) and IS_AFTER_DATE (last millisecond of day's end).

  • Comparative operations
{
"filterType": "PROPERTY",
"property": "datetime_property_name",
"operation": {
"propertyType": "datetime-comparative",
"operator": "IS_AFTER",
"comparisonPropertyName": "xyz"
}
}

Operations: IS_BEFORE, IS_AFTER Comparison property names: property name of any other date/datetime property on the object record

  • Ranged operations
{
"filterType": "PROPERTY",
"property": "datetime_property_name",
"operation": {
"propertyType": "datetime-ranged",
"operator": "IS_BETWEEN",
"lowerBoundTimestamp": 1,
"upperBoundTimestamp": 2
}
}

Operations: IS_BETWEEN, IS_NOT_BETWEEN

  • Rolling Filters
{
"filterType": "PROPERTY",
"property": "datetime_property_name",
"operation": {
"propertyType": "datetime-rolling",
"operator": "IS_LESS_THAN_X_DAYS_AGO"
"numberOfDays": 5,
}
}

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

Evaluates whether property value has been changed or unchanged for a certain period of time.

  • Datetime property operations
{
"filterType": "PROPERTY",
"property": "any_property",
"operation": {
"propertyType": "rolling-property-updated",
"operator": "UPDATED_IN_LAST_X_DAYS",
"numberOfDays": 3
}
}

Operator: UPDATED_IN_LAST_X_DAYS, NOT_UPDATED_IN_LAST_X_DAYS

Docs for this API