Leads

A API nunca cria leads como efeito colateral de um envio: se o destinatário não existe, o envio falha com 404 lead_not_found. Criar lead é sempre uma ação explícita sua.

Buscar um lead

Por telefone (aceita E.164 ou apenas dígitos):

curl "https://api.superlead.app/v1/leads?phone=%2B5511999999999" \
  -H "Authorization: Bearer sk_SUA_CHAVE"

Em query string, o + precisa ser codificado como %2B — um + cru vira espaço. Alternativa: mande só os dígitos (?phone=5511999999999).

Por id (o lead_... retornado na criação):

curl https://api.superlead.app/v1/leads/lead_0b5f8a3e-1a2b-3c4d-5e6f-7a8b9c0d1e2f \
  -H "Authorization: Bearer sk_SUA_CHAVE"

As duas formas retornam o mesmo recurso:

{
  "id": "lead_0b5f8a3e-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "name": "João Silva",
  "phone": "+5511999999999",
  "source": "Meta Ads",
  "channel": "WhatsApp",
  "entry_point": "ctwa",
  "funnel_stage": "1º Contato",
  "created_at": "2026-06-01T12:00:00.000Z"
}

Números brasileiros: a busca por telefone testa automaticamente a variação do nono dígito, então funciona com ou sem o 9 após o DDD.

Criar um lead

curl -X POST https://api.superlead.app/v1/leads \
  -H "Authorization: Bearer sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "phone": "+5511999999999",
    "source": "Indicação"
  }'

Campos:

Campo	Obrigatório	Descrição
`name`	Sim	Nome do lead (até 200 caracteres).
`phone`	Sim	Telefone em E.164, por exemplo `+5511999999999`.
`source`	Não	Origem do lead. Sem valor, entra como `Não Rastreado`.
`channel`	Não	Canal de origem (por exemplo `WhatsApp`).
`entry_point`	Não	Ponto de entrada da conversão.
`email`	Não	E-mail do lead.
`notes`	Não	Observações livres (até 2000 caracteres).
`utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`	Não	Parâmetros de atribuição.

O lead criado entra na primeira etapa do funil da empresa. Se a empresa não tem funil configurado no painel, a resposta é 422 funnel_not_configured.

Telefone duplicado

Se já existe um lead com esse telefone na sua empresa, a resposta é 409 lead_already_exists. Nesse caso, recupere o lead existente com a busca por telefone — e envie a mensagem normalmente, já que o envio só precisa do telefone em to.

Fluxo recomendado: garantir lead antes do envio

Busque pelo telefone

GET /v1/leads?phone=.... Se retornar 200, o lead existe — siga para o envio.

Se 404, crie o lead

POST /v1/leads com nome e telefone. Trate 409 como sucesso (outra automação pode ter criado o lead entre as duas chamadas).

Envie a mensagem

POST /v1/whatsapp/messages com o telefone em to.

Editando um lead

Atualize dados cadastrais com PATCH /v1/leads/{id} — envie só o que mudou. Campo omitido fica como está; null explícito limpa o campo.

curl -X PATCH https://api.superlead.app/v1/leads/lead_0b5f8a3e-... \
  -H "Authorization: Bearer sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "email": "joao@empresa.com",
    "document": "123.456.789-01",
    "cep": "01310-100",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR"
  }'

Campos editáveis: name, email, notes, source, channel, entry_point, utm_*, document + document_type (CPF ou CNPJ — enviando só document, o tipo é inferido pelo tamanho), cep, address, address_number, address_complement, neighborhood, city, state, country.

Telefone e etapa do funil não são editáveis por aqui. O telefone é a identidade WhatsApp do lead. A etapa muda pelo endpoint próprio abaixo — que registra o histórico da transição.

Movendo o lead de etapa

Primeiro, descubra as etapas da sua empresa (os ids são estáveis — sobrevivem a renomear a etapa no painel):

curl https://api.superlead.app/v1/funnel/stages \
  -H "Authorization: Bearer sk_SUA_CHAVE"

{
  "data": [
    { "id": "stage_3", "name": "1º Contato", "order": 0, "is_first_contact": true, "is_sale": false, "color": "#4CAF50" },
    { "id": "stage_7", "name": "Qualificado", "order": 1, "is_first_contact": false, "is_sale": false, "color": "#2196F3" }
  ]
}

Depois, mova com PUT /v1/leads/{id}/stage:

curl -X PUT https://api.superlead.app/v1/leads/lead_0b5f8a3e-.../stage \
  -H "Authorization: Bearer sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "stage_id": "stage_7", "reason": "respondeu no site" }'

{
  "lead_id": "lead_0b5f8a3e-...",
  "previous_stage": { "id": "stage_3", "name": "1º Contato" },
  "current_stage": { "id": "stage_7", "name": "Qualificado" },
  "changed": true,
  "moved_at": "2026-07-06T12:00:00.000Z"
}

Idempotente: mover para a etapa em que o lead já está retorna 200 com changed: false — sem log duplicado. Seguro para retries.
Histórico completo: a transição fica registrada no painel (origem API), com o reason como observação. Pular etapas registra as intermediárias automaticamente.
stage_id de outra empresa retorna 404 stage_not_found — as etapas são escopadas pela sua chave.

Sincronizar leads alterados

Para manter um sistema externo (CRM, dashboard, planilha) em dia com os leads da Superlead, peça só o que mudou desde a última sincronização com GET /v1/leads?updated_since=....

Quer saber na hora, sem perguntar? Assine os webhooks de lead (lead.created, lead.updated, lead.deleted) e use esta listagem como reconciliação periódica.

