Reading and updating leads with the API

All endpoints need an API key sent as Authorization: Bearer …. See API overview and authentication.

GET /api/v1/me

Scope business:read. Returns the workspace, the key and the live role it acts with:

{
  "workspace": { "id": "…", "name": "…", "timezone": "Europe/London", "industry": "…", "status": "…" },
  "key": { "name": "…", "environment": "live", "scopes": ["business:read", "leads:read"] },
  "acting_as": { "role": "admin" }
}

GET /api/v1/leads

Scope leads:read. Searches your leads. Archived leads are not included.

{ "data": [ { "id": "…", "first_name": "…" } ], "count": 1 }

GET /api/v1/leads/{id}

Scope leads:read. Returns one lead as data, with its recent activity beside it as recent_activity: the last 20 messages on any channel, newest first.

{
  "data": { "id": "…", "first_name": "Jo", "status": "QUALIFIED", … },
  "recent_activity": [
    { "type": "message", "id": "…", "direction": "inbound", "channel": "email", "status": "…", "body": "…", "at": "2026-09-25T10:12:00Z" }
  ]
}

A message body longer than 500 characters is shortened. An ID that is not a valid UUID returns 400; a valid ID with no matching lead in your workspace returns 404.

PATCH /api/v1/leads/{id}

Scope leads:write, member role or above. Send only what you want to change:

Any other field is refused. Changes are applied in the order details, then status, then note. The response is the lead as it is now stored, plus the steps that were applied:

{ "data": { … }, "applied": ["lead.update", "lead.set_status"], "warnings": [ { "code": "…", "message": "…" } ] }

warnings passes on what the change means, for example that follow-up has stopped because the lead was marked won. Show these to your user.

A multi-part change is not all-or-nothing. If a later step is refused, the error says which step failed and which had already been applied:

{ "error": { "code": "conflict", "message": "…", "failed_step": "lead.set_status", "applied": ["lead.update"] } }

GET /api/v1/events

Scope business:read. Lists recent webhook deliveries for your workspace, newest first, so you can see what was sent to your endpoints, what your server answered, and whether it will be retried.

Each item has id, event_id, type, status, attempts, response_status, next_attempt_at, delivered_at, created_at and the payload that was sent. The endpoint URL and signing secret are never included.

Related

• Creating leads with the API
• Webhooks