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

# Listar leads

> Obter a lista paginada de leads capturados pelos seus agentes.

# Listar leads

Retorna todos os leads capturados pelos agentes da organização, ordenados por data de criação decrescente. É possível filtrar por agente. Os leads excluídos não são retornados.

```http theme={null}
GET https://app.chatnorris.ai/api/v2/leads
Authorization: Bearer <sua_api_key>
```

**Escopo necessário:** `leads:read`

***

## Query parameters

| Parâmetro | Tipo | Descrição |
| - | - | - |
| `chatbot_id` | string | Filtrar os leads de um agente específico |
| `created_after` | string | Apenas leads criados depois desta data (ISO 8601, ex.: `2026-09-01T00:00:00Z`) |
| `page` | integer | Número da página. Default: `1` |
| `per_page` | integer | Resultados por página. Default: `25`, máximo `100` |

***

## Resposta

```json theme={null}
{
  "status": "success",
  "data": {
    "leads": [
      {
        "id": "lead_abc123",
        "chatbot_id": "bot_xyz789",
        "conversation_id": "conv_def456",
        "name": "María García",
        "email": "maria@empresa.com",
        "phone": "+5491112345678",
        "extra_data": {
          "company": "Empresa SA"
        },
        "channel": "whatsapp",
        "contact_properties": {
          "company": "Empresa SA",
          "job_title": "Gerente de compras"
        },
        "custom_fields": {
          "Empresa": "Empresa SA"
        },
        "created_at": "2026-06-25T11:30:00.000Z"
      }
    ]
  },
  "pages": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 25,
    "total": 112
  }
}
```

### Campos da resposta

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | string | ID único do lead |
| `chatbot_id` | string | ID do agente que capturou o lead |
| `conversation_id` | string | ID da conversa associada |
| `name` | string \| null | Nome do lead |
| `email` | string \| null | Email do lead |
| `phone` | string \| null | Telefone do lead |
| `extra_data` | object \| null | Dados adicionais capturados |
| `channel` | string \| null | Canal da conversa que gerou o lead: `web`, `whatsapp`, `instagram`, `telegram`, `messenger`, `email` ou `api`. `null` se o lead não tiver conversa associada |
| `contact_properties` | object | Propriedades de contato confirmadas na conversa: `company`, `job_title`, `website`, `industry`, `address`, `city`, `state`, `zip` e `country`. Objeto vazio se não houver nenhuma |
| `custom_fields` | object | Campos personalizados do lead (plano Premium). As chaves são o nome do campo, não o ID interno dele — ex.: `{ "Empresa": "Empresa SA" }` |
| `created_at` | string | Data da captura (ISO 8601) |

> [!TIP]
>
> Para fazer polling incremental, use `created_after` com o `created_at` do último lead recebido como ponto de partida da consulta seguinte.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.