curl --request POST \
  --url https://api.superlead.app/v1/leads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "João Silva",
  "phone": "+5511999999999"
}
'

{
  "id": "lead_0b5f8a3e-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "name": "João Silva",
  "phone": "+5511999999999",
  "source": "Indicação",
  "channel": "WhatsApp",
  "entry_point": "formulario-site",
  "funnel_stage": "1º Contato",
  "created_at": "2026-07-08T12:00:00.000Z"
}

{
  "error": {
    "code": "invalid_request",
    "message": "The request body is invalid.",
    "request_id": "req_01J9X7K2M3N4P5Q6R7S8T9V0W1",
    "details": [
      {
        "path": "to",
        "message": "Required"
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "Missing or invalid API key. Send it as 'Authorization: Bearer sk_...'.",
    "request_id": "req_01J9X7K2M3N4P5Q6R7S8T9V0W1"
  }
}

{
  "error": {
    "code": "lead_already_exists",
    "message": "A lead with this phone number already exists in your company. You can message it directly via POST /v1/whatsapp/messages.",
    "request_id": "req_01J9X7K2M3N4P5Q6R7S8T9V0W1"
  }
}

{
  "error": {
    "code": "funnel_not_configured",
    "message": "Your company has no funnel stages configured. Set up the funnel in the Superlead panel first.",
    "request_id": "req_01J9X7K2M3N4P5Q6R7S8T9V0W1"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit for this API key exceeded. Retry after the time in the Retry-After header.",
    "request_id": "req_01J9X7K2M3N4P5Q6R7S8T9V0W1"
  }
}

Leads

Criar Lead

Cria um lead na sua empresa. Criar lead é sempre uma ação explícita — envios de mensagem nunca criam leads como efeito colateral.

O lead entra na primeira etapa do funil e aparece imediatamente no painel.
Telefone é único por empresa: se já existe um lead com o número, a resposta é 409 lead_already_exists — recupere-o com GET /v1/leads?phone=... e siga normalmente (para automações, trate 409 como sucesso).
Requer funil configurado no painel (422 funnel_not_configured caso contrário).

Veja o fluxo recomendado buscar → criar → enviar em Leads.

POST

leads

curl --request POST \
  --url https://api.superlead.app/v1/leads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "João Silva",
  "phone": "+5511999999999"
}
'

{
  "id": "lead_0b5f8a3e-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "name": "João Silva",
  "phone": "+5511999999999",
  "source": "Indicação",
  "channel": "WhatsApp",
  "entry_point": "formulario-site",
  "funnel_stage": "1º Contato",
  "created_at": "2026-07-08T12:00:00.000Z"
}

{
  "error": {
    "code": "invalid_request",
    "message": "The request body is invalid.",
    "request_id": "req_01J9X7K2M3N4P5Q6R7S8T9V0W1",
    "details": [
      {
        "path": "to",
        "message": "Required"
      }
    ]
  }
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "Missing or invalid API key. Send it as 'Authorization: Bearer sk_...'.",
    "request_id": "req_01J9X7K2M3N4P5Q6R7S8T9V0W1"
  }
}

{
  "error": {
    "code": "lead_already_exists",
    "message": "A lead with this phone number already exists in your company. You can message it directly via POST /v1/whatsapp/messages.",
    "request_id": "req_01J9X7K2M3N4P5Q6R7S8T9V0W1"
  }
}

{
  "error": {
    "code": "funnel_not_configured",
    "message": "Your company has no funnel stages configured. Set up the funnel in the Superlead panel first.",
    "request_id": "req_01J9X7K2M3N4P5Q6R7S8T9V0W1"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit for this API key exceeded. Retry after the time in the Retry-After header.",
    "request_id": "req_01J9X7K2M3N4P5Q6R7S8T9V0W1"
  }
}

Authorizations

Authorization

string

header

required

Chave de API da sua empresa (sk_...). Crie no painel Superlead em Integrações → API e envie em toda chamada como Authorization: Bearer sk_.... Veja Autenticação.

Body

application/json

name

string

required

Nome do lead, até 200 caracteres.

Required string length: 1 - 200

Example:

"João Silva"

phone

string

required

Telefone em E.164: +, código do país, DDD e número (ex.: +5511999999999). Único por empresa.

Pattern: ^\+[1-9]\d{6,14}$

Example:

"+5511999999999"

source

string

Origem do lead exibida no painel (ex.: Indicação, Site). Sem valor, o lead entra como Não Rastreado.

Required string length: 1 - 120

Example:

"Indicação"

channel

string

Canal de origem (ex.: WhatsApp, Instagram).

Required string length: 1 - 120

Example:

"WhatsApp"

entry_point

string

Ponto de entrada da conversão (ex.: formulario-site, ctwa).

Required string length: 1 - 120

Example:

"formulario-site"

string<email>

E-mail do lead.

Example:

"joao@empresa.com"

notes

string

Observações livres, até 2000 caracteres.

Maximum string length: 2000

Example:

"Pediu orçamento do plano anual."

utm_source

string

Atribuição de campanha: origem (ex.: google, facebook).

Maximum string length: 255

Example:

"google"

utm_medium

string

Atribuição de campanha: mídia (ex.: cpc, social).

Maximum string length: 255

Example:

"cpc"

utm_campaign

string

Atribuição de campanha: nome da campanha.

Maximum string length: 255

Example:

"lancamento-julho"

utm_term

string

Atribuição de campanha: termo de busca.

Maximum string length: 255

Example:

"crm whatsapp"

utm_content

string

Atribuição de campanha: variação do anúncio.

Maximum string length: 255

Example:

"video-a"

Response

Lead criado na primeira etapa do funil.

string

Id do lead (lead_...). Guarde-o para editar, mover de etapa e consultar.

Example:

"lead_0b5f8a3e-1a2b-3c4d-5e6f-7a8b9c0d1e2f"

name

string

Nome do lead.

Example:

"João Silva"

phone

string

Telefone em E.164.

Example:

"+5511999999999"

source

string

Origem do lead (ou Não Rastreado).

Example:

"Indicação"

channel

string | null

Canal de origem.

Example:

"WhatsApp"

entry_point

string | null

Ponto de entrada da conversão.

Example:

"formulario-site"

funnel_stage

string | null

Nome da etapa em que o lead entrou (a primeira do funil).

Example:

"1º Contato"

created_at

string<date-time>

Data de criação (ISO 8601, UTC).

Example:

"2026-07-08T12:00:00.000Z"

Introdução

WhatsApp

Leads

Funil

Criar Lead

Authorizations

Body

Response