Buscar ou Listar Leads

curl --request GET \
  --url https://api.superlead.app/v1/leads \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.superlead.app/v1/leads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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",
  "document": "123.456.789-01",
  "document_type": "cpf",
  "cep": "01310-100",
  "address": "Av. Paulista",
  "address_number": "1000",
  "address_complement": null,
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "country": "BR",
  "created_at": "2026-06-01T12:00:00.000Z"
}

Leads

Buscar ou Listar Leads

Dois modos no mesmo endpoint:

Busca por telefone (phone): retorna o cadastro completo de um lead — o mesmo recurso de GET /v1/leads/{id}.

Aceita E.164 (+5511999999999) ou apenas dígitos (5511999999999).
Em query string, codifique o + como %2B — um + cru vira espaço. Alternativa: envie só os dígitos.
Números brasileiros: a busca testa automaticamente a variação do nono dígito, então funciona com ou sem o 9 após o DDD.
Com phone, os parâmetros de listagem são ignorados.

Use antes de criar (POST /v1/leads) para não duplicar, e para descobrir o id (lead_...) de um lead que você só conhece pelo telefone.

Listagem incremental (updated_since, sem phone): retorna, em páginas, os leads da sua empresa alterados desde um instante — criados ou com qualquer dado mudado. É a forma eficiente de manter um sistema externo sincronizado: em vez de consultar lead a lead para descobrir o que mudou, peça só o que mudou.

Ordem: updated_at crescente (desempate pelo id).
Paginação por cursor: enquanto has_more for true, repita a chamada com starting_after igual ao next_cursor recebido.
Guarde o maior updated_at visto e use-o, menos alguns minutos, como updated_since da próxima sincronização. Leads repetidos na sobreposição têm o mesmo id — atualize pelo id.
Leads excluídos não aparecem na listagem — para saber deles, assine o webhook lead.deleted.

Veja o passo a passo em Leads → Sincronizar leads alterados.

Sem phone, updated_since nem starting_after, a resposta é 400 invalid_request.

GET

leads

Buscar ou Listar Leads

curl --request GET \
  --url https://api.superlead.app/v1/leads \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.superlead.app/v1/leads', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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",
  "document": "123.456.789-01",
  "document_type": "cpf",
  "cep": "01310-100",
  "address": "Av. Paulista",
  "address_number": "1000",
  "address_complement": null,
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "country": "BR",
  "created_at": "2026-06-01T12:00:00.000Z"
}

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.

Query Parameters

phone

string

Busca por telefone. Telefone em E.164 (%2B5511999999999 na query) ou só dígitos (5511999999999). A variação do nono dígito BR é tratada automaticamente. Quando presente, os parâmetros de listagem são ignorados.

updated_since

string<date-time>

Listagem. Retorna os leads com updated_at maior ou igual a este instante. ISO 8601 com fuso (Z ou -03:00); sem fuso é recusado. Na primeira sincronização, use uma data antiga (ex.: 2000-01-01T00:00:00Z) para trazer todos. Com fuso positivo, codifique o + como %2B — ou prefira Z (UTC).

limit

integer

default:50

Listagem. Leads por página, de 1 a 100. Padrão: 50.

Required range: 1 <= x <= 100

starting_after

string

Listagem. Cursor da próxima página: o next_cursor da resposta anterior, sem alterações. É opaco — não monte nem edite. Pode ser enviado com ou sem updated_since.

Response

Com phone: o lead encontrado, cadastro completo. Na listagem: uma página de leads alterados.

Busca por telefone
Listagem incremental

string

Id do lead no Superlead (lead_...). Estável — use nas demais chamadas.

Example:

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

name

string | null

Nome do lead.

Example:

"João Silva"

phone

string | null

Telefone em E.164. null para leads sem telefone exposto (username do WhatsApp).

Example:

"+5511999999999"

source

string | null

Origem do lead exibida no painel.

Example:

"Meta Ads"

channel

string | null

Canal de origem.

Example:

"WhatsApp"

entry_point

string | null

Ponto de entrada da conversão.

Example:

"ctwa"

funnel_stage

string | null

Nome da etapa atual do funil. Para mover, use PUT /v1/leads/{id}/stage.

Example:

"1º Contato"

document

string | null

CPF ou CNPJ do lead.

Example:

"123.456.789-01"

document_type

enum<string> | null

Tipo do documento.

Available options:

cpf,

cnpj

Example:

"cpf"

cep

string | null

CEP do endereço.

Example:

"01310-100"

address

string | null

Logradouro.

Example:

"Av. Paulista"

address_number

string | null

Número.

Example:

"1000"

address_complement

string | null

Complemento.

Example:

"Conjunto 51"

neighborhood

string | null

Bairro.

Example:

"Bela Vista"

city

string | null

Cidade.

Example:

"São Paulo"

state

string | null

Estado (UF).

Example:

"SP"

country

string | null

País.

Example:

"BR"

created_at

string<date-time>

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

Example:

"2026-06-01T12:00:00.000Z"

Introdução

WhatsApp

Templates

Leads

Funil

Buscar ou Listar Leads

Authorizations

Query Parameters

Response