> ## 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. # 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](/guias/leads#sincronizar-leads-alterados). Sem `phone`, `updated_since` nem `starting_after`, a resposta é `400 invalid_request`. ## OpenAPI ````yaml /openapi.json get /v1/leads openapi: 3.1.0 info: title: Superlead API version: 1.0.0 description: > API oficial do Superlead para envio de mensagens WhatsApp aos **seus leads**. ## Autenticação Toda chamada exige `Authorization: Bearer sk_...` (crie a chave no painel Superlead em Integrações → API). A chave é escopada à sua empresa. ## Início rápido ```bash curl -X POST https://api.superlead.app/v1/whatsapp/messages \ -H "Authorization: Bearer sk_SUACHAVE" \ -H "Idempotency-Key: pedido-8734" \ -H "Content-Type: application/json" \ -d '{"to":"+5511999999999","type":"text","text":{"body":"Olá!"}}' ``` No n8n: nó **HTTP Request**, método POST, header Authorization como acima. ## Endereçamento O campo `to` aceita **telefone E.164** (`+5511999999999`) ou **BSUID** (`BR.13491208655302741918` — o `fromUserId` entregue nos webhooks quando o contato usa username do WhatsApp; usernames nunca endereçam). O destinatário precisa ser um lead existente da sua empresa — o envio nunca cria leads. Para outreach, crie antes com `POST /v1/leads`. Use `external_id` para reconciliar com o seu sistema. ## Janela de 24h (regra da Meta) Mensagens de formato livre (text, image, ...) só são entregues se o lead falou com você nas últimas 24 horas. Fora da janela, use `type: "template"` com um template aprovado (liste-os em `GET /v1/whatsapp/templates`). Fora da janela a Meta pode rejeitar o envio na hora (`outside_24h_window`) OU aceitá-lo (201, status `accepted`) e falhá-lo de forma assíncrona segundos depois — a mensagem passa ao status `failed`. Confirme em `GET /v1/whatsapp/messages/{id}` ou pelo webhook `whatsapp.message.updated`. ## Idempotência Envie o header `Idempotency-Key` (recomendado). Retries com a mesma chave e mesmo body retornam a resposta original sem reenviar. Validade: 24h. ## Rate limit 60 requisições/min por chave (headers `X-RateLimit-*`; `429` inclui `Retry-After`). Cota diária por empresa: 10.000 leituras (GET) e 10.000 escritas (POST, PATCH, PUT, DELETE), zerada à meia-noite de Brasília (headers `X-Daily-Quota-*`; `429 daily_quota_exceeded` inclui `Retry-After`). ## Status da mensagem A resposta traz o status inicial. Acompanhe `sent → delivered → read` (ou `failed`) pelos webhooks do Superlead (evento `whatsapp.message.updated`) ou por `GET /v1/whatsapp/messages/{id}`. O evento de status identifica a mensagem pelo `wamid` retornado na resposta do envio. ## Erros Envelope estável `{ "error": { "code", "message", "request_id" } }`. Trate códigos desconhecidos pelo HTTP status (novos códigos são mudança aditiva). | HTTP | code | Meaning | |---|---|---| | 400 | `invalid_request` | The request body is invalid. Check the details field and the API reference. | | 401 | `invalid_api_key` | Missing or invalid API key. Send it as 'Authorization: Bearer sk_...'. | | 404 | `lead_not_found` | No lead matches this recipient in your company. The API only messages existing leads. | | 404 | `message_not_found` | No message with this id exists in your company. | | 404 | `stage_not_found` | No funnel stage with this id exists in your company. List valid stages with GET /v1/funnel/stages. | | 409 | `idempotency_conflict` | This Idempotency-Key was already used with a different request body, or the original request is still in progress. | | 409 | `lead_already_exists` | A lead with this phone number already exists in your company. You can message it directly via POST /v1/whatsapp/messages. | | 422 | `funnel_not_configured` | Your company has no funnel stages configured. Set up the funnel in the Superlead panel first. | | 422 | `no_active_connection` | Your company has no active WhatsApp connection. Connect a number in the Superlead panel first. | | 422 | `connection_expired` | Your WhatsApp connection is no longer authorized. Reconnect it in the Superlead panel. | | 422 | `channel_capability_unsupported` | Your company's WhatsApp connection type does not support this operation. | | 422 | `outside_24h_window` | Free-form messages require the lead to have messaged you within the last 24 hours. Send an approved template instead. | | 422 | `template_not_found` | Template not found. Check the exact name and language with GET /v1/whatsapp/templates. | | 422 | `template_params_invalid` | Template parameters do not match the approved template. Check count, format and language. | | 422 | `recipient_unavailable` | The recipient cannot receive this message on WhatsApp right now. | | 422 | `media_unsupported` | WhatsApp could not fetch or process the media. Check that the link is public and direct, the format is supported and the file is within the size limit for its type. | | 422 | `message_blocked` | Meta blocked this message (spam or ecosystem limits). Reduce volume to this recipient and review quality. | | 429 | `rate_limit_exceeded` | Rate limit for this API key exceeded. Retry after the time in the Retry-After header. | | 429 | `daily_quota_exceeded` | Daily quota for this company exceeded. It resets at midnight America/Sao_Paulo. Retry after the time in the Retry-After header. | | 429 | `channel_rate_limit` | WhatsApp is throttling your number. Slow down and retry later. | | 502 | `channel_error` | The messaging provider returned an unexpected error. Our team was notified; retry later. | | 500 | `internal_error` | Internal error. Our team was notified; retry later. | ## Versionamento Caminho `/v1/`. Mudanças incompatíveis só em `/v2/`. Campos novos opcionais podem aparecer a qualquer momento — ignore campos desconhecidos. servers: - url: https://api.superlead.app description: Produção security: [] paths: /v1/leads: get: summary: Buscar ou Listar Leads description: >- 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](/guias/leads#sincronizar-leads-alterados). Sem `phone`, `updated_since` nem `starting_after`, a resposta é `400 invalid_request`. operationId: getLeadByPhone parameters: - name: phone in: query required: false schema: type: string description: >- **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. example: '+5511999999999' - name: updated_since in: query required: false schema: type: string format: date-time description: >- **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). example: '2026-10-01T00:00:00Z' - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 50 description: '**Listagem.** Leads por página, de 1 a 100. Padrão: 50.' example: 100 - name: starting_after in: query required: false schema: type: string description: >- **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`. example: >- eyJ0IjoiMjAyNi0xMC0xNlQxMjowMDowMC4wMDAwMDEiLCJpZCI6IjBiNWY4YTNlLTFhMmItM2M0ZC01ZTZmLTdhOGI5YzBkMWUyZiJ9 responses: '200': description: >- Com `phone`: o lead encontrado, cadastro completo. Na listagem: uma página de leads alterados. content: application/json: schema: oneOf: - title: Busca por telefone type: object properties: id: type: string description: >- Id do lead no Superlead (`lead_...`). Estável — use nas demais chamadas. example: lead_0b5f8a3e-1a2b-3c4d-5e6f-7a8b9c0d1e2f name: type: - string - 'null' description: Nome do lead. example: João Silva phone: type: - string - 'null' description: >- Telefone em E.164. `null` para leads sem telefone exposto (username do WhatsApp). example: '+5511999999999' source: type: - string - 'null' description: Origem do lead exibida no painel. example: Meta Ads channel: type: - string - 'null' description: Canal de origem. example: WhatsApp entry_point: type: - string - 'null' description: Ponto de entrada da conversão. example: ctwa funnel_stage: type: - string - 'null' description: >- Nome da etapa atual do funil. Para mover, use `PUT /v1/leads/{id}/stage`. example: 1º Contato document: type: - string - 'null' description: CPF ou CNPJ do lead. example: 123.456.789-01 document_type: type: - string - 'null' description: Tipo do documento. example: cpf enum: - cpf - cnpj cep: type: - string - 'null' description: CEP do endereço. example: 01310-100 address: type: - string - 'null' description: Logradouro. example: Av. Paulista address_number: type: - string - 'null' description: Número. example: '1000' address_complement: type: - string - 'null' description: Complemento. example: Conjunto 51 neighborhood: type: - string - 'null' description: Bairro. example: Bela Vista city: type: - string - 'null' description: Cidade. example: São Paulo state: type: - string - 'null' description: Estado (UF). example: SP country: type: - string - 'null' description: País. example: BR created_at: type: string format: date-time description: Data de criação do lead (ISO 8601, UTC). example: '2026-06-01T12:00:00.000Z' - title: Listagem incremental type: object properties: data: type: array description: >- Leads alterados, em ordem crescente de `updated_at`. Cada item é o recurso de `GET /v1/leads/{id}` com `updated_at`. items: type: object properties: id: type: string description: >- Id do lead no Superlead (`lead_...`). Estável — use nas demais chamadas. example: lead_0b5f8a3e-1a2b-3c4d-5e6f-7a8b9c0d1e2f name: type: - string - 'null' description: Nome do lead. example: João Silva phone: type: - string - 'null' description: >- Telefone em E.164. `null` para leads sem telefone exposto (username do WhatsApp). example: '+5511999999999' source: type: - string - 'null' description: Origem do lead exibida no painel. example: Meta Ads channel: type: - string - 'null' description: Canal de origem. example: WhatsApp entry_point: type: - string - 'null' description: Ponto de entrada da conversão. example: ctwa funnel_stage: type: - string - 'null' description: >- Nome da etapa atual do funil. Para mover, use `PUT /v1/leads/{id}/stage`. example: 1º Contato document: type: - string - 'null' description: CPF ou CNPJ do lead. example: 123.456.789-01 document_type: type: - string - 'null' description: Tipo do documento. example: cpf enum: - cpf - cnpj cep: type: - string - 'null' description: CEP do endereço. example: 01310-100 address: type: - string - 'null' description: Logradouro. example: Av. Paulista address_number: type: - string - 'null' description: Número. example: '1000' address_complement: type: - string - 'null' description: Complemento. example: Conjunto 51 neighborhood: type: - string - 'null' description: Bairro. example: Bela Vista city: type: - string - 'null' description: Cidade. example: São Paulo state: type: - string - 'null' description: Estado (UF). example: SP country: type: - string - 'null' description: País. example: BR created_at: type: string format: date-time description: Data de criação do lead (ISO 8601, UTC). example: '2026-06-01T12:00:00.000Z' updated_at: type: string format: date-time description: >- Última alteração do lead (ISO 8601, UTC, sempre com 6 casas decimais). Muda em qualquer alteração do lead: cadastro, etapa do funil, atribuição e também mensagem recebida do lead. Guarde o maior valor visto para a próxima sincronização. example: '2026-10-16T12:00:00.123456Z' has_more: type: boolean description: >- `true` quando há mais leads depois desta página — busque a próxima com `starting_after`. example: true next_cursor: type: - string - 'null' description: >- Valor para `starting_after` na próxima página. `null` quando `has_more` é `false`. example: >- eyJ0IjoiMjAyNi0xMC0xNlQxMjowMDowMC4xMjM0NTYiLCJpZCI6IjBiNWY4YTNlLTFhMmItM2M0ZC01ZTZmLTdhOGI5YzBkMWUyZiJ9 examples: busca-por-telefone: summary: Busca por telefone (?phone=) value: 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' listagem: summary: Listagem incremental (?updated_since=) value: data: - 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' updated_at: '2026-10-16T12:00:00.123456Z' has_more: true next_cursor: >- eyJ0IjoiMjAyNi0xMC0xNlQxMjowMDowMC4xMjM0NTYiLCJpZCI6IjBiNWY4YTNlLTFhMmItM2M0ZC01ZTZmLTdhOGI5YzBkMWUyZiJ9 '400': description: >- `invalid_request` — faltou `phone` (busca) ou `updated_since`/`starting_after` (listagem), ou algum parâmetro é inválido: `updated_since` sem fuso, `limit` fora de 1 a 100, cursor alterado. O campo `details` aponta o parâmetro. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_request message: >- Invalid query parameters. Check the details field and the API reference. request_id: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 details: - path: updated_since message: >- must be an ISO 8601 date-time with timezone, e.g. 2026-10-01T00:00:00Z '401': description: >- `invalid_api_key` — chave de API ausente, malformada ou revogada. Envie `Authorization: Bearer sk_...`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_api_key message: >- Missing or invalid API key. Send it as 'Authorization: Bearer sk_...'. request_id: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 '404': description: >- `lead_not_found` — (busca por telefone) nenhum lead com este telefone na sua empresa. Para registrá-lo, use `POST /v1/leads`. A listagem nunca retorna 404: sem alterações, `data` vem vazio. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: lead_not_found message: >- No lead matches this recipient in your company. The API only messages existing leads. request_id: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 security: - apiKey: [] components: schemas: Error: type: object properties: error: type: object properties: code: type: string description: >- Código estável do erro (ex.: `lead_not_found`). Novos códigos podem surgir a qualquer momento — trate códigos desconhecidos pelo HTTP status. example: lead_not_found message: type: string description: >- Descrição legível do erro, em inglês. O texto pode mudar — não faça parsing dele; use `code`. request_id: type: string description: >- Id único desta requisição. Inclua ao reportar um problema ao suporte. example: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 upstream_code: type: number description: >- Código numérico original da Meta, presente quando o erro veio do WhatsApp (ex.: `131047` para fora da janela de 24h). example: 131047 details: type: array description: >- Detalhes do erro. Aparece em três casos: erros de validação campo a campo em `400 invalid_request` (`path` é o campo do body); a explicação da Meta numa recusa de template, com `path: "meta"` (só quando a Meta envia uma explicação); e as campanhas que bloqueiam a exclusão de um template (`template_in_use`), com `path: "campaigns"` (até 10). items: type: object properties: path: type: string description: >- Em `invalid_request`, o caminho do campo inválido no body (ex.: `text.body`). Nas recusas de template vale `meta`; em `template_in_use` vale `campaigns`. message: type: string description: O que está errado com o campo. securitySchemes: apiKey: type: http scheme: bearer description: >- 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](/guias/autenticacao). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.