# Ruuster API

> Read-only access to engagement on a brokerage's Ruuster-powered home-search sites: listings and their views, leads and their activity, agents, the weekly analytics summary, email performance, website traffic, and lead-event webhooks. Base URL https://api.ruuster.com/v1. Authenticate every call with the `x-api-key` and `x-email` headers of a brokerage owner or admin; call it from a server, never a browser.

Every page below is Markdown. The whole documentation in one file: https://help.ruuster.com/api/llms-full.txt. OpenAPI 3.1 with parameters and example responses: https://help.ruuster.com/api/openapi.json. Use of the API is subject to the Ruuster API Terms of Use (https://help.ruuster.com/api/terms).

## Getting started

- [Overview](https://help.ruuster.com/api/overview.md): What the Ruuster API does, every call at a glance, machine-readable formats and a quick start.
- [Authentication](https://help.ruuster.com/api/authentication.md): Send your Ruuster API key and login email as headers. Only owner and admin logins can use the API.
- [Scope: what a key can see](https://help.ruuster.com/api/scope.md): What a key can see: the whole brokerage, the listings attributed to it, and lead contact details (on unless you ask for them off).
- [Rate and payload limits](https://help.ruuster.com/api/limits.md): Per-minute rate limits, daily row quotas, page sizes, range caps, and how to pull large amounts of data.
- [Conventions](https://help.ruuster.com/api/conventions.md): Response envelope, dates and time zone, ranges, granularity, pagination, coverage, identifiers, versioning and the example data.
- [MLS numbers](https://help.ruuster.com/api/mls-numbers.md): How MLS numbers are matched, with or without their leading letters, and what happens when more than one listing matches.
- [Use with AI assistants (MCP)](https://help.ruuster.com/api/mcp.md): Step by step, connect Ruuster to Claude, ChatGPT or any assistant that supports remote MCP servers, sign in once with your owner or admin email and API key, and ask about your listings, leads, traffic and CMAs in plain language.
- [Connect your CRM](https://help.ruuster.com/api/crm.md): 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.
- [Errors](https://help.ruuster.com/api/errors.md): Every error code with its HTTP status and when it happens, with example error responses.

## Account

- [Check API status (GET /status)](https://help.ruuster.com/api/status.md): Whether the API is up. Needs no authentication; use it for uptime monitors.
- [Get your account (GET /me)](https://help.ruuster.com/api/me.md): Who the key belongs to, your brokerage, MLSs, hostnames, data coverage and current limits. Call it first to check credentials.
- [Get your brand kit (GET /brand)](https://help.ruuster.com/api/brand.md): Your brokerage's name, logo, phone, website and the colors and fonts your Ruuster site is styled with, so reports and documents built from the API can carry your brand.

## Listings

- [List listings (GET /properties)](https://help.ruuster.com/api/properties-list.md): Listings attributed to your brokerage, including listings that left the market in about the last 18 months. Also finds a listing by MLS number.
- [Look up any listing by MLS number or address (GET /properties/lookup)](https://help.ruuster.com/api/properties-lookup.md): Resolve one MLS number or street address to a listing in your MLSs, whether or not it's yours. A lookup call (20 per minute). Use it to turn an MLS number or address from a buyer's email, a showing request or a user's question into a propertyId.
- [Get a listing (GET /properties/{propertyId})](https://help.ruuster.com/api/properties-get.md): One listing with its photo gallery and the home's details (beds, baths, living area, lot, year built, garage, HOA, taxes). Any listing by propertyId, whether or not it's yours; your own listings also by MLS number (mls:<number>).
- [Get listing engagement (GET /properties/{propertyId}/engagement)](https://help.ruuster.com/api/properties-engagement.md): How people engaged with one listing across Ruuster sites, by day, week or month: views, visitors, favorites, tour requests, offers, shares, contact requests and push alerts. The seller-report call. With scope=any, your own leads' activity on any one listing.
- [List engagement for all listings (GET /properties/engagement)](https://help.ruuster.com/api/properties-bulk-engagement.md): The engagement numbers for all your listings in one paged call, ranked by views, favorites, tour requests or contact requests.
- [List a listing's viewers (GET /properties/{propertyId}/viewers)](https://help.ruuster.com/api/properties-viewers.md): Your brokerage's leads who viewed, saved or requested a tour of one listing in a period, with how many times and when. Your own listings by default; any single listing with scope=any.
- [Find prospects for a listing (GET /properties/{propertyId}/prospects)](https://help.ruuster.com/api/properties-prospects.md): Reverse prospecting in one call. Your brokerage's leads whose saved searches this listing fits, by area (zip, city, or a county, school or neighborhood that contains it) and by price within a tolerance, with the matching searches. Use it to pick who to email about a new listing, a price change or an open house.

## Leads

- [List leads (GET /leads)](https://help.ruuster.com/api/leads-list.md): Your brokerage's leads, filtered by when they were created, updated or last active. Paged.
- [Find a lead (GET /leads/lookup)](https://help.ruuster.com/api/leads-lookup.md): Find your leads by email, phone or CRM id. Returns every match, with links to their activity and emails.
- [Get a lead's email status (GET /leads/email-status)](https://help.ruuster.com/api/leads-email-status.md): Ruuster's verdict on a lead's email address, by email, CRM id or lead id: valid, invalid, blocked, soft bounce, complaint, unsubscribed or unknown, with the code and reason behind it and since when.
- [Email status](https://help.ruuster.com/api/email-status.md): Ruuster's verdict on each lead's email address (valid, invalid, blocked, soft bounce, complaint, unsubscribed, unknown), how to read it, how to get it by lookup or webhook, and how to keep it in Follow Up Boss, Sure Send or Sierra Interactive through their APIs.
- [List active leads (GET /leads/activity)](https://help.ruuster.com/api/leads-active.md): Your leads with recorded activity in a period, most active first. The hot list for follow-up.
- [Map where your leads are looking (GET /leads/map)](https://help.ruuster.com/api/leads-map.md): Where your leads are looking for homes, as map-ready points. Listing views, favorites and tour requests from the last 30 days, grouped by the viewed listings' locations into clusters, ZIP codes, cities or single listings, with the top areas and the map bounds. One call for a heatmap, dot map or market map; no need to page through leads.
- [Find leads looking in an area (GET /leads/area-interest)](https://help.ruuster.com/api/leads-area-interest.md): Your leads who have been looking in a city, zip, county, school zone, neighborhood or subdivision at a price, in one call. Combines the listing views and inquiries your CRM sends back (Ylopo, Zillow, Realtor.com, your IDX site, Ruuster), views on your Ruuster site, and saved searches (Ruuster's and your CRM's). Use it for "who's been searching $500K+ in Santa Rosa Beach" or a neighborhood farming list.
- [Get new-lead stats (GET /leads/stats)](https://help.ruuster.com/api/leads-stats.md): New leads per day, week or month, optionally broken down by first-visit source and medium.
- [Get a lead's activity (GET /leads/{leadId}/activity)](https://help.ruuster.com/api/leads-activity.md): What one lead did, by day, week or month, and optionally the individual events (the same events webhooks send).
- [List a lead's emails (GET /leads/{leadId}/emails)](https://help.ruuster.com/api/leads-emails.md): Ruuster emails sent to one lead (saved-search alerts and listing updates), newest first, with delivery, opens and clicks.

## Agents

- [List agents (GET /agents)](https://help.ruuster.com/api/agents-list.md): Your brokerage's agent directory with each agent's landing page. No activity figures.
- [Get an agent (GET /agents/{agentId})](https://help.ruuster.com/api/agents-get.md): One agent in your brokerage. Use it to turn the agentId on a lead into a person.

## Brokerage

- [Get the brokerage summary (GET /summary)](https://help.ruuster.com/api/summary.md): The brokerage's numbers by week or month. Each bucket carries weeklyEmail, the exact figures Ruuster's weekly analytics email showed for that week: use those as the headline numbers in anything you show the brokerage or its clients. The measured fields beside them (human opens, signed-in leads) use stricter definitions and are expected to be lower; that is not an error, so don't report it as a discrepancy.
- [Get your account's highlights (GET /wins)](https://help.ruuster.com/api/wins.md): Highlights for the brokerage in one call. Figures that grew against the previous period of the same length, the most-viewed listings, the most engaged leads, agent activity, the hottest areas with Ruuster's share of listing views, and, for Follow Up Boss accounts, dormant leads re-engaged after a Ruuster touch. Highlights only; for every figure, including those that fell, use summary.
- [Get email stats (GET /emails/stats)](https://help.ruuster.com/api/emails-stats.md): Ruuster email sent to your leads (saved-search alerts and listing updates): sends, deliveries, human opens and clicks, optionally per saved search. These rates are stricter than the open and click rates in Ruuster's weekly analytics email, which count automatic and repeat opens; for a headline rate that matches that email, use summary's weeklyEmail figures, and present these as the detail, not as a discrepancy.
- [Get website traffic (GET /traffic)](https://help.ruuster.com/api/traffic.md): Google Analytics visits to your Ruuster hostnames by source, medium and campaign. Measured per website, so it can't be split by agent, lead or listing.

## CMA

- [Run a CMA (POST /cma)](https://help.ruuster.com/api/cma-create.md): A comparative market analysis for one home in a market your brokerage is on: subject profile, sold comps with dollar adjustments, active, pending and expired competition, market conditions, a value conclusion and a seller net sheet. Computed from MLS records; no AI text.
- [Get a CMA (GET /cma/{cmaId})](https://help.ruuster.com/api/cma-get.md): Read a CMA your brokerage ran, for 90 days after it was created. The same object Run a CMA returned, with the market as it was that day.
- [List CMAs (GET /cma)](https://help.ruuster.com/api/cma-list.md): The CMAs your brokerage ran in the last 90 days, newest first, with the subject, the indicated value and the confidence of each.

## Public records

- [Look up a public record (GET /public-records/lookup)](https://help.ruuster.com/api/public-records-lookup.md): One US home's county record by address, parcel number or propertyId, whether or not it was ever on the MLS: parcel, building facts, tax and assessed value, AVM, last sale and the loans still open, plus owner names and mailing address with include=owner. A lookup call, one home at a time.
- [Get a home's deed and mortgage history (GET /public-records/{recordId}/history)](https://help.ruuster.com/api/public-records-history.md): Every recorded transfer and mortgage on one US home, newest first, with each mortgage marked open, released or paid off. Buyer, seller and borrower names with include=owner. A lookup call, one home at a time.

## Market

- [Mortgage rates (GET /mortgage/rates)](https://help.ruuster.com/api/mortgage-rates.md): Today's national mortgage-rate averages (30- and 15-year fixed, FHA, jumbo, VA and the 10-year Treasury) and the history of one series, from public Federal Reserve data, for market context and payment illustrations.

## Your CRM

- [Find engaged leads your CRM hasn't called (GET /leads/follow-up)](https://help.ruuster.com/api/leads-follow-up.md): Leads who viewed listings (or engaged more) on your Ruuster sites in a period, whom your CRM shows no call, or no contact of any kind, for N days. Ruuster activity joined with your own CRM, live, in one call. Follow Up Boss.
- [Count engaged leads by CRM pond, stage, agent or tag (GET /leads/crm-segments)](https://help.ruuster.com/api/leads-crm-segments.md): How many of your leads engaged on your Ruuster sites in a period, counted by where they sit in your CRM (pond, stage, assigned agent or tag), optionally filtered to some ponds or stages and with the leads listed. Answers "how many leads in our inactive ponds engaged meaningfully?" in one call.
- [Search your CRM's people (GET /crm/people)](https://help.ruuster.com/api/crm-people.md): 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.
- [Get one CRM person (GET /crm/people/{crmPersonId})](https://help.ruuster.com/api/crm-person.md): One person from your CRM (profile, recent calls and texts, recent events and open tasks) with their Ruuster activity over the last N days, matched by CRM id. The two sides of one lead's story in one call.
- [Get your CRM's vocabulary (GET /crm/overview)](https://help.ruuster.com/api/crm-overview.md): Your CRM key's identity plus the account's ponds, stages, users (agents) and smart lists, with their ids. Call it once to learn the names and ids the CRM filters take (pond=, stage=, assignedUserId=).
- [Check your CRM key (GET /crm/identity)](https://help.ruuster.com/api/crm-identity.md): Whose CRM API key this is (account and user), whether it sees the whole account or one user's people, and which Ruuster and CRM joins your CRM supports. One CRM call or two; use it to confirm a CRM connection.

## Changing your CRM

- [Preview a change to your CRM (POST /crm/changes)](https://help.ruuster.com/api/crm-change-preview.md): Step one of changing your CRM. Says exactly what a change would do (add or remove tags, change stage, reassign, add a note or a task) to each person, with warnings, and records the request. Writes NOTHING to your CRM; nothing changes until you confirm the preview with Apply a change.
- [Apply a change to your CRM (POST /crm/changes/{changeId}/apply)](https://help.ruuster.com/api/crm-change-apply.md): Step two of changing your CRM. Confirms a previewed change and makes it in your CRM, person by person, checking each one against what the CRM answers. Needs confirm=true from the person who previewed it. Large changes run in batches; call again with the same changeId to continue.
- [Cancel a change to your CRM (POST /crm/changes/{changeId}/cancel)](https://help.ruuster.com/api/crm-change-cancel.md): Stops a change that hasn't finished. A preview that was never applied is closed; a change still applying stops, and the people it hadn't reached yet are marked cancelled. Anyone already changed stays changed (preview an undo to reverse them).
- [List CRM changes (GET /crm/changes)](https://help.ruuster.com/api/crm-changes-list.md): The audit record of changes made to your CRM through Ruuster, newest first. Every request (in the person's words), who asked and from where, what it did, when it was confirmed and completed, and how many people were changed, skipped or failed, including previews that were never confirmed.
- [Get a CRM change (GET /crm/changes/{changeId})](https://help.ruuster.com/api/crm-change-get.md): One change made to your CRM through Ruuster, in full: the request, every person with the values before and after (as the CRM confirmed them) and whether they were done, skipped or failed and why, and the history of every call against the change.

## Webhooks

- [Webhooks: subscribing to events](https://help.ruuster.com/api/webhooks.md): Subscribe a URL to lead events: who can subscribe, the subscription calls and the endpoint rules.
- [Webhooks: event catalog](https://help.ruuster.com/api/webhook-events.md): Every lead event kind, the event envelope, the objects inside it, and example payloads.
- [Webhooks: receiving and verifying](https://help.ruuster.com/api/webhook-verifying.md): Delivery headers, verifying the signature in Node and Python, retries, batching and other delivery behavior.
- [Webhooks: replay and the event feed](https://help.ruuster.com/api/webhook-replay.md): Re-send missed events, poll the event feed instead of receiving webhooks, and use webhooks with Zapier.

## Webhook subscriptions

- [List event kinds (GET /webhooks/events)](https://help.ruuster.com/api/webhooks-event-kinds.md): The webhook event catalog: every event kind you can subscribe to, which are high volume, and a sample payload for each.
- [List subscriptions (GET /webhooks)](https://help.ruuster.com/api/webhooks-list.md): Every webhook subscription in your brokerage, with delivery health for the last 24 hours.
- [Create a subscription (POST /webhooks)](https://help.ruuster.com/api/webhooks-create.md): Subscribe a URL you host to lead events. Returns 201 and the signing secret, which is shown only once.
- [Get a subscription (GET /webhooks/{webhookId})](https://help.ruuster.com/api/webhooks-get.md): One webhook subscription with its delivery health.
- [Update a subscription (PATCH /webhooks/{webhookId})](https://help.ruuster.com/api/webhooks-update.md): Change a subscription's URL, events, description, or pause and re-activate it.
- [Delete a subscription (DELETE /webhooks/{webhookId})](https://help.ruuster.com/api/webhooks-delete.md): Delete a webhook subscription. Pending deliveries are dropped.
- [Send a test event (POST /webhooks/{webhookId}/test)](https://help.ruuster.com/api/webhooks-test.md): Send a webhook.test event to the subscription's URL now and return what your endpoint answered.
- [Rotate the signing secret (POST /webhooks/{webhookId}/rotate-secret)](https://help.ruuster.com/api/webhooks-rotate-secret.md): Issue a new signing secret. The old one keeps signing alongside it for 24 hours.
- [List deliveries (GET /webhooks/{webhookId}/deliveries)](https://help.ruuster.com/api/webhooks-deliveries.md): Delivery attempts for one subscription from the last 30 days, newest first.
- [Replay events (POST /webhooks/{webhookId}/replay)](https://help.ruuster.com/api/webhooks-replay.md): Re-send a subscription's events from a time window, with their original ids.
- [Poll the event feed (GET /events)](https://help.ruuster.com/api/events-feed.md): Read the same lead events webhooks send, by polling. No subscription needed; events are kept 30 days.

## Guides

- [Guides](https://help.ruuster.com/api/guides.md): Worked recipes: seller reports, top listings, Google Sheets, lead sources next to traffic, lead lookup, hot-lead alerts, catching up and a nightly sync.
- [CMAs](https://help.ruuster.com/api/cma.md): How Run a CMA chooses comparable sales, what each dollar adjustment is based on, how the value conclusion is reached, the daily allowance, and what a CMA from this API is not.
- [Data notes](https://help.ruuster.com/api/data-notes.md): What the numbers mean and their limits: time zone, perspectives, reloads, freshness, history, attribution and email opens.
- [Changelog](https://help.ruuster.com/api/changelog.md): Releases and planned additions.
- [Support and terms](https://help.ruuster.com/api/support.md): How to get help, and a summary of the terms.
- [Ruuster API Terms of Use](https://help.ruuster.com/api/terms.md): The Ruuster API Terms of Use, which govern all use of the API.