List leads

GET/api/v1/leadsscope: leads.read

Returns leads in your organisation, ordered by next-call time ascending then by creation time descending. The response is paginated - a maximum of 100 leads come back per page. Walk `pagination.totalPages` (or keep going until `pagination.hasNextPage` is `false`) to read everything. See [API conventions → Pagination](/docs/api-conventions/pagination) for the shared pagination contract.

Query parameters

Field	Type	Required	Description
status	enum (NOT_CONTACTED \| CONTACTED \| QUALIFIED \| CONVERTED \| LOST)	no	Filter by exact status
search	string	no	Case-insensitive match against contact name, email, phone, or company
assignedToId	string	no	OrgMember id, or the literal string "unassigned" for leads with no owner
page	number	no	1-indexed page number. Defaults to 1.
pageSize	number	no	Items per page (1–100). Defaults to 50.

Response

Returns a paginated wrapper:

Field	Type	Required	Description
data	object[]	yes	Page of leads
pagination	object	yes	-

Each item in `data`

Field	Type	Required	Description
id	string	yes	Lead id
name	string	yes	Contact name
phones	string[]	yes	Normalised phone numbers (E.164)
emails	string[]	yes	Normalised email addresses (lowercased)
primaryPhone	string \| null	yes	First/primary phone, or null
primaryEmail	string \| null	yes	First/primary email, or null
contactId	string	yes	Underlying Contact record id
company	string \| null	yes	-
source	string \| null	yes	Free-text source label e.g. "website", "referral"
status	enum (NOT_CONTACTED \| CONTACTED \| QUALIFIED \| CONVERTED \| LOST)	yes	-
notes	string \| null	yes	-
nextCallAt	string \| null	yes	ISO timestamp of the next scheduled call
createdAt	string	yes	-
updatedAt	string	yes	-
assignedToId	string \| null	yes	OrgMember id
clientId	string \| null	yes	Client id this lead is linked to

Example response

{
  "data": [
    {
      "id": "65f0a000a000a000a000a001",
      "name": "Acme Co - Jane Doe",
      "phones": [
        "+14155550101"
      ],
      "emails": [
        "jane@acme.com"
      ],
      "primaryPhone": "+14155550101",
      "primaryEmail": "jane@acme.com",
      "contactId": "65f0a000a000a000a000a002",
      "company": "Acme Co",
      "source": "website",
      "status": "QUALIFIED",
      "notes": null,
      "nextCallAt": "2026-05-02T10:30:00.000Z",
      "createdAt": "2026-04-21T09:00:00.000Z",
      "updatedAt": "2026-04-28T16:14:00.000Z",
      "assignedToId": "65e0a000a000a000a000a000",
      "clientId": null
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 137,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

cURL

curl -X GET 'https://your-host/api/v1/leads' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Try it

GET/api/v1/leads

The playground sends real requests against your org. Sign in to spin up a 1-hour test token. You need DEVELOPER permission and the DEVELOPER_API feature enabled in the org.

Query

status

Filter by exact status

Case-insensitive match against contact name, email, phone, or company

assignedToId

OrgMember id, or the literal string "unassigned" for leads with no owner

page

1-indexed page number. Defaults to 1.

pageSize

Items per page (1–100). Defaults to 50.