HubSpot - Buscar objetos

↩ Parte de la integración HubSpot.

Descripción

Busca registros de un tipo de objeto con el endpoint de búsqueda de HubSpot (POST /crm/v3/objects/{object_type}/search) y devuelve el array results.

Es el nodo con el que respondés “¿este contacto ya existe?” antes de crear un duplicado, o con el que traés “todos los negocios que cierran este mes”. El cuerpo de la búsqueda lo escribís en JSON, tal como lo documenta HubSpot.

Configuración

Campo	Tipo	Obligatorio	Descripción
`credentials_id`	credentials	Sí	Credencial de HubSpot
`object_type`	text	Sí	Tipo de objeto: `contacts`, `companies`, `deals`, `tickets`. Si lo dejás vacío se usa `contacts`
`search`	json	Sí	Cuerpo de búsqueda: `filterGroups`, `query`, `sorts`, `properties`, `limit`

Los dos parámetros aceptan variables dinámicas; el texto de search se resuelve antes de parsearse como JSON, así que podés inyectar {{data.email}} dentro del valor de un filtro.

El cuerpo de la búsqueda

Clave	Para qué sirve
`filterGroups`	Array de grupos. Los filtros dentro de un grupo se combinan con AND, y los grupos entre sí con OR. Cada filtro es `{ propertyName, operator, value }`
`query`	Búsqueda de texto libre sobre las propiedades indexadas del objeto
`sorts`	Array del estilo `[{"propertyName":"createdate","direction":"DESCENDING"}]`
`properties`	Array con los nombres de las propiedades a devolver
`limit`	Resultados por página (máx. 100)

Operadores habituales: EQ, NEQ, LT, LTE, GT, GTE, BETWEEN, IN, NOT_IN, HAS_PROPERTY, NOT_HAS_PROPERTY, CONTAINS_TOKEN.

Credenciales

Este módulo necesita una credencial de HubSpot:

Campo	Descripción
`token`	Token de la Private App (empieza con `pat-`), desde HubSpot → Settings → Integrations → Private Apps

Salida

data es el array de registros coincidentes:

[
  {
    "id": "701",
    "properties": {
      "email": "ana@acme.com",
      "firstname": "Ana",
      "createdate": "2026-08-05T10:00:00.000Z",
      "hs_object_id": "701"
    },
    "createdAt": "2026-08-05T10:00:00.000Z",
    "updatedAt": "2026-08-05T11:22:00.000Z",
    "archived": false
  }
]

El total de coincidencias (no solo las de la página) viaja en _meta:

{ "moduleVersion": "1.0.0", "success": true, "count": 1, "total": 1, "objectType": "contacts", "totalMs": 320 }

Una búsqueda sin resultados devuelve [] y count: 0, no un error. Ramificá según _meta.count (o según la longitud del array) para decidir entre crear y actualizar.

Ejemplo de uso

Encontrar un contacto por email

{
  "credentials_id": "hubspot_marketing",
  "object_type": "contacts",
  "search": {
    "filterGroups": [
      { "filters": [{ "propertyName": "email", "operator": "EQ", "value": "{{data.email}}" }] }
    ],
    "properties": ["email", "firstname", "lastname", "lifecyclestage"],
    "limit": 1
  }
}

Negocios de más de 10.000 todavía abiertos

{
  "credentials_id": "hubspot_ventas",
  "object_type": "deals",
  "search": {
    "filterGroups": [
      {
        "filters": [
          { "propertyName": "amount", "operator": "GT", "value": "10000" },
          { "propertyName": "dealstage", "operator": "NEQ", "value": "closedlost" }
        ]
      }
    ],
    "sorts": [{ "propertyName": "amount", "direction": "DESCENDING" }],
    "properties": ["dealname", "amount", "dealstage", "closedate"],
    "limit": 50
  }
}

Búsqueda libre sobre empresas

{
  "credentials_id": "hubspot_marketing",
  "object_type": "companies",
  "search": {
    "query": "{{data.termino}}",
    "properties": ["name", "domain", "city"],
    "limit": 20
  }
}

Notas

Los filtros dentro de un mismo grupo se combinan con AND; los grupos entre sí, con OR. Un único grupo con dos filtros significa “las dos condiciones a la vez”.
Los valores siempre se envían como cadenas, incluidos números y fechas: "10000", no 10000. Las fechas van en ISO 8601 o como marca de tiempo en milisegundos.
El limit máximo es 100, y HubSpot limita además el total de resultados paginables por búsqueda; conviene acotar los filtros antes que paginar sin fin.
El índice de búsqueda de HubSpot es eventualmente consistente: un registro creado segundos antes puede no aparecer todavía. Si lo acabás de crear, leelo por id con Leer objeto.
Si search está vacío o no parsea como JSON, el nodo se detiene con un error de validación antes de llamar a HubSpot.

Nodos relacionados

HubSpot: Crear objeto — creá el registro cuando la búsqueda no devuelve nada.
HubSpot: Actualizar objeto — actualizá el registro cuando ya existe.
HubSpot: Listar objetos — recorré todo el tipo de objeto cuando no necesitás filtros.