Pular para conteúdo

HUBSPOT_CONTACT_SEARCH - Buscar Contatos por Filtros

O que é este Node?

O HUBSPOT_CONTACT_SEARCH é o node responsável por buscar contatos usando filtros avançados no HubSpot CRM, permitindo encontrar contatos por email, nome, empresa, propriedades customizadas e mais.

Por que este Node existe?

Encontrar contatos específicos sem saber o ID é essencial. O HUBSPOT_CONTACT_SEARCH existe para:

  1. Busca por Email: Encontrar contato pelo email antes de criar/atualizar (evita duplicatas)
  2. Filtros Complexos: Buscar contatos que atendem múltiplos critérios
  3. Segmentação: Encontrar grupos de contatos com características específicas
  4. Verificação de Existência: Checar se contato já existe antes de criar novo

Como funciona internamente?

Quando o HUBSPOT_CONTACT_SEARCH é executado, o sistema:

  1. Recebe os filtros: Critérios de busca (email, nome, properties, etc.)
  2. Processa variáveis: Substitui variáveis do contexto
  3. Monta query: Cria filterGroups compatível com API HubSpot
  4. Autentica na API: Usa Bearer Token
  5. Faz requisição POST: Busca em /crm/v3/objects/contacts/search
  6. Retorna resultados: Lista de contatos que atendem os filtros
  7. Aplica limite: Retorna até limite configurado (padrão: 100)

Código interno (hubspot.executor.ts:90-98): 

case 'search': {
  const filters = JSON.parse(this.replaceVariables(JSON.stringify(data.filters), context.variables));
  const response = await axios.post(
    `${baseUrl}/search`,
    { filterGroups: filters, limit: data.limit || 100 },
    { headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' } }
  );
  return response.data;
}

Quando você DEVE usar este Node?

Use HUBSPOT_CONTACT_SEARCH quando precisar encontrar contatos por critérios:

Casos de uso

  1. Buscar por email: Verificar se email já existe antes de criar contato
  2. Encontrar por empresa: Listar todos contatos de uma empresa
  3. Filtrar por status: Buscar leads em estágio específico
  4. Segmentação: Encontrar contatos que atendem múltiplos critérios
  5. Deduplicação: Identificar duplicatas antes de criar
  • Já tem o ID: Use HUBSPOT_CONTACT_GET diretamente
  • Quer todos os contatos: Use HUBSPOT_CONTACT_LIST (mais simples)
  • Busca muito ampla: Liste primeiro e filtre depois

Parâmetros

Campo Tipo Obrigatório Descrição
resource string Sim Deve ser "contacts"
operation string Sim Deve ser "search"
config.apiKey string Sim API Key do HubSpot
filters array Sim Array de filterGroups (ver formato abaixo)
limit number Não Máximo de resultados (padrão: 100)
responseVariable string Não Variável para resultado

Formato de Filters

{
  "filters": [
    {
      "filters": [
        {
          "propertyName": "email",
          "operator": "EQ",
          "value": "joao@empresa.com"
        }
      ]
    }
  ]
}

Operadores disponíveis: - EQ (equals): Igual a - NEQ (not equal): Diferente de - LT (less than): Menor que - GT (greater than): Maior que - CONTAINS: Contém - NOT_CONTAINS: Não contém

Exemplo 1: Buscar Contato por Email

Objetivo: Verificar se email já existe antes de criar contato

JSON para Importar

{
  "name": "HubSpot - Buscar por Email",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "email_1",
      "type": "email",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Coletar Email",
        "parameters": {
          "message": "Digite seu email:",
          "variableName": "user_email"
        }
      }
    },
    {
      "id": "hubspot_1",
      "type": "hubspot",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Buscar Email",
        "parameters": {
          "resource": "contacts",
          "operation": "search",
          "config": {
            "apiKey": "{{hubspot_api_key}}"
          },
          "filters": [
            {
              "filters": [
                {
                  "propertyName": "email",
                  "operator": "EQ",
                  "value": "{{user_email}}"
                }
              ]
            }
          ],
          "limit": 1,
          "responseVariable": "search_result"
        }
      }
    },
    {
      "id": "condition_1",
      "type": "condition",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Verificar se Existe",
        "parameters": {
          "variable": "{{search_result.total}}",
          "operator": "greater_than",
          "value": "0"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 900, "y": 50 },
      "data": {
        "label": "Já Existe",
        "parameters": {
          "message": "Encontramos seu cadastro! Bem-vindo de volta, {{search_result.results.0.properties.firstname}}!"
        }
      }
    },
    {
      "id": "message_2",
      "type": "message",
      "position": { "x": 900, "y": 150 },
      "data": {
        "label": "Novo",
        "parameters": {
          "message": "Email não encontrado. Vamos criar seu cadastro!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "email_1" },
    { "source": "email_1", "target": "hubspot_1" },
    { "source": "hubspot_1", "target": "condition_1" },
    { "source": "condition_1", "target": "message_1", "label": "true" },
    { "source": "condition_1", "target": "message_2", "label": "false" },
    { "source": "message_1", "target": "end_1" },
    { "source": "message_2", "target": "end_1" }
  ]
}

Exemplo 2: Buscar Contatos de Uma Empresa

Objetivo: Listar todos os contatos de uma empresa específica

JSON para Importar

{
  "name": "HubSpot - Buscar por Empresa",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Nome Empresa",
        "parameters": {
          "message": "Digite o nome da empresa:",
          "variableName": "company_name"
        }
      }
    },
    {
      "id": "hubspot_1",
      "type": "hubspot",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Buscar Contatos",
        "parameters": {
          "resource": "contacts",
          "operation": "search",
          "config": {
            "apiKey": "{{hubspot_api_key}}"
          },
          "filters": [
            {
              "filters": [
                {
                  "propertyName": "company",
                  "operator": "EQ",
                  "value": "{{company_name}}"
                }
              ]
            }
          ],
          "limit": 50,
          "responseVariable": "company_contacts"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Resultado",
        "parameters": {
          "message": "Encontrados {{company_contacts.total}} contatos da empresa {{company_name}}."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "hubspot_1" },
    { "source": "hubspot_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Resposta do Node

{
  "total": 2,
  "results": [
    {
      "id": "12345678901",
      "properties": {
        "email": "joao@empresa.com",
        "firstname": "João",
        "lastname": "Silva",
        "company": "TechCorp"
      }
    },
    {
      "id": "12345678902",
      "properties": {
        "email": "maria@empresa.com",
        "firstname": "Maria",
        "lastname": "Santos",
        "company": "TechCorp"
      }
    }
  ]
}

Boas Práticas

✅ SIM: - Use search para verificar existência antes de criar - Limite resultados apropriadamente (evite carregar 1000+ contatos) - Verifique total antes de acessar results[0] - Use filtros específicos para melhor performance - Combine múltiplos filtros para busca precisa

❌ NÃO: - Buscar sem filtros (use LIST ao invés) - Assumir que results sempre existe - Fazer searches repetitivas em loop - Usar como listagem geral

Dicas

💡 Dica 1: Use search_result.total > 0 em CONDITION para verificar se encontrou resultados antes de acessar.

💡 Dica 2: Acesse primeiro resultado com {{search_result.results.0.properties.fieldname}}.

💡 Dica 3: Combine filtros usando múltiplos objetos no array filters para busca AND.

Próximos Nodes

→ HUBSPOT_CONTACT_GET - Buscar contato por ID depois de encontrar → HUBSPOT_CONTACT_CREATE - Criar se não encontrar → HUBSPOT_CONTACT_LIST - Listar todos os contatos