# Connect your CRM

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

> Add your CRM's API key (Follow Up Boss, Sierra Interactive or Sure Send) to ask questions that need both sides, such as which leads viewed listings on your Ruuster site but haven't been called in a month, or how many leads in your inactive ponds engaged meaningfully. How the key is used, what each CRM supports, and how leads are matched.

Ruuster knows what your leads do on your Ruuster sites: the listings they view, save and ask about. Your CRM knows the rest: who called them, which pond or stage they're in, who they're assigned to. With your CRM's API key, the CRM calls put the two together, so one question answers both:

- "Which leads have viewed properties on our site but haven't been called in the last month?" ([Find engaged leads your CRM hasn't called](https://help.ruuster.com/api/leads-follow-up))
- "How many leads in our inactive ponds have engaged meaningfully with Ruuster?" ([Count engaged leads by CRM pond, stage, agent or tag](https://help.ruuster.com/api/leads-crm-segments))
- "Show me the people in the Inactive Buyers pond and whether they're active on our site." ([Search your CRM's people](https://help.ruuster.com/api/crm-people))
- "Tell me everything about Sam Lee: what he looked at, and when we last called him." ([Get one CRM person](https://help.ruuster.com/api/crm-person))

## In an AI assistant (MCP)

On the Ruuster connect screen, under **Your CRM (optional)**, pick your CRM and paste its API key, then
connect as usual. Ruuster checks the key before connecting, keeps it encrypted with that one connection,
and uses it only for the CRM tools (`leads_follow_up`, `leads_crm_segments`, `crm_people`, `crm_person`,
`crm_overview`, `crm_identity`, and, if you tick **Let the assistant make changes**, `crm_change_preview`
and `crm_change_apply`; `crm_changes_list` and `crm_change_get` show the record). Already connected
without one? Disconnect Ruuster in your assistant and connect again with your CRM picked. To stop CRM
access, disconnect, or rotate the key in your CRM. See
[Use with AI assistants (MCP)](https://help.ruuster.com/api/mcp).

Where to find the key:

- **Follow Up Boss:** create an API key under Admin › API. Use a broker's or the owner's key: an agent's key may see only that agent's people.
- **Sierra Interactive:** your site's API key, from your Sierra admin (Sierra support can turn API access on). Sierra keys are site-wide.
- **Sure Send:** an API key from your Sure Send account settings. A team key sees everyone; a user key sees only that user's people.

Your CRM may already be connected to Ruuster for the lead sync; that connection stays as it is. The key
you add here is separate and belongs to you. It only reads, unless you allow changes (below).

## With the API

Send two more headers on the CRM calls:

```bash
curl -s "https://api.ruuster.com/v1/leads/follow-up?quietDays=30" \
  -H "x-api-key: $RUUSTER_API_KEY" \
  -H "x-email: $RUUSTER_EMAIL" \
  -H "x-crm-vendor: fub" \
  -H "x-crm-key: $FUB_API_KEY"
```

`x-crm-vendor` is `fub`, `sierra` or `suresend`. Ruuster uses the key for that request only: it is
never stored, logged or sent anywhere but your CRM's own API, and only to read (`GET`). Calls without
the headers answer `400 crm_not_connected`.

## Changing your CRM

Ruuster can also make changes in your CRM for you: add or remove tags, change stage, reassign people to an
agent, add a note, or create a task, for up to 500 people at a time. **Follow Up Boss** only for now (see
[What each CRM supports](#what-each-crm-supports)). It is off unless you turn it on: in an AI assistant,
tick **Let the assistant make changes** under Your CRM on the connect screen; with the API, send
`x-crm-write: allow` on the change calls.

Every change takes two steps, and nothing is written in the first:

1. **Preview** ([Preview a change to your CRM](https://help.ruuster.com/api/crm-change-preview)). Ruuster
   reads each person from your CRM and shows their before and after, skips anyone already that way, and
   lists what to consider (tags and stages can start automations and action plans in your CRM that email or
   text the lead; reassigning notifies the new agent). The request, in your words, is recorded.
2. **Confirm** ([Apply a change](https://help.ruuster.com/api/crm-change-apply)). Only the person who
   previewed it can confirm it, no sooner than 8 seconds and no later than 15 minutes after the preview,
   with a key for the same CRM account. An assistant connected to Ruuster is told to show you the preview
   and ask "Are you sure?" first, and never to confirm for you. Ruuster then changes each person one at a
   time and checks the result against what your CRM answers; anything the CRM didn't apply is reported as
   failed, never as done.

What Ruuster never does: delete or merge people, delete notes or tasks, change contact details, or send
anything to a lead. A tag, stage or assignment change can be undone by previewing `action: "undo"` with the
change's id: only what that change did is reversed, and anyone changed again since is left alone. Notes and
tasks are removed in your CRM itself.

**The record.** Every change is kept and can't be deleted: the request in the person's words, who asked
(their Ruuster login, and whether through an AI assistant), the action and its values, the warnings shown,
when it was confirmed and finished, and for every person the values before and after and whether they were
changed, skipped or failed and why, with the history of every call against the change, including refused
confirmations. See [List CRM changes](https://help.ruuster.com/api/crm-changes-list) and
[Get a CRM change](https://help.ruuster.com/api/crm-change-get). Reads of your CRM are on record too: which
calls were made and with which filters (search text and keys are never stored).

## How leads are matched

Every lead your CRM sync brought into Ruuster carries its CRM person id as `crmExternalId`. The joins
use only that id: a lead without one is counted as `notLinkedToCrm`, never guessed by name or email. A
CRM id the key doesn't return (the person was deleted, trashed or merged, or the key can't see them) is
counted as `notFoundInCrm`. If only a small share is found, the answer says so: the key may be for a
different CRM account than the one your Ruuster site syncs with.

## Engagement levels

| Level | Means |
|---|---|
| `any` | Any recorded activity on your Ruuster sites (listing views, searches, saves, sign-ins) |
| `viewed` | Viewed at least one listing |
| `meaningful` | 3 or more listing views, or any favorite, tour request, contact-agent click or share |
| `strong` | A tour request or contact-agent click, 10 or more listing views, or 2 or more favorites |

Email opens never count (machine opens are common), and neither do sign-ins, searches or saved-search
changes on their own.

## What each CRM supports

| | Follow Up Boss | Sure Send | Sierra Interactive |
|---|---|---|---|
| [Find engaged leads your CRM hasn't called](https://help.ruuster.com/api/leads-follow-up) | Yes | Not yet | No: Sierra keeps no calls |
| [Segments](https://help.ruuster.com/api/leads-crm-segments) by pond and agent | Yes, live | Not yet | Not yet |
| Segments by stage and tag | Yes, live | From Ruuster's synced copy | From Ruuster's synced copy |
| [Search people](https://help.ruuster.com/api/crm-people) | Yes | Yes (no pond filter) | Yes (status, tag, agent) |
| [One person](https://help.ruuster.com/api/crm-person) | Calls, texts, events, tasks | Calls, texts, events | Notes |
| [Changes](https://help.ruuster.com/api/crm-change-preview) (tags, stage, assignment, notes, tasks) | Yes | Not yet | Not yet: Sierra's lead update can reset a lead's type, so it waits for testing |

Follow Up Boss looks up to 100 people per call, so a join checks up to 2,000 engaged leads in about
20 CRM calls. Sure Send and Sierra can only be asked one person at a time, which is why their joins are
narrower.

## Limits

CRM calls are lookup calls (20 per minute per key), and one CRM call runs at a time per brokerage, so
your CRM's own rate limit is never strained. Your CRM's limits still apply: if it is busy, the API
answers `429 crm_rate_limited` with `Retry-After`. If it refuses the key, `403 crm_key_rejected`; if it
is slow or down, `503 crm_unavailable`. See [Errors](https://help.ruuster.com/api/errors).