How to Filter Listings by MLS® Number

The mlsNumber parameter allows you to filter a specific listing by its exact MLS® number. This is useful when you need to fetch data for one or more listings you already know the MLS® number for.

Basic Usage

To filter listings by MLS® number, add the mlsNumber parameter to your API request:

https://api.repliers.io/listings?mlsNumber=12345

Important: The MLS® number must be an exact match. Partial matches or similar numbers will not return results.

Multiple MLS® Numbers

You can also filter for multiple MLS® numbers at once by providing an array of values:

https://api.repliers.io/listings?mlsNumber=12345&mlsNumber=67890&mlsNumber=11111

This will return all listings that match any of the specified MLS® numbers.

Understanding Default Status Behavior

When using the mlsNumber parameter, there's an important default behavior to be aware of:

• Default status is "A" (Active) - If you don't specify a status parameter, the API automatically filters for active listings only
• Your request https://api.repliers.io/listings?mlsNumber=12345 is actually interpreted as https://api.repliers.io/listings?mlsNumber=12345&status=A

Including All Listing Statuses

To filter for a listing regardless of its status (both Active and Unavailable), you must explicitly specify both status values:

https://api.repliers.io/listings?mlsNumber=12345&status=U&status=A

This ensures you'll find the listing whether it's:

• A (Active)
• U (Unavailable)

Common Issue: Disappearing Results

You might encounter a situation where:

1. You search for an MLS® number and get a result
2. Later, the same search returns no results

This typically happens because the listing status changed from Active (A) to Unavailable (U), and you're only filtering active listings by default. To avoid this issue, always include both status parameters when filtering by MLS® number.

Alternative: Keyword Search

If you need more flexible searching capabilities (such as partial matches or searching across multiple fields), consider using our keyword search functionality instead.

For more information, see: How to Search Listings Using Keywords

Best Practices

1. Always specify status parameters when using mlsNumber to avoid missing results due to status changes
2. Use exact MLS® numbers - partial or approximate numbers won't work
3. Consider keyword search for more flexible searching needs

Example Requests

Filter for a single MLS® number (active listings only - default behavior):

https://api.repliers.io/listings?mlsNumber=12345

Filter for a single MLS® number regardless of status (recommended):

https://api.repliers.io/listings?mlsNumber=12345&status=U&status=A

Filter for multiple MLS® numbers:

https://api.repliers.io/listings?mlsNumber=12345&mlsNumber=67890&mlsNumber=11111

Filter for multiple MLS® numbers regardless of status:

https://api.repliers.io/listings?mlsNumber=12345&mlsNumber=67890&mlsNumber=11111&status=U&status=A

Updated on: 05/08/2025