API Reference / List leads
List leads
Leads newest first with status, score, primary contact and your own columns, paged by an opaque cursor. Draft bodies are only on GET /leads/{id}.
Last updated
curl -H "Authorization: Bearer $REVNU_API_TOKEN" "https://revnu.com/api/v1/leads?status=replied&limit=50"Query
| Param | Meaning |
|---|---|
status |
Filter by lead status. |
limit |
1 to 100. |
cursor |
The nextCursor from the previous page. |
workflowRunId |
Only the leads this workflow run created or added people to (a run id from GET /workflows/{id}/runs). Each lead then also has runContactIds, the contacts this run created, and runCreatedLead, true when the run created the lead itself. |
Response
{ "leads": [lead, …], "nextCursor": "…" | null }. A page is bounded in rows and in bytes, so pass nextCursor back until it is null.
A lead is { id, domain, companyName, status, replyKind, declineReason, score, scoreReasons, vertical, archetype, tags, fields, contact, createdAt, workflowRunId }, plus runContactIds and runCreatedLead when you pass workflowRunId. workflowRunId is the workflow run that created the lead, or null. fields is your account's configured lead columns, exactly the dashboard table, as [{ key, value }] entries with each value cut at 1,000 characters, for example [{ "key": "account_case", "value": "…" }, { "key": "slack_thread", "value": "1790064680.268899" }]. The list never carries the draft or the research behind a value; read GET /leads/{id} for those.
| Code | Meaning |
|---|---|
| 404 | workflowRunId is not one of your workflow runs. |
Agents: this page is also markdown at /docs/leads.md, answers Accept: text/markdown, and is listed in /docs/llms.txt.
Frequently Asked Questions
`leads:read`. A token without it gets `403` with `requiredScope` in the body. `GET /me` shows a token's scopes.