> ## 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.

# List leads

> Get the paginated list of leads captured by your agents.

# List leads

Returns all the leads captured by the organization's agents, sorted by creation date in descending order. You can filter by agent. Deleted leads aren't returned.

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

**Required scope:** `leads:read`

***

## Query parameters

| Parameter | Type | Description |
| - | - | - |
| `chatbot_id` | string | Filter leads from a specific agent |
| `created_after` | string | Only leads created after this date (ISO 8601, e.g. `2026-09-01T00:00:00Z`) |
| `page` | integer | Page number. Default: `1` |
| `per_page` | integer | Results per page. Default: `25`, maximum `100` |

***

## Response

```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": "Purchasing manager"
        },
        "custom_fields": {
          "Company": "Empresa SA"
        },
        "created_at": "2026-06-25T11:30:00.000Z"
      }
    ]
  },
  "pages": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 25,
    "total": 112
  }
}
```

### Response fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique ID of the lead |
| `chatbot_id` | string | ID of the agent that captured the lead |
| `conversation_id` | string | ID of the associated conversation |
| `name` | string \| null | Lead's name |
| `email` | string \| null | Lead's email |
| `phone` | string \| null | Lead's phone number |
| `extra_data` | object \| null | Additional captured data |
| `channel` | string \| null | Channel of the conversation that generated the lead: `web`, `whatsapp`, `instagram`, `telegram`, `messenger`, `email` or `api`. `null` if the lead has no associated conversation |
| `contact_properties` | object | Contact properties confirmed in the conversation: `company`, `job_title`, `website`, `industry`, `address`, `city`, `state`, `zip` and `country`. Empty object if there are none |
| `custom_fields` | object | The lead's custom fields (Premium plan). The keys are the field name, not its internal ID — e.g. `{ "Company": "Empresa SA" }` |
| `created_at` | string | Capture date (ISO 8601) |

> [!TIP]
>
> To do incremental polling, use `created_after` with the `created_at` of the last lead received as the starting point for the next query.


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