RuusterAPI Reference
Menu · Getting started
Getting started

MLS numbers

How MLS numbers are matched, with or without their leading letters, and what happens when more than one listing matches.

View as Markdown

You can send an MLS number with or without its leading letters. ?mlsRecordId= on /properties and mls:<number> search the listings attributed to your brokerage; /properties/lookup searches every listing in your brokerage's MLSs, one number per call.

MLSs format numbers differently. Some include letters as part of the number (PAPH2000001, PW26000002, A12000003), some use a prefix that's often left off (MRD12000004 is also known as 12000004), and some use digits only (22600005).

How a number is matched

  1. Spaces, #, -, _ and . are ignored, and letters aren't case sensitive. pa 1000006, PA-1000006 and PA1000006 are the same.
  2. An exact match on the full number wins.
  3. If there's no exact match, or you sent digits only, the number is compared with the letters removed: 2000001 finds PAPH2000001.
  4. Every match comes back with matchedOn (exact or digits), the full number, and the MLS name.

More than one match. Some MLSs reuse the same digits behind different letters for different homes, for example P4900006 and V4900006. Digits only can then match more than one listing. The response sets "ambiguous": true and lists them all. Send the full number, or add &mlsId=, to pick one. Ruuster doesn't pick one for you.

No match. /properties?mlsRecordId= searches your own listings, so a listing that belongs to another brokerage is never returned there. If one of your listings isn't found, the most common causes are the listing agent's MLS id missing from their Ruuster profile, or a listing from an office Ruuster hasn't confirmed as yours. Listings that left the market more than about 18 months ago aren't included.

Listings that aren't yours. Look up any listing by MLS number (GET /properties/lookup?mlsRecordId=) finds a listing in any of your MLSs whoever holds it, with ownedByYou on each match. It's a lookup call (20 per minute) and matches the number as the MLS publishes it or in its digits-only form; it doesn't try prefixes for you. Unlike your own listings, it also finds older sales, however long ago they closed.

mlsId must be one of your brokerage's MLSs (see /me › mlsIds), otherwise 400 mls_not_in_scope. A number in a format Ruuster can't read returns 400 invalid_mls_number.