Find prospects for a listing
https://api.ruuster.com/v1/properties/{propertyId}/prospectsReverse 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.
- Authentication:
x-api-keyandx-emailheaders of an owner or admin - Rate limit: lookup call, 20 per minute per key, within the 120 per minute
- Rows count against the daily lead-row quota (50,000 by default)
Answers "who should hear about this home?" from what your leads told Ruuster they want. A lead is a prospect when one of their saved searches covers the listing's area and its price:
- Area: the search names the listing's zip code, or its city, or a county, school zone, neighborhood or drawn area whose boundary contains the listing.
- Price: the search's price range overlaps the listing price widened by
priceTolerancepercent each way. A search with no maximum is open-ended; one with no minimum starts at 0. Withbounded=1, only searches with a maximum price count (a budget rather than "any price").
Brokerage-wide default searches (the fallback search every contact gets) are skipped: they say nothing about what a person wants. Rental searches are skipped too. Other criteria on the search (property types, beds, square feet, year built…) are returned in criteria but not applied, so you can judge fit, for example leaving out a condo-only search for a house.
Any listing works by propertyId, yours or not; your own listings also by mls:<number>. The leads are always your brokerage's. To see which of your leads have already looked at the listing, use List a listing's viewers with scope=any. This is a lookup call: it searches saved searches live, except that a search a lead saved in the last 15 minutes may not be included yet.
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 |
|---|---|---|---|
priceTolerance |
integer | 5 |
Percent the listing price is widened each way before comparing with a search's range, 0 to 25 |
bounded |
0 | 1 |
0 |
1 counts only searches with a maximum price |
limit |
integer | 100 |
Prospects returned, 1 to 200, best matches first |
countOnly |
0 | 1 |
0 |
1 returns { "total": n, "priceBounded": 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, city, state, postalCode, price, status, url (on your Ruuster site) and ownedByYou. data.total is the number of prospects found; meta.truncated is true when it is more than limit.
data.prospects has one row per lead, leads whose fitting search has a maximum price first, then the tightest price range:
| 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 |
priceBounded |
Whether at least one fitting search has a maximum price |
searches |
The lead's fitting saved searches: searchId, name, matchedOn (zip, city, or area:<kind> such as area:county or area:school), priceMin, priceMax (null when not set), criteria (the search's other filters as saved) and updatedAt |
meta.priceRange is the price window used (null when the listing has no price, in which case price isn't checked), meta.priceTolerance and meta.bounded echo the parameters, and meta.searchesConsidered counts your leads' searches whose area covers the listing before the price check. meta.areaShapes says whether searches drawn as shapes (county, school district, neighborhood or a drawn area) were checked: checked, no_location (the listing has no map point, so only zip and city areas apply), or timed_out (the shape check ran out of time; the prospects shown are the zip and city matches, so try again for the full list). An unknown propertyId returns 404 not_found. Rows count against your daily lead-row quota.