Skip to main content
Humm reads your HubSpot contacts, companies, deals, and custom objects. Ask which deals are stalling, which accounts haven’t had activity in 30 days, or what your stage conversion looks like this quarter.

​
Tools

ToolDescription
HUBSPOT_READ_OWNERSList owners (users) to find IDs for record associations
HUBSPOT_SEARCH_COMPANIESSearch companies with advanced filtering and sorting
HUBSPOT_SEARCH_DEALSSearch deals with advanced filtering and sorting
HUBSPOT_SEARCH_CONTACTSSearch contacts with advanced filtering and sorting
HUBSPOT_LIST_OBJECTSList records for any object type with pagination
HUBSPOT_READ_RECORDSRead one or more records by ID with optional associations
HUBSPOT_SEARCH_OBJECTSGeneric search for any object type with filters
HUBSPOT_QUERY_ASSOCIATIONSBatch query associations between object types
HUBSPOT_LIST_PROPERTIESList available properties for an object type
HUBSPOT_LIST_SCHEMASList custom object schemas to discover objectTypeIds

​
Filter Groups Syntax

Humm uses HubSpot’s filterGroups structure for advanced searches. Here’s how it works:

​
Logic

  • Within a filter group: Conditions are combined with AND
  • Across filter groups: Groups are combined with OR

​
Structure

{
  "filterGroups": [
    {
      "filters": [
        {"propertyName": "email", "operator": "CONTAINS_TOKEN", "value": "@acme.com"},
        {"propertyName": "lifecyclestage", "operator": "CONTAINS_TOKEN", "value": "customer"}
      ]
    }
  ]
}

​
Operators

OperatorDescriptionValue Type
EQEqual to (use for strings/numbers, not enumeration properties)value
NEQNot equal tovalue
LT / LTELess than / Less than or equalvalue
GT / GTEGreater than / Greater than or equalvalue
BETWEENWithin range (inclusive)value + highValue
IN / NOT_INIn list / Not in listvalues array
HAS_PROPERTYProperty has a valuenone
NOT_HAS_PROPERTYProperty has no valuenone
CONTAINS_TOKENContains token (preferred for enumeration properties)value
NOT_CONTAINS_TOKENDoes not contain tokenvalue

​
Enumeration Properties

Certain HubSpot properties are “enumeration” types internally and require special handling:
  • hubspot_owner_id
  • dealstage
  • pipeline
  • lifecyclestage
For these properties, use CONTAINS_TOKEN instead of EQ. Using EQ often returns no results. 
// Correct - use CONTAINS_TOKEN for enumeration properties
{"propertyName": "hubspot_owner_id", "operator": "CONTAINS_TOKEN", "value": "12345"}
{"propertyName": "dealstage", "operator": "CONTAINS_TOKEN", "value": "closedwon"}

// Wrong - EQ often fails for enumeration properties
{"propertyName": "hubspot_owner_id", "operator": "EQ", "value": "12345"}

​
Query Examples

​
Search companies by owner

{
  "filterGroups": [
    {
      "filters": [
        {"propertyName": "hubspot_owner_id", "operator": "CONTAINS_TOKEN", "value": "12345678"}
      ]
    }
  ],
  "properties": ["name", "domain", "hubspot_owner_id"],
  "limit": 50
}

​
Search deals in a specific stage

{
  "filterGroups": [
    {
      "filters": [
        {"propertyName": "dealstage", "operator": "CONTAINS_TOKEN", "value": "closedwon"}
      ]
    }
  ],
  "sorts": [{"propertyName": "closedate", "direction": "DESCENDING"}],
  "properties": ["dealname", "amount", "closedate"],
  "limit": 100
}

​
Search contacts by email domain

{
  "filterGroups": [
    {
      "filters": [
        {"propertyName": "email", "operator": "CONTAINS_TOKEN", "value": "@acme.com"}
      ]
    }
  ],
  "properties": ["firstname", "lastname", "email"],
  "limit": 50
}

​
Combined filters (AND logic within group)

{
  "filterGroups": [
    {
      "filters": [
        {"propertyName": "pipeline", "operator": "CONTAINS_TOKEN", "value": "default"},
        {"propertyName": "amount", "operator": "GTE", "value": "50000"}
      ]
    }
  ]
}

​
Multiple filter groups (OR logic across groups)

{
  "filterGroups": [
    {
      "filters": [
        {"propertyName": "lifecyclestage", "operator": "CONTAINS_TOKEN", "value": "customer"}
      ]
    },
    {
      "filters": [
        {"propertyName": "email", "operator": "CONTAINS_TOKEN", "value": "@partner.com"}
      ]
    }
  ]
}

​
Custom Objects

HubSpot supports custom objects with unique schemas. To work with custom objects:
  1. Discover schemas: Use HUBSPOT_LIST_SCHEMAS to list all custom object schemas and their objectTypeId values (e.g., 2-123456)
  2. List properties: Use HUBSPOT_LIST_PROPERTIES with the objectTypeId to see available fields
  3. Query records: Use HUBSPOT_LIST_OBJECTS or HUBSPOT_SEARCH_OBJECTS with the objectTypeId as the object_type
// List custom object records
{"object_type": "2-123456", "limit": 50, "properties": ["name", "custom_code"]}

// Search custom objects
{
  "object_type": "2-123456",
  "filterGroups": [
    {
      "filters": [
        {"propertyName": "custom_code", "operator": "CONTAINS_TOKEN", "value": "ABC-"}
      ]
    }
  ]
}

​
Authentication

OAuth

Connect securely via HubSpot OAuth. Authorize Humm to access your HubSpot portal.