跳到主要内容
Docs/Api Reference/Leads

Leads API

A lead is a sales opportunity attached to a contact. Leads carry status, score, value, and pipeline-stage information.

Resource

Auth: Bearer JWT or X-Api-Key. Tenant required.

Endpoints

MethodPathDescription
GET`/api/v1/leads`List (filter by status / pipeline / assignee)
POST`/api/v1/leads`Create
GET`/api/v1/leads/:id`Get one
PATCH`/api/v1/leads/:id`Update
PATCH`/api/v1/leads/:id/stage`Move to a different pipeline stage
PATCH`/api/v1/leads/:id/assign`Reassign owner
POST`/api/v1/leads/auto-assign`Round-robin auto-assign unowned leads
POST`/api/v1/leads/:id/recompute-score`Force a score recompute
DELETE`/api/v1/leads/:id`Delete

Schema

{
  "id": "lead_01H...",
  "tenantId": "tnt_01H...",
  "contactId": "ctc_01H...",
  "pipelineId": "pip_01H...",
  "stageId": "stg_01H...",
  "status": "OPEN",
  "source": "CRAWLER",
  "score": 78,
  "value": 12000,
  "currency": "USD",
  "assignedToId": "usr_01H...",
  "createdAt": "2026-04-01T08:00:00Z",
  "updatedAt": "2026-05-04T17:21:00Z"
}

Stage Transitions

Stage moves emit lead.stage_changed webhooks. Use PATCH /:id/stage (not PATCH /:id) to ensure stage-trigger automations fire.

Examples

curl -X PATCH https://api.anvilhk.com/api/v1/leads/lead_01H.../stage \
  -H "Authorization: Bearer $ANVIL_KEY" \
  -H "X-Tenant-ID: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{ "stageId": "stg_qualified" }'

Every response uses the standard envelope:

{
  "success": true,
  "data": { /* resource or array */ },
  "meta": { "total": 100, "cursor": "...", "hasMore": true },
  "error": { "code": "ERROR_CODE", "message": "Human readable" }
}

error is omitted on success; meta is omitted when not paginating.

Rate Limits

Subject to the standard 200 req/min/tenant authenticated limit. See [Rate Limits](/docs/api-reference/rate-limits) for full details and the per-endpoint overrides.

← Back to Docs