List a listing's viewers
https://api.ruuster.com/v1/properties/{propertyId}/viewersYour 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.
- Authentication:
x-api-keyandx-emailheaders of an owner or admin - Rate limit: 120 requests per minute per key
- Rows count against the daily lead-row quota (50,000 by default)
The people behind a listing's engagement, as far as Ruuster can name them: only leads who belong to your brokerage are listed. Anonymous visitors are counted in Get listing engagement but can't be listed, and another brokerage's lead who viewed your listing on their site never appears here.
By default the listing must be one of yours, and you can pass mls:<number> in place of the id to find it by MLS number. With scope=any you can ask about one listing that isn't yours (a home one of your buyers looked at, say), by propertyId only; the answer is still limited to your own leads. It is always one listing per call: there is no call that lists viewers across many listings, and nothing enumerates listings beyond your own inventory.
Path parameters
| Name | Type | Description |
|---|---|---|
propertyId |
string | The listing's propertyId (uuid), or mls:<number> to find it by MLS number. See MLS numbers |
Query parameters
| Name | Type | Default | Description |
|---|---|---|---|
from |
date | 30 days before to |
First day, YYYY-MM-DD in America/Chicago, included |
to |
date | today | Day after the last day, YYYY-MM-DD, excluded |
scope |
string | brokerage |
brokerage: the listing must be attributed to your brokerage (MLS-number lookup allowed). any: any single listing your leads viewed, identified by propertyId |
sort |
string | views |
views (most views first) or lastViewedAt (most recent first) |
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 |
agent |
string | your default agent | Whose page the listing links (url) open under: an agentId, email or landing-page slug from List agents. Whoever signs up from such a link becomes that agent's lead. Without it, links credit your brokerage's default agent (where unassigned leads go). meta.agent names the agent credited |
Response
data.property identifies the listing: propertyId, mlsRecordId, mlsName, address (one line), url (the listing's page on your Ruuster site, under the page of the agent in meta.agent, for example https://saguaro.ruuster.com/agent/jane-doe/listings/5b7e2d94-…; see the property object), and ownedByYou, for your own and other brokerages' listings alike. Use it as the link in a seller report or a CRM task; Get a listing has the full details and photos. meta.scope echoes the scope used.
data.viewers has one row per lead:
| Field | Description |
|---|---|
lead |
The short lead form: leadId, firstName, lastName, email and phone when lead contact details are on, crmExternalId, crmStatus, crmTags, agentId, createdAt, lastLoginAt |
views |
Times the lead opened the listing on your sites in the range. Reloads count |
favorited |
Whether the lead saved the listing in the range |
tourRequested |
Whether the lead requested a tour of the listing in the range |
firstViewedAt, lastViewedAt |
First and last view in the range. null for a lead who saved or requested a tour without a recorded view |
With scope=brokerage a listing that isn't attributed to your brokerage returns 404 not_found; with scope=any only an unknown propertyId does. Rows count against your daily lead-row quota. meta.coverage says which days are available; it's the same coverage as the listing's engagement series.