Como usar o Lead Scoring para enriquecer e enviar seus leads para a Meta

Neste tutorial, vamos te guiar em um passo a passo de como utilizar a API de Lead Scoring da Hotmart. O objetivo é enriquecer sua base de leads, identificar aqueles com maior potencial de compra e, por fim, enviá-los para a Meta para criar públicos de alta conversão.

Authorization: Bearer SEU_ACCESS_TOKEN

Passo 1: Enriquecer Leads e enviar para a Meta

A primeira etapa consiste em enviar seus leads para a nossa API de enriquecimento. Nosso algoritmo irá analisá-los e qualificá-los com base na semelhança com seus clientes mais engajados.

Para isso, você fará uma chamada POST para a API de enriquecimento. É crucial que você inclua um webhook nesta chamada para receber o executionId, que será necessário para consultar e enviar os dados.

Caso você trabalhe com uma classificação customizada dos seus leads, pode optar por enviá-la ao invés de algum parâmetro UTM menos relevante para seu negócio (aproveitando o campo do mesmo), para que também consiga agrupar pela sua própria classificação.

Recomendamos que nessa etapa você também informe o Pixel ID e Pixel Token da Meta, para que possamos também disparar eventos customizados dos leads quentes, otimizando automaticamente o público de suas campanhas para que você atinja cada vez mais públicos com mais propensão a compra.

Request

POST https://developers.hotmart.com/send/api/v1/leadscoring/batch_enrich

Request Body

{
  "webhook": "",
  "leads": [
    {
      "email": "",
      "phone": "",
      "utm": {
        "source": "",
        "content": "",
        "campaign": "",
        "term": "",
        "medium": ""
      }
    }
    // inserir aqui até 1000 leads
  ],
  "campaign": {
    "launch_date": "(example: 2025-08-20)",
    "expected_ticket":
  },
  "meta": {
    "campaign_name": "",
    "pixel_id": "",
    "pixel_token": ""
  }
}

Retorno da Request

{
  "executionId": "0aa4cc2a-4cbf-4932-819a-e90bbbec1f45",
  "sync": false
}

Retorno do Webhook

Na request o usuário pode mandar uma url de webhook próprio "webhook": "" para receber os dados de resultado do enriquecimento. O webhook é opcional mas recomendado pois só através dele é possível identificar se houve algum erro, além disso esse retorno traz também a classificação de cada lead. Exemplo de retorno da request ao webhook.

POST <user-webhook>

{
  "leads_processed": 2,
  "execution_id": "0aa4cc2a-4cbf-4932-819a-e90bbbec1f45",
  "leads": [
    {
      "email": "producerteste1@exemplo.com",
      "phone": "996878663",
      "score": 1,
      "utm": { // valores de utm enviados pelo usuário
        "source": "<utm-source>",
        "content": "<utm-content>",
        "campaign": "<utm-campaign>",
        "term": "<utm-term>",
        "medium": "<utm-medium>"
      }
    },
    {
      "email": "producerteste3@exemplo.com",
      "phone": "+5511777777777",
      "score": 0,
      "utm": { // valores de utm enviados pelo usuário
        "source": "<utm-source>",
        "content": "<utm-content>",
        "campaign": "<utm-campaign>",
        "term": "<utm-term>",
        "medium": "<utm-medium>"
      }
    }
  ],
  "campaign": { // campanha enviada pelo usuário
    "launch_date": "<date>(example: 2025-08-20)",
    "expected_ticket": <expected-ticket>
  }
}

Passo 2: Acompanhar o Percentual de Leads Qualificados

Existem duas formas de acompanhar o percentual de leads qualificados, através da API ou através da plataforma da Hotmart. Esta etapa é útil para analisar o desempenho de suas campanhas e entender o percentual de leads qualificados (leads quentes).

1. Acompanhar via API

Com o executionId em mãos, você pode consultar os resultados do enriquecimento. Para isso, utilize o endpoint GET /report. Você pode passar filtros opcionais como parâmetros na URL para refinar sua busca. Os filtros disponíveis são:

• execution_id (o execution_id retornado no Passo 1)
• lead_utm_campaign
• lead_utm_source
• lead_utm_medium
• lead_utm_term
• lead_utm_content
• meta_campaign_name

Request de Exemplo

GET https://developers.hotmart.com/send/api/v1/leadscoring/report?execution_id=v3vdF5Z4UA-DqmmKfr7pq&lead_utm_source=facebook

Retorno

{
  "unique_leads": 150,
  "unique_hot_leads": 30,
  "unique_hot_leads_percentage": 0.2,
  "leads_processed": 150
}

2. Acompanhar via Plataforma

Com os leads enviados para o enriquecimento, é possível consultar o resultado através dodashboard de Lead Scoring.Esse dashboard vai conter todos os enriquecimentos realizados, podendo filtrar pelas UTMs configuradas para os leads.

Além de ser mais fácil por não precisar usar o execution_id, também é possível exportar as informações.

Pronto! Seguindo esses passos, você terá um fluxo completo de qualificação de leads integrado com suas campanhas da Meta, potencializando seus resultados.