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 sl_live_SUA_CHAVE"
Em query string, o + precisa ser codificado como %2B — um + cru vira espaço. Alternativa: mande só os dígitos (?phone=5511999999999).
lead_... retornado na criação):
curl https://api.superlead.app/v1/leads/lead_0b5f8a3e-1a2b-3c4d-5e6f-7a8b9c0d1e2f \
-H "Authorization: Bearer sl_live_SUA_CHAVE"
{
"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 sl_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"name": "João Silva",
"phone": "+5511999999999",
"source": "Indicação"
}'
| 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. |
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/messages com o telefone em to.