# List leads

Source: https://help.ruuster.com/api/leads-list

```http
GET https://api.ruuster.com/v1/leads
```

Your brokerage's leads, filtered by when they were created, updated or last active. Paged.

- Authentication: `x-api-key` and `x-email` headers of an owner or admin
- Rate limit: *lookup* call, 20 per minute per key, within the 120 per minute
- Rows count against the daily lead-row quota (50,000 by default)

## Query parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `dateField` | string | `created` | Which date `from` and `to` filter on: `created`, `active` (any recorded activity in the range) or `updated` |
| `from` | date | | First day, `YYYY-MM-DD`, included. No date filter when omitted, except `active`, which defaults to the last 30 days |
| `to` | date | | Day after the last day, `YYYY-MM-DD`, excluded |
| `type` | string | `all` | `user` (has a Ruuster account), `unregistered` (CRM-only contact) or `all` |
| `cursor` | string | | `meta.nextCursor` from the previous page. Omit for the first page |
| `limit` | integer | `100` | Rows per page, 1 to 200 |
| `countOnly` | `0` \| `1` | `0` | `1` returns `{ "total": n }` and no rows |

## Response

`data.leads` is a list of lead objects; `meta.total` and `meta.nextCursor` page through them. Rows count against your daily lead-row quota.

## Lead object

| Field | Description |
|---|---|
| `leadId` | `user:<uuid>` (has a Ruuster account) or `unregistered:<uuid>` (a contact synced from your CRM). Use the whole value |
| `firstName`, `lastName` | |
| `email`, `phone` | Only when lead contact details are on for your brokerage (see `leadContactDetails` in [/me](https://help.ruuster.com/api/me)) |
| `crmExternalId` | The lead's id in your CRM, for example the Follow Up Boss person id |
| `crmStatus`, `crmTags` | From your CRM. `crmStatus` can be empty for CRM-only contacts |
| `agentId` | The lead's assigned agent. Look it up with [Get an agent](https://help.ruuster.com/api/agents-get) |
| `source` | First recorded visit, when known: `utmSource`, `utmMedium`, `utmCampaign`, `firstSeenAt` |
| `createdAt`, `createdAtInCrm` | When Ruuster first saw the lead, and when your CRM did |
| `lastLoginAt`, `lastActivityAt`, `updatedAt` | |

## Example request

cURL:

```bash
curl -s "https://api.ruuster.com/v1/leads?dateField=created&from=2026-09-21&to=2026-09-28&limit=2" \
  -H "x-api-key: $RUUSTER_API_KEY" \
  -H "x-email: $RUUSTER_EMAIL"
```

Node.js:

```javascript
const res = await fetch("https://api.ruuster.com/v1/leads?dateField=created&from=2026-09-21&to=2026-09-28&limit=2", {
  headers: {
    "x-api-key": process.env.RUUSTER_API_KEY,
    "x-email": process.env.RUUSTER_EMAIL,
  },
});
const body = await res.json();
if (!body.ok) throw new Error(`${body.error.code}: ${body.error.message} (${body.requestId})`);
console.log(body.data);
```

Python:

```python
import os
import requests

res = requests.get(
    "https://api.ruuster.com/v1/leads?dateField=created&from=2026-09-21&to=2026-09-28&limit=2",
    headers={"x-api-key": os.environ["RUUSTER_API_KEY"], "x-email": os.environ["RUUSTER_EMAIL"]},
    timeout=30,
)
body = res.json()
if not body["ok"]:
    raise RuntimeError(f'{body["error"]["code"]}: {body["error"]["message"]} ({body.get("requestId")})')
print(body["data"])
```

## Example response

```json
{
  "ok": true,
  "data": {
    "leads": [
      {
        "leadId": "user:c0ff3e21-8a4b-4c7d-9e15-2b6f8d3a1c04",
        "firstName": "Sam", "lastName": "Lee", "email": "sam.lee@example.com", "phone": "+15205550142",
        "crmExternalId": "48213", "crmStatus": "Showing Homes Nurture", "crmTags": ["buyer", "tucson"],
        "agentId": "7c1e9b42-3d85-4a6f-9e07-1b2c8d4f5a69",
        "source": { "utmSource": "facebook", "utmMedium": "paid_social", "utmCampaign": "fall-buyers", "firstSeenAt": "2026-09-21T18:02:44Z" },
        "createdAt": "2026-09-21T18:20:05Z", "createdAtInCrm": "2026-09-21T18:20:01Z",
        "lastLoginAt": "2026-09-30T02:11:40Z", "lastActivityAt": "2026-09-30T23:58:44Z",
        "updatedAt": "2026-09-30T03:10:00Z"
      },
      {
        "leadId": "unregistered:8d2b6f19-4e37-4a85-b0c9-7f1e3d5a2b68",
        "firstName": "Priya", "lastName": "Shah", "email": "priya.shah@example.com", "phone": "+15205550187",
        "crmExternalId": "51907", "crmStatus": null, "crmTags": ["seller-lead"],
        "agentId": "e5a7d3c1-9b46-4f28-8c0e-6d2a1f7b3e95",
        "source": { "utmSource": "sendGrid", "utmMedium": "sendGridEmails", "utmCampaign": "savedSearches", "firstSeenAt": "2026-09-24T17:50:10Z" },
        "createdAt": "2026-09-23T15:44:12Z", "createdAtInCrm": "2026-09-23T15:40:00Z",
        "lastLoginAt": null, "lastActivityAt": "2026-09-30T19:07:56Z",
        "updatedAt": "2026-09-26T16:10:00Z"
      }
    ]
  },
  "meta": { "range": { "from": "2026-09-21", "to": "2026-09-28", "tz": "America/Chicago" }, "total": 163, "nextCursor": "cur_r5Lm1xPq7Lm3XvT8wR" }
}
```