> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.repliers.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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](https://help.repliers.com/en/article/how-to-search-listings-using-keywords-1osixqn/)

## 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
```

# What questions does this article answer?

- How do I retrieve a specific listing (or listings) when I already know the MLS® number(s)?  
- How do I use the `mlsNumber` parameter for exact-match lookups?  
- Can I filter by multiple MLS® numbers, and how do I pass them?  
- Why won’t partial MLS® numbers or similar numbers return matches?