# Search your CRM's people

Source: https://help.ruuster.com/api/crm-people

```http
GET https://api.ruuster.com/v1/crm/people
```

People from your CRM's own search (by name, email or phone, stage, tag, pond, agent, smart list or recent CRM activity), each with their Ruuster activity over the last N days. CRM-first lookups joined with Ruuster in one call.

- 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
- Your CRM: `x-crm-vendor` and `x-crm-key` headers with your CRM's API key, used for this request only. See [Connect your CRM](https://help.ruuster.com/api/crm)
- Rows count against the daily lead-row quota (50,000 by default)

Starts from your CRM: search it the way you would in the CRM, and every person comes back with what they did on your Ruuster sites, matched by the CRM id Ruuster's CRM sync stored on the lead (`crmExternalId`). Use it for "show me the people in the Inactive Buyers pond and whether they're active on our site", or to find one person before [Get one CRM person](https://help.ruuster.com/api/crm-person).

For Ruuster-first questions across many leads (everyone who viewed listings, counted by pond), use [Find engaged leads your CRM hasn't called](https://help.ruuster.com/api/leads-follow-up) and [Count engaged leads by CRM pond, stage, agent or tag](https://help.ruuster.com/api/leads-crm-segments) instead: one search here returns at most 100 people.

Reads your CRM live with the key in `x-crm-vendor` and `x-crm-key` (one to three CRM calls; the key is used for this request only). Filters each CRM supports: Follow Up Boss all of them; Sure Send all but `pond` and `sort=lastCall`; Sierra `query`, `stage` (a lead status), `tag`, `assignedUserId` and `sort=recent|newest`.

## Query parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `query` | string | | A name, email address or phone number |
| `stage` | string | | A CRM stage name (Sierra: a lead status such as `Active`) |
| `tag` | string | | A CRM tag |
| `pond` | string | | A pond id or name (Follow Up Boss). A name that matches several ponds asks you to choose |
| `assignedUserId` | string | | People assigned to this CRM user (ids from [Get your CRM's vocabulary](https://help.ruuster.com/api/crm-overview)) |
| `smartListId` | string | | People in this smart list (Follow Up Boss, Sure Send) |
| `activeWithinDays` | integer | | Only people with CRM activity in the last N days, 1 to 365 (Follow Up Boss, Sure Send) |
| `days` | integer | `30` | Days of Ruuster activity to attach, counting today, 1 to 93 |
| `sort` | `recent` \| `newest` \| `lastCall` | `recent` | `recent`: latest CRM activity first (Sierra: latest sign-in); `newest`: newest people first; `lastCall`: least recently called first (Follow Up Boss) |
| `limit` | integer | `25` | People returned, 1 to 100 |

## Response

| Field | Description |
|---|---|
| `people[].person` | The CRM person: `id`, `name`, `stage`, `source`, `assignedTo`, `tags`, contact details (when lead contact details are on), and the CRM's own dates such as `lastActivity`, `lastCall` and `lastCommunication` |
| `people[].pond` | The person's pond name, when the CRM says |
| `people[].ruuster` | Null when the person has no Ruuster activity in `days`; otherwise `leadId`, `level` (`any`, `viewed`, `meaningful` or `strong`), `totals` and `lastActivityAt` |
| `total` | How many people match in the CRM |
| `pond` | With `pond`, the pond it resolved to |

`meta.ponds` lists the account's ponds when no `pond` was given. Rows count against your daily lead-row quota.

## Example request

cURL:

```bash
curl -s "https://api.ruuster.com/v1/crm/people?pond=Inactive%20Buyers&sort=recent&limit=2" \
  -H "x-api-key: $RUUSTER_API_KEY" \
  -H "x-email: $RUUSTER_EMAIL" \
  -H "x-crm-vendor: fub" \
  -H "x-crm-key: $CRM_API_KEY"
```

Node.js:

```javascript
const res = await fetch("https://api.ruuster.com/v1/crm/people?pond=Inactive%20Buyers&sort=recent&limit=2", {
  headers: {
    "x-api-key": process.env.RUUSTER_API_KEY,
    "x-email": process.env.RUUSTER_EMAIL,
    "x-crm-vendor": "fub",
    "x-crm-key": process.env.CRM_API_KEY,
  },
});
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/crm/people?pond=Inactive%20Buyers&sort=recent&limit=2",
    headers={"x-api-key": os.environ["RUUSTER_API_KEY"], "x-email": os.environ["RUUSTER_EMAIL"], "x-crm-vendor": "fub", "x-crm-key": os.environ["CRM_API_KEY"]},
    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": {
    "people": [
      {
        "person": { "id": 48213, "name": "Sam Lee", "stage": "Nurture", "source": "Zillow", "assignedTo": null, "assignedUserId": null,
                    "tags": ["buyer"], "emails": ["sam.lee@example.com"], "phones": ["+15205550142"], "created": "2026-05-21T18:20:05Z",
                    "lastActivity": "2026-10-20T23:58:44Z", "lastCommunication": "2026-07-02T16:10:00Z", "lastCall": "2026-07-02T16:10:00Z",
                    "lastText": null, "lastEmail": null, "contacted": true, "price": 450000 },
        "pond": "Inactive Buyers",
        "ruuster": { "leadId": "user:c0ff3e21-8a4b-4c7d-9e15-2b6f8d3a1c04", "level": "strong",
                     "totals": { "actions": 64, "propertyViews": 31, "favorites": 4, "searches": 12, "tourRequests": 1,
                                 "contactAgentClicks": 0, "shares": 1, "logins": 5, "savedSearchEvents": 0 },
                     "lastActivityAt": "2026-10-20T23:58:44Z" }
      },
      {
        "person": { "id": 39120, "name": "Pat Morgan", "stage": "Nurture", "source": "Website", "assignedTo": null, "assignedUserId": null,
                    "tags": [], "emails": ["pat.morgan@example.com"], "phones": [], "created": "2025-11-02T10:01:44Z",
                    "lastActivity": "2026-10-11T09:12:00Z", "lastCommunication": "2026-03-14T18:00:00Z", "lastCall": null,
                    "lastText": null, "lastEmail": "2026-03-14T18:00:00Z", "contacted": true, "price": null },
        "pond": "Inactive Buyers",
        "ruuster": null
      }
    ],
    "total": 1840,
    "pond": { "id": "4", "name": "Inactive Buyers" }
  },
  "meta": {
    "range": { "from": "2026-09-23", "to": "2026-10-23", "tz": "America/Chicago" },
    "crm": { "vendor": "fub", "label": "Follow Up Boss", "source": "Follow Up Boss, live, with your API key", "calls": 2,
             "note": "1 of these 2 people have Ruuster activity in the range (matched by crmExternalId). 1,840 people match in Follow Up Boss; showing 2." }
  }
}
```