Não consulte lead a lead (GET /v1/leads/{id} em laço) para descobrir o que mudou. Com milhares de leads, isso esgota o rate limit da chave e fica lento — a listagem traz até 100 leads alterados por requisição.

curl "https://api.superlead.app/v1/leads?updated_since=2026-10-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer sk_SUA_CHAVE"

{
  "data": [
    {
      "id": "lead_0b5f8a3e-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
      "name": "João Silva",
      "phone": "+5511999999999",
      "source": "Meta Ads",
      "channel": "WhatsApp",
      "entry_point": "ctwa",
      "funnel_stage": "Qualificado",
      "document": null,
      "document_type": null,
      "cep": null,
      "address": null,
      "address_number": null,
      "address_complement": null,
      "neighborhood": null,
      "city": null,
      "state": null,
      "country": null,
      "created_at": "2026-06-01T12:00:00.000Z",
      "updated_at": "2026-10-16T12:00:00.123456Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0xNlQxMjowMDowMC4xMjM0NTYiLCJpZCI6IjBiNWY4YTNlLTFhMmItM2M0ZC01ZTZmLTdhOGI5YzBkMWUyZiJ9"
}

Cada item é o mesmo recurso de GET /v1/leads/{id}, com updated_at.
A lista vem em ordem crescente de updated_at.
updated_at muda em qualquer alteração do lead — criação, cadastro, etapa do funil, atribuição — e também quando o lead manda mensagem. Vem sempre em UTC, com 6 casas decimais.
updated_since é inclusivo e exige fuso: use Z (UTC) ou um deslocamento como -03:00. Com deslocamento positivo, codifique o + como %2B.
limit vai de 1 a 100 (padrão 50).

Paginação

Enquanto has_more for true, repita a chamada adicionando starting_after com o next_cursor recebido:

curl "https://api.superlead.app/v1/leads?updated_since=2026-10-01T00:00:00Z&limit=100&starting_after=eyJ0IjoiMjAyNi0xMC0xNlQxMjowMDowMC4xMjM0NTYiLCJpZCI6IjBiNWY4YTNlLTFhMmItM2M0ZC01ZTZmLTdhOGI5YzBkMWUyZiJ9" \
  -H "Authorization: Bearer sk_SUA_CHAVE"

O cursor é opaco: envie exatamente o valor recebido. Ele garante que nenhum lead se repete nem fica de fora entre as páginas, mesmo quando vários leads mudam no mesmo instante. Quando has_more é false, next_cursor vem null.

Fluxo recomendado

Primeira sincronização: traga tudo

Use updated_since com uma data antiga (por exemplo 2000-01-01T00:00:00Z) e limit=100. Percorra as páginas até has_more: false e guarde o maior updated_at que apareceu.

Próximas sincronizações: só o que mudou

A cada ciclo (por exemplo, a cada 15 minutos), use como updated_since o maior updated_at guardado menos 5 minutos. Percorra as páginas e atualize o maior updated_at.

Grave pelo id

Insira ou atualize cada lead pelo id (lead_...). A sobreposição de 5 minutos traz de volta alguns leads que você já tem — gravando pelo id, isso é inofensivo.

Por que voltar 5 minutos: updated_at registra o momento da alteração, e uma alteração pode ficar visível na API alguns instantes depois desse momento. Sem a sobreposição, ela poderia cair antes do ponto em que você parou e nunca ser lida.

Exemplo em JavaScript:

const CINCO_MINUTOS = 5 * 60 * 1000;

// `desde`: maior updated_at da sincronização anterior (na primeira, "2000-01-01T00:00:00Z")
async function sincronizarLeads(desde) {
  const inicio = new Date(Date.parse(desde) - CINCO_MINUTOS).toISOString();
  let maior = desde;
  let cursor = null;
  do {
    const params = new URLSearchParams({ updated_since: inicio, limit: "100" });
    if (cursor) params.set("starting_after", cursor);
    const res = await fetch(`https://api.superlead.app/v1/leads?${params}`, {
      headers: { Authorization: `Bearer ${process.env.SUPERLEAD_API_KEY}` },
    });
    if (!res.ok) throw new Error(`Superlead respondeu ${res.status}`);
    const pagina = await res.json();
    for (const lead of pagina.data) {
      await salvarLead(lead); // insere ou atualiza pelo lead.id
      if (Date.parse(lead.updated_at) > Date.parse(maior)) maior = lead.updated_at;
    }
    cursor = pagina.has_more ? pagina.next_cursor : null;
  } while (cursor);
  return maior; // guarde para a próxima rodada
}

Leads excluídos não aparecem na listagem. Para refletir exclusões, assine o webhook lead.deleted. Sem webhook, faça de tempos em tempos (por exemplo, uma vez por semana) uma sincronização completa, com updated_since antigo: os leads que você tem e que não vierem nela foram excluídos.

Comece aqui

Conceitos

Buscar um lead

Criar um lead

Telefone duplicado

Fluxo recomendado: garantir lead antes do envio

Editando um lead

Movendo o lead de etapa

Sincronizar leads alterados

Paginação

Fluxo recomendado

​Buscar um lead

​Criar um lead

​Telefone duplicado

​Fluxo recomendado: garantir lead antes do envio

​Editando um lead

​Movendo o lead de etapa

​Sincronizar leads alterados

​Paginação

​Fluxo recomendado

Buscar um lead

Criar um lead

Telefone duplicado

Fluxo recomendado: garantir lead antes do envio

Editando um lead

Movendo o lead de etapa

Sincronizar leads alterados

Paginação

Fluxo recomendado