Understanding Listing Permissions in the API

Overview

Each listing in our API includes a permissions object that helps you understand how and where the listing can be displayed. These permissions are set by the MLS and ensure compliance with MLS rules and regulations. Your application must respect these permissions to maintain compliance.

Permissions Object Structure

The permissions object contains three key fields, each with a simple Y/N value:

"permissions": {
  "displayAddressOnInternet": "Y",
  "displayPublic": "Y", 
  "displayInternetEntireListing": "Y"
}

Values:

• Y = Yes (permission granted)
• N = No (permission denied)

Permission Fields Explained

displayAddressOnInternet

Purpose: Controls whether the listing's full address can be shown on internet portals.

When value is "Y":

• The complete address can be displayed publicly on websites and portals
• No address redaction is required

When value is "N":

• The listing information can still be displayed
• The address must be redacted or hidden from public view
• Common redaction formats include showing only city/state or using partial addresses

displayPublic

Purpose: Determines whether the listing requires user authentication to view.

When value is "Y":

• The listing can be viewed by anonymous users
• No sign-in is required to access listing details

When value is "N":

• Users must be signed in to view the listing
• Authentication is required before displaying any listing information
• This typically applies to all unavailable listings, plus some active listings depending on MLS rules

displayInternetEntireListing

Purpose: Controls whether the listing can be displayed on customer-facing applications at all.

When value is "Y":

• The listing can be shown on public websites and consumer applications
• Standard display rules apply based on other permission settings

When value is "N":

• The listing cannot be displayed on any customer-facing applications
• This restriction applies regardless of user authentication status
• Back-office applications used exclusively by agents are not affected by this setting

Implementation Guidelines

For Customer-Facing Applications

1. Always check displayInternetEntireListing first

• If "N", do not display the listing at all
• If "Y", proceed to check other permissions

2. Apply authentication requirements

• Check displayPublic to determine if sign-in is required
• Enforce authentication before showing listing details when set to "N"

3. Handle address display

• Respect displayAddressOnInternet setting
• Implement appropriate address redaction when set to "N"

For Back-Office Applications

• Agent-only applications can ignore displayInternetEntireListing
• Still respect displayAddressOnInternet for address display rules
• Authentication requirements may still apply based on displayPublic

Common Scenarios

Scenario 1: Fully Public Listing

{
  "displayAddressOnInternet": "Y",
  "displayPublic": "Y",
  "displayInternetEntireListing": "Y"
}

Result: Full listing with address can be displayed to anonymous users.

Scenario 2: Sign-In Required

{
  "displayAddressOnInternet": "Y",
  "displayPublic": "N",
  "displayInternetEntireListing": "Y"
}

Result: Full listing with address available only to authenticated users.

Scenario 3: Address Redaction Required

{
  "displayAddressOnInternet": "N",
  "displayPublic": "Y",
  "displayInternetEntireListing": "Y"
}

Result: Listing visible to all users, but address must be redacted.

Scenario 4: No Public Display

{
  "displayAddressOnInternet": "N",
  "displayPublic": "N",
  "displayInternetEntireListing": "N"
}

Result: Listing cannot be displayed on customer-facing applications.

Compliance Requirements

• These permission values are determined by the MLS and cannot be modified
• Your application must respect these permissions to maintain compliance
• Failure to comply with permission restrictions may result in API access being revoked
• Always validate all three permission fields before displaying any listing

Best Practices

• Always validate all three permission fields before displaying any listing
• Implement proper error handling for restricted listings
• Consider caching permission checks for performance optimization
• Regularly review and update permission handling logic to ensure compliance
• Document your implementation approach for future reference
• Remember that these permissions are read-only and set by the MLS

Support

If you encounter issues with permission handling or need clarification on specific scenarios, please contact our technical support team with the mlsNumber and specific permission values in question.

Updated on: 08/07/2025