---
title: "Leads"
description: "Read the leads your agents collect through the Chatvox API."
---

Leads are the contact details your agents collect with the [Collect Leads](/docs/actions/collect-leads) action. To get them as soon as they're captured, use the [`lead.created` webhook](/docs/developers/webhooks#events) instead of polling.

## The lead object

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The lead's ID. |
| `agent_id` | string | The agent that collected it. |
| `conversation_id` | string or null | The conversation it came from. |
| `name` | string or null | The lead's name. |
| `email` | string or null | The lead's email address. |
| `phone` | string or null | The lead's phone number. |
| `notes` | string or null | Notes the agent added. |
| `custom_fields` | object | Your [custom lead fields](/docs/actions/collect-leads), keyed by field key. |
| `source` | string or null | The channel it came from, such as `embed` or `public_link`. |
| `referrer_url` | string or null | The page the visitor was on. |
| `utm` | object | The [UTM parameters](/docs/leads-and-contacts/campaign-tracking) of the link the visitor arrived through, such as `utm_source` and `utm_campaign`. Empty if there were none. |
| `created_at` | string | When it was captured. |
| `updated_at` | string | When it last changed. |

## List leads

```http
GET /api/v1/agents/{agent}/leads
```

```bash
curl "https://my.chatvox.co/api/v1/agents/AGENT_ID/leads?per_page=50" \
  -H "Authorization: Bearer cvx_your_key"
```

Returns a [paginated list](/docs/developers#lists-and-pagination), newest first.

## Get a lead

```http
GET /api/v1/agents/{agent}/leads/{lead}
```

```json
{
  "id": "01a12267-9e4a-73b6-8619-2bb0cdda7ba2",
  "agent_id": "019f80ad-e549-712d-bc26-3ab29ae2228c",
  "conversation_id": "01a12260-2b5c-7d41-9f0e-6a1f2c9b8e11",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "phone": "+1 555 0100",
  "notes": "Interested in the Pro plan.",
  "custom_fields": { "company": "Analytical Engines Ltd" },
  "source": "embed",
  "referrer_url": "https://example.com/pricing",
  "utm": { "utm_source": "google", "utm_campaign": "spring_sale" },
  "created_at": "2026-10-09T18:40:12+00:00",
  "updated_at": "2026-10-09T18:41:03+00:00"
}
```