# Overview

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

> What the Ruuster API does, every call at a glance, machine-readable formats and a quick start.

The Ruuster API gives your brokerage read access to how people engage with your Ruuster-powered
websites and apps: your listings, your leads, your email, and your site traffic. Use it
to build seller reports, feed a data warehouse, judge marketing spend, or alert your team when a
lead does something worth a call.

**Calls at a glance.** Each call has its own reference page with parameters, response fields, code samples and an example response.

| Group | Call | What it does |
|---|---|---|
| Account | [`GET /status`](https://help.ruuster.com/api/status) | Check the API is up (no key needed) |
| Account | [`GET /brand`](https://help.ruuster.com/api/brand) | Your name, logo, phone, website, colors and fonts, for branded reports |
| Account | [`GET /me`](https://help.ruuster.com/api/me) | Your key, role, brokerage, limits and which days have data |
| Listings | [`GET /properties`](https://help.ruuster.com/api/properties-list) | Your listings; find one by MLS number |
| Listings | [`GET /properties/lookup`](https://help.ruuster.com/api/properties-lookup) | Any listing in your MLSs by MLS number, yours or not |
| Listings | [`GET /properties/{propertyId}`](https://help.ruuster.com/api/properties-get) | Any listing by id, with its photos |
| Listings | [`GET /properties/{propertyId}/engagement`](https://help.ruuster.com/api/properties-engagement) | A listing's views, visitors, favorites, tour requests, offers, shares, contact requests and push alerts; or your leads' activity on any one listing with `scope=any` |
| Listings | [`GET /properties/engagement`](https://help.ruuster.com/api/properties-bulk-engagement) | The same numbers for every listing, ranked |
| Listings | [`GET /properties/{propertyId}/viewers`](https://help.ruuster.com/api/properties-viewers) | Your leads who viewed, saved or toured a listing: yours by default, or any one listing with `scope=any` |
| Leads | [`GET /leads`](https://help.ruuster.com/api/leads-list) | List leads by created, updated or active date |
| Leads | [`GET /leads/lookup`](https://help.ruuster.com/api/leads-lookup) | Find a lead by email, phone or CRM id |
| Leads | [`GET /leads/activity`](https://help.ruuster.com/api/leads-active) | Your most active leads in a period |
| Leads | [`GET /leads/stats`](https://help.ruuster.com/api/leads-stats) | New leads per period, by source |
| Leads | [`GET /leads/{leadId}/activity`](https://help.ruuster.com/api/leads-activity) | What a lead did, and their individual events |
| Leads | [`GET /leads/{leadId}/emails`](https://help.ruuster.com/api/leads-emails) | Ruuster emails a lead received |
| Agents | [`GET /agents`](https://help.ruuster.com/api/agents-list) | Your agent roster and landing pages |
| Agents | [`GET /agents/{agentId}`](https://help.ruuster.com/api/agents-get) | One agent; match a lead's `agentId` to a person |
| Brokerage | [`GET /summary`](https://help.ruuster.com/api/summary) | The weekly analytics email as data |
| Brokerage | [`GET /emails/stats`](https://help.ruuster.com/api/emails-stats) | Email sends, human opens and clicks |
| Brokerage | [`GET /traffic`](https://help.ruuster.com/api/traffic) | Website visits by source, medium and campaign |
| AI assistants | [Use with AI assistants (MCP)](https://help.ruuster.com/api/mcp) | Connect the API to Claude, ChatGPT or any MCP client at `https://mcp.ruuster.com` and ask in plain language |
| CMA | [`POST /cma`](https://help.ruuster.com/api/cma-create), [`GET /cma/{cmaId}`](https://help.ruuster.com/api/cma-get), [`GET /cma`](https://help.ruuster.com/api/cma-list) | A comparative market analysis for any home in your MLSs: comps, adjustments, market conditions, value conclusion, net sheet. See [CMAs](https://help.ruuster.com/api/cma) |
| Webhooks | [`GET /webhooks/events`](https://help.ruuster.com/api/webhooks-event-kinds) | The event catalog with sample payloads |
| Webhooks | [`GET /webhooks`](https://help.ruuster.com/api/webhooks-list) | Your subscriptions and their delivery health |
| Webhooks | [`POST /webhooks`](https://help.ruuster.com/api/webhooks-create) | Subscribe a URL to lead events |
| Webhooks | [`GET /webhooks/{webhookId}`](https://help.ruuster.com/api/webhooks-get) | One subscription |
| Webhooks | [`PATCH /webhooks/{webhookId}`](https://help.ruuster.com/api/webhooks-update) | Change, pause or re-activate a subscription |
| Webhooks | [`DELETE /webhooks/{webhookId}`](https://help.ruuster.com/api/webhooks-delete) | Delete a subscription |
| Webhooks | [`POST /webhooks/{webhookId}/test`](https://help.ruuster.com/api/webhooks-test) | Send a test event |
| Webhooks | [`POST /webhooks/{webhookId}/rotate-secret`](https://help.ruuster.com/api/webhooks-rotate-secret) | Issue a new signing secret |
| Webhooks | [`GET /webhooks/{webhookId}/deliveries`](https://help.ruuster.com/api/webhooks-deliveries) | Delivery attempts from the last 30 days |
| Webhooks | [`POST /webhooks/{webhookId}/replay`](https://help.ruuster.com/api/webhooks-replay) | Re-send events from a window |
| Event feed | [`GET /events`](https://help.ruuster.com/api/events-feed) | Poll the same lead events instead of receiving them |

**For AI agents and tools.** Every page is also available as Markdown: add `.md` to its URL, for example
`https://help.ruuster.com/api/properties-engagement.md`. `https://help.ruuster.com/api/llms.txt` indexes every page, `https://help.ruuster.com/api/llms-full.txt` is the whole
documentation in one file, and `https://help.ruuster.com/api/openapi.json` is the OpenAPI 3.1 description with every
parameter and an example response for each call.

**Webhook options at a glance**
- **Events:** 12 lead events. These are lead created, listing viewed, listing favorited, saved search
  created or updated, search run, email opened, email clicked, tour requested, agent contacted, signed
  in, and listing shared. There's also a test event. Subscribe to any of them, or to `lead.*` for all.
- **Delivery:** a signed `POST` to your HTTPS URL, typically within 15 minutes, delivered at least
  once, with automatic retries for about a day and batching when volume is high.
- **Control:** up to 10 subscriptions per brokerage. You can pause, edit or delete them, send a test,
  rotate the signing secret, see 30 days of delivery attempts, and replay up to 7 days at a time.
- **No endpoint?** Poll `GET /events` for the same events, kept for 30 days.

| | |
|---|---|
| Base URL | `https://api.ruuster.com/v1` |
| Format | JSON over HTTPS, UTF-8 |
| Authentication | Your Ruuster API key and login email, sent as headers |
| Access | Enabled per brokerage by your Ruuster customer success manager |
| Spec | `https://api.ruuster.com/openapi.json` (OpenAPI 3.1) |
| Status | `https://api.ruuster.com/v1/status` |

**What you can do**
- **Listings.** See every listing attributed to your brokerage, and for each one: views by the public
  and by logged-in leads, favorites, tour requests, offers, shares, contact-agent requests and push
  alerts, by day, week or month.
- **Leads.** List your leads, look one up by email, phone or CRM id, see the activity Ruuster records
  for a lead, see the Ruuster emails they received, and count new leads by source.
- **Agents.** Get your agent roster with each agent's landing page URL.
- **Brokerage.** Get the numbers from Ruuster's weekly analytics email as data, email performance, and
  website traffic by source.
- **Webhooks.** Have lead activity pushed to your server, typically within 15 minutes.

**Terms.** Use of the API is subject to the [Ruuster API Terms of Use](https://help.ruuster.com/api/terms), which supplement
your Ruuster subscription agreement. Calling the API means your brokerage accepts them.

**What it isn't**
- It's read-only for your Ruuster data. Nothing you call changes anything in Ruuster. The only write calls
  manage your own webhook subscriptions and, if you allow it, make changes you preview and confirm in your
  own CRM ([Connect your CRM](https://help.ruuster.com/api/crm)).
- It doesn't return other brokerages' data, or anyone's billing, contract or CRM records.
- It's for brokerage owners and admins. Agent logins can't use it. It lists your agents, but it doesn't
  report agent activity.
- It isn't an audited record or a real-time feed, and v1 has no uptime or accuracy guarantee.

**What to expect from the numbers.** The API reports what Ruuster records and what Google Analytics
measures, each with its own definitions and limits:
- Page views count reloads.
- Public visitor counts come from Google Analytics and leave out people who block analytics.
- Email opens leave out opens that look automated. That filter is best-effort.
- Listing attribution depends on the MLS ids on your agents' Ruuster profiles.
- Figures for recent days can change as late data arrives. Use `meta.coverage` to see which days are
  final.

Use the API as a reporting and automation source, and check anything you publish to a seller
against the [Data notes](https://help.ruuster.com/api/data-notes).

**Quick start**

> **Before you start: ask Ruuster to turn on API access.** Access is enabled per brokerage, and
> only brokerage owners and admins can use the API. To get started, have an owner or admin at your
> brokerage email **support@ruuster.com** with your brokerage name. Ruuster enables the brokerage,
> confirms where to find your API key, and tells you when the first data is ready (usually within
> an hour; history fills in over the following days).

> **Looking for recipes?** Worked, copy-and-paste use cases live in [Guides](https://help.ruuster.com/api/guides):
> a weekly seller report, your most-viewed listings, a monthly summary into Google Sheets, lead sources
> next to website traffic, finding a lead by phone, hot-lead alerts into your CRM, catching up after
> an outage, and a nightly sync into your own database.

1. Once Ruuster confirms your brokerage is enabled, sign in to the Ruuster web app as an owner or
   admin and copy your API key from the Zapier integration settings.
2. Call `/me` to check your credentials:

```bash
curl -s https://api.ruuster.com/v1/me \
  -H "x-api-key: $RUUSTER_API_KEY" \
  -H "x-email: you@yourbrokerage.com"
```

A `200` with your name, role and brokerage means you're ready. A `403 brokerage_not_enabled`
means your brokerage isn't enabled yet (see the box above); `403 role_not_permitted` means the key belongs to an agent.