> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superlead.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Leads

> Consulte leads por telefone ou id e crie leads explicitamente.

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):

```bash theme={null}
curl "https://api.superlead.app/v1/leads?phone=%2B5511999999999" \
  -H "Authorization: Bearer sl_live_SUA_CHAVE"
```

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

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

```bash theme={null}
curl https://api.superlead.app/v1/leads/lead_0b5f8a3e-1a2b-3c4d-5e6f-7a8b9c0d1e2f \
  -H "Authorization: Bearer sl_live_SUA_CHAVE"
```

As duas formas retornam o mesmo recurso:

```json theme={null}
{
  "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"
}
```

<Note>
  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.
</Note>

## Criar um lead

```bash theme={null}
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"
  }'
```

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

<Steps>
  <Step title="Busque pelo telefone">
    `GET /v1/leads?phone=...`. Se retornar `200`, o lead existe — siga para o envio.
  </Step>

  <Step title="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).
  </Step>

  <Step title="Envie a mensagem">
    `POST /v1/messages` com o telefone em `to`.
  </Step>
</Steps>