Leads

Read the leads your agents collect through the Chatvox API.

Leads are the contact details your agents collect with the Collect Leads action. To get them as soon as they’re captured, use the lead.created webhook 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, 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 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

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

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

Returns a paginated list, newest first.

Get a lead

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

{
  "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"
}