# MLS numbers

Source: https://help.ruuster.com/api/mls-numbers

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

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](https://help.ruuster.com/api/properties-lookup)
(`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`.