Why this matters
/v3/MLSDetail returns one complete listing record: the listing itself, agent and office contacts, photos, schools, open houses, and the full price and status history. Plus the property's other listings, past and present.
It's the right call any time you already know which property you want. A common mistake is using MLS Search with an address filter to "look up" a property. Search is built for finding sets of listings, so an address search can return near-matches. MLS Detail resolves the exact record.
Common use cases
- Listing or property page. One call fills the whole page: details, photos, agent card, history.
- Address lookup from a CRM or lead form. Turn a typed address into the current MLS listing for that property.
- Agent hands you a listing's MLS number. Look it up with the board code, since MLS numbers repeat across boards.
- Price and status history panel. Show every price cut and status change without running daily jobs to diff prices yourself.
- Dual-listing and relist checks. See whether the property is listed on more than one board, or was listed before.
- Listing plus public record in one call. Merge in owner, tax and deed data when your plan includes public records.
Ways to look a listing up
| Lookup | Example | Notes |
|---|---|---|
listing_id | { "listing_id": 10678958569 } | From MLS Search, Pins or AutoComplete |
mls_number + mls_board_code | { "mls_number": "50480527", "mls_board_code": "mamlspin" } | Both are required |
public_id | { "public_id": 325961565 } | RealEstateAPI property ID, e.g. from Property Search |
apn | { "apn": "..." } | Assessor parcel number |
address | { "address": "123 Main St, Austin, TX 78704" } | Full address with city, state and ZIP |
If you send more than one, the API uses the first in this order: mls_number, listing_id, public_id, apn, address.
Example: property page with only what you render
Use field_sections to return just the sections your page shows. Smaller responses are faster to send and parse.
{
"listing_id": 10678958569,
"field_sections": ["ROOT", "address", "listingDetails", "media", "listingAgent", "listingOffice"]
}ROOT returns the top-level fields (status, price, dates, IDs). See No More Bloated Responses for every section name and for picking individual fields with fields.
Example: history panel
{
"listing_id": 10678958569,
"field_sections": ["ROOT", "priceChangeHistory", "statusChangeHistory", "pastListings"]
}priceChangeHistory: every price change on this listing. See Tracking Price Changes on a Listing.statusChangeHistory: every status change, including relists and deals that fell through. See Listing Journeys Aren't Always Linear.pastListings: earlier listings of the same property, useful for sale history and pricing anchors.
Example: dual-listed properties
The same home can be listed on two neighboring boards, or listed for sale and for rent at once. linkedListings shows those other active listings, so you can dedupe them or show every board it appears on:
{ "listing_id": 10678958569, "field_sections": ["ROOT", "linkedListings"] }See Linked Listings vs. Past Listings.
Example: agent contact card
{ "listing_id": 10678958569, "field_sections": ["listingAgent", "listingOffice"] }Add colistingAgent, sellingAgent or sellingOffice for the other sides of the deal.
Example: listing plus public record
If your plan includes public-record data, add public: true to merge the property's public record into the same response:
{ "listing_id": 10678958569, "public": true, "fields": ["listingPrice", "listingDetails", "public"] }Without a public-record plan, the public block is left out and the response includes a warning explaining why.
When there's no MLS listing
If the property has no MLS record, you get a 404 with errorCode: "MLS_NOT_FOUND". For accounts with both an MLS plan and public-record access, MLS Detail falls back to the public record instead (billed as a public-record call). Send public_record_fallback: false if you'd rather get the 404.
Tips
| Tip | Why |
|---|---|
| Use MLS Detail, not MLS Search, for single-address lookups | Detail resolves the exact record instead of returning near-matches |
Always send mls_board_code with mls_number | MLS numbers aren't unique across boards |
| Send full addresses | address needs street, city, state and ZIP |
| Fetching more than a few listings? Use MLS Detail Bulk | Up to 1,000 listings per call, same record shape |