Leads

Verified against backend/internal/publicapi/dto.go, leads_handler.go, and routes.go.

List / get

curl "https://api.voicematrix.ai/api/v1/ext/leads?status=new&limit=50" \
  -H "X-API-Key: vm_live_..."

Filters: status, agent_id, from_date, to_date, plus the standard limit/offset. Same {"data": [...], "pagination": {...}} envelope as every other list endpoint.

{
  "id": "...",
  "name": "John Doe",
  "phone": "+972501234567",
  "email": "[email protected]",
  "status": "new",
  "source": "phone_call",
  "agent_id": "...",
  "notes": "Interested in premium plan",
  "metadata": {},
  "created_at": "2026-08-20T10:00:00Z",
  "updated_at": "2026-08-20T10:00:00Z"
}

Create a lead

curl -X POST https://api.voicematrix.ai/api/v1/ext/leads \
  -H "X-API-Key: vm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "phone": "+972501234567",
    "agent_id": "<agent-uuid>",
    "email": "[email protected]",
    "source": "website_form",
    "notes": "Requested a callback"
  }'

name, phone and agent_id are all required, and agent_id must be a UUID for an agent in your organization. agent_id is the one to watch: the request schema marks it optional, but the handler rejects a missing or blank value with 400 VALIDATION_ERROR — "agent_id is required" before the insert, because the column is NOT NULL (leads_handler.go:143-150). An earlier version of this page documented it as optional and showed an example without it — that example returned a 400. Verified live against DEV on 2026-08-25.

Dispatches a lead.created webhook event on success.

Writes accept an Idempotency-Key header: a retried request with the same key returns the original lead instead of creating a second one (verified live — the retry returned the same id).

Update a lead

PATCH /leads/:id

Every field is optional and independently settable — name, email, status, notes, metadata. Dispatches lead.updated.

Next

• Webhooks — lead.created / lead.updated payloads in full
• Agents