List an agent's leads
list_leadsRead-onlyIdempotent
List an agent's leads
Pinned leads (pinned: true) come first, on the first page only, then the rest newest
first. Later pages never contain pinned leads, so if more leads are pinned than limit,
the extra ones are not returned: use a limit (up to 100) above the number of pinned
leads. The filters (status, search, creation dates, assignee and custom fields) combine:
a lead is listed only when it matches all of those sent.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, 1 to 100 (values outside are clamped). Default 20. | |
| cursor | No | Opaque cursor from the previous page's `next_cursor`. Omit for the first page. A cursor the API didn't return is `422 invalid_request`. | |
| search | No | Matches the name or phone. | |
| status | No | One or more of the agent's lead statuses, comma-separated, written exactly as `listLeadFields` returns them. | |
| date_to | No | Only those created on or before this date (UTC), the whole day included. Send a date such as `2026-10-11`; a date-time is read as its date. | |
| agent_id | Yes | The agent the resource belongs to. Another company's agent, or the nil UUID, is `404 agent_not_found`; an agent outside the key's agent list is `403 agent_not_authorized`. | |
| date_from | No | Only those created on or after this date (UTC). Send a date such as `2026-10-01`; a date-time is read as its date. | |
| assigned_to | No | Only the leads assigned to this teammate (a `user_id` from `listAgentMembers`), or `unassigned` for the leads assigned to no one. `me` isn't taken, because a key isn't a person; it and any other value are `422 invalid_request_body`. | |
| custom_fields | No | Only the leads whose custom fields match: a URL-encoded JSON object that maps a field's key (from `listLeadFields`) to a clause, such as `{"city": {"op": "eq", "values": ["Cairo"]}, "budget": {"op": "is_null"}}`. `op` is `eq` (one value), `in` (one or more), `ilike` (one value the field contains, ignoring case, where `%` and `_` are wildcards), `between` (two values: from the first, included, to the second, excluded) or `is_null` (no `values`). Values are JSON strings, numbers or booleans, compared with the stored value as text: write dates `YYYY-MM-DD` for `between`, and don't expect numbers to compare by size. Clauses combine with AND. A lead without the key reads as null there: it matches `is_null` and no other op. At most 10 keys and 100 values in all; anything else is `422 invalid_request_body`. |