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.

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

​Buscar um lead

​Criar um lead

​Telefone duplicado

​Fluxo recomendado: garantir lead antes do envio

​Editando um lead

​Movendo o lead de etapa

Buscar um lead

Criar um lead

Telefone duplicado

Fluxo recomendado: garantir lead antes do envio

Editando um lead

Movendo o lead de etapa