Listings

Multiple RESO Dictionary Support
This service supports multiple RESO Data Dictionary versions.

Listing Display Rules

Each MLS defines rules each application must abide by when displaying listing reports or brief summary data (such as listing search results). Review the Compliance page for details.

The Listings API is used to retrieve listing information, enter new listings and updating existing listing data, and run searches on listings.

Supported Roles
Available Services
Response Description
Expansions

Supported Roles

Role	Reads	Writes	Notes
IDX	Yes	No
Public	Yes	No
VOW	Yes	No
Portal	Yes	No
Private	Yes	Yes	Privileged roles only for writes, typically for internal use only. Very limited support; contact support at api-support@fbsdata.com to discuss on case-by-case basis.

More information about roles may be found here.

Available Services

Listings

`/<API Version>/listings`
`/<API Version>/contacts/<Contact.Id>/listings`

HTTP Method	Description	Conditional	Notes
GET	Retrieves listing data	No
POST	Creates a new listing record.	No	Only `StandardFields` and `CustomFields` can be set using this service. The listing rules data will inform the application which fields are writable and required. The `Errors` response attribute will be present on failures, as most listing rule violations are considered fatal for this service.
PUT	Returns HTTP 405 (Method Not Allowed)	No	Not implemented
DELETE	Returns HTTP 405 (Method Not Allowed)	No	Not implemented

GET Request

Parameters:

Parameter	Required	Notes
Standard search and paging syntax	No
Standard selection parameters	No
Standard expansion parameters	No
Sub-resource search parameters	No
_location	No

GET Response

{
    "D": {
        "Success": true,
        "Results": [
            {
                "ResourceUri": "/vX/listings/20060412165917817933000000",
                "Id": "20060412165917817933000000",
                "StandardFields": {
                    "ListingKey": "20060412165917817933000000",
                    "ListingId": "10-1796",
                    "PropertyType": "A",
                    "PropertySubType": "SF",
                    "ListPrice": 1079900,
                    "StreetNumber": "611",
                    "StreetDirPrefix": null,
                    "StreetName": "8th",
                    "StreetSuffix": "St",
                    "StreetDirSuffix": "S",
                    "StreetAdditionalInfo": null,
                    "City": "Fargo",
                    "StateOrProvince": "ND",
                    "PostalCode": "58103",
                    "YearBuilt": 1884,
                    "BuildingAreaTotal": 7275,
                    "BathsThreeQuarter": 1,
                    "BathsTotal": 8,
                    "BathsFull": 5,
                    "BedsTotal": 8,
                    "BathsHalf": 2,
                    "Longitude": -96.792246,
                    "Latitude": 46.868464,
                    "SubdivisionName": "Westgate",
                    "MLSAreaMinor": "West",
                    "CountyOrParish": null,
                    "PublicRemarks": "Great foyer. Cool kitchen. 6 fireplaces. The list goes on.",
                    "PrivateRemarks": "********",
                    "PrivateOfficeRemarks": "********",
                    "PendingDate": "********",
                    "CloseDate": "********",
                    "CancelDate": "********",
                    "WithdrawDate": "********",
                    "ListAgentFirstName": "Joe",
                    "ListAgentMiddleName": "",
                    "ListAgentLastName": "Agent",
                    "ListAgentPreferredPhone": "123-456-7890",
                    "ListAgentPreferredPhoneExt": "3",
                    "ListAgentOfficePhone": "123-456-7890",
                    "ListAgentOfficePhoneExt": "123-456-7890",
                    "ListAgentCellPhone": "123-456-7890",
                    "ListAgentDirectPhone": "123-456-7890",
                    "ListAgentTollFreePhone": "123-456-7890",
                    "ListAgentFax": "123-456-7890",
                    "ListAgentPager": "123-456-7890",
                    "ListAgentVoiceMail": "123-456-7890",
                    "ListAgentVoiceMailExt": "123-456-7890",
                    "ListAgentEmail": "joe@joeagent.com",
                    "ListAgentURL": "http://joeagent.com/",
                    "ListAgentStateLicense": "12345",
                    "ListAgentDesignation": "CRS, GRI",
                    "ListOfficeName": "BigBrokerCo",
                    "ListOfficePhone": "987-654-3210",
                    "ListOfficePhoneExt": "33",
                    "ListOfficeFax": "987-654-3210",
                    "ListOfficeEmail": "big@brokerco.com",
                    "ListOfficeURL": "http://bigbrokerco.com",
                    "CoListAgentFirstName": "Jimmy",
                    "CoListAgentMiddleName": "",
                    "CoListAgentLastName": "Agent",
                    "CoListAgentPreferredPhone": "323-456-7890",
                    "CoListAgentPreferredPhoneExt": "3",
                    "CoListAgentOfficePhone": "123-456-7890",
                    "CoListAgentOfficePhoneExt": "123-456-7890",
                    "CoListAgentCellPhone": "123-456-7890",
                    "CoListAgentDirectPhone": "123-456-7890",
                    "CoListAgentTollFreePhone": "123-456-7890",
                    "CoListAgentFax": "123-456-7890",
                    "CoListAgentPager": "123-456-7890",
                    "CoListAgentVoiceMail": "123-456-7890",
                    "CoListAgentVoiceMailExt": "123-456-7890",
                    "CoListAgentEmail": "jimmy@jimmyagent.com",
                    "CoListAgentURL": "http://jimmyagent.com/",
                    "CoListAgentStateLicense": "22345",
                    "CoListAgentDesignation": "CRS, GRI",
                    "CoListOfficeName": "BigBrokerCo",
                    "CoListOfficePhone": "987-654-3210",
                    "CoListOfficePhoneExt": "33",
                    "CoListOfficeFax": "987-654-3210",
                    "CoListOfficeEmail": "big@brokerco.com",
                    "CoListOfficeURL": "http://bigbrokerco.com",
                    "ModificationTimestamp": "2010-11-22T20:09:37Z",
                    "VirtualTourURLBranded": "http://somethirdpartyservice.com/234",
                    "VirtualTourURLUnbranded": "http://somethirdpartyservice.com/345",
                    "Supplement": "Text supplement goes here",
                    "Photos": [
                        {
                            "ResourceUri": "/vX/listings/20060412165917817933000000/photos/20080917142739989238000000",
                            "Id": "20080917142739989238000000",
                            "Name": "Listing Photo",
                            "Caption": "",
                            "UriThumb": "http://photos.sparkplatform.com/demomls/20080917142739989238000000-t.jpg",
                            "Uri300": "http://photos.sparkplatform.com/demomls/20080917142739989238000000.jpg",
                            "Uri640": "http://resize.sparkplatform.com/demomls/640x480/true/20080917142739989238000000-o.jpg",
                            "Uri800": "http://resize.sparkplatform.com/demomls/800x600/true/20080917142739989238000000-o.jpg",
                            "Uri1024": "http://resize.sparkplatform.com/demomls/1024x768/true/20080917142739989238000000-o.jpg",
                            "Uri1280": "http://resize.sparkplatform.com/demomls/1280x1024/true/20080917142739989238000000-o.jpg",
                            "Uri1600": "http://resize.sparkplatform.com/demomls/1600x1200/true/20080917142739989238000000-o.jpg",
                            "Uri2048": "http://resize.sparkplatform.com/demomls/2048x1600/true/20080917142739989238000000-o.jpg",
                            "UriLarge": "http://photos.sparkplatform.com/demomls/20080917142739989238000000-o.jpg",
                            "Primary": true
                        }
                    ],
                    "OpenHouses": [
                        {
                            "ResourceUri": "/vX/listings/20060412165917817933000000/openhouses/10000000000000000000000000",
                            "Id": "10000000000000000000000000",
                            "Date": "2007-07-08",
                            "StartTime": "9:00 am",
                            "EndTime": "1:00 pm"
                        }
                    ],
                    "Documents": [
                        {
                            "ResourceUri": "/listings/20100815153524571646000000/documents/20101125153422574618000000",
                            "Id": "20101125153422574618000000",
                            "Name": "Document name",
                            "Uri": "http://documents.sparkplatform.com/abc.pdf"
                        }
                    ],
                    "VirtualTours": [
                        {
                            "ResourceUri": "/listings/20100815153524571646000000/virtualtours/20101213041526458274000000",
                            "Id": "20101213041526458274000000",
                            "Name": "VT name",
                            "Uri": "http://somethirdpartyvtservice.com/123",
                            "Type": "branded"
                        }
                    ],
                    "Videos": [
                        {
                            "ResourceUri": "/listings/20100815153524571646000000/videos/20101213041526458274000000",
                            "Id": "20101213041526458274000000",
                            "Name": "Video name",
                            "Caption": "Caption text",
                            "Type": "branded",
                            "ObjectHtml": "<>"
                        }
                    ],
                    "Rooms": [
                        {
                            "Id": "20110525151622697369000000",
                            "ResourceUri": "/v1/listings/20101014195350951959000000/rooms/20110525151622697369000000",
                            "Fields": [
                                {
                                    "Room Name": "Bedroom"
                                },
                                {
                                    "Room Level": "1"
                                },
                                {
                                    "No. of Rooms": "2"
                                },
                                {
                                    "Area": "40"
                                },
                                {
                                    "Length": null
                                },
                                {
                                    "Width": null
                                },
                                {
                                    "Room Remarks": "Lorem ipsum dolor sit amet"
                                }
                            ]
                        }
                    ]
                },
                "CustomFields": [
                    {
                        "Main": [
                            {
                                "Contract Information": [
                                    {
                                        "Book Section": "Residential w/ Acreage"
                                    },
                                    {
                                        "Area": "North (Bonner & Boundary)"
                                    },
                                    {
                                        "Begin Date": "2006-03-03"
                                    }
                                ]
                            },
                            {
                                "General Property Description": [
                                    {
                                        "Realtor.COM Type": "Residential - Single Family"
                                    },
                                    {
                                        "Style": "Multi Level"
                                    },
                                    {
                                        "Basement": "No"
                                    },
                                    {
                                        "Stories": 2
                                    },
                                    {
                                        "Garage Type": "Att Garage"
                                    },
                                    {
                                        "Garage Stall": "3 or more"
                                    },
                                    {
                                        "SqFt B": 0
                                    },
                                    {
                                        "SqFt 1": 3585
                                    },
                                    {
                                        "SqFt 2": 1500
                                    },
                                    {
                                        "SqFt Source": "Assessor/Tax Roll"
                                    },
                                    {
                                        "New Construction": "No"
                                    },
                                    {
                                        "Lot Acres": 36.9
                                    },
                                    {
                                        "Lot Type 1": "Residential"
                                    },
                                    {
                                        "Lot Type 2": "Lake/River View"
                                    },
                                    {
                                        "Lake/River Name": "Granite Lake"
                                    }
                                ]
                            }
                        ],
                        "Details": [
                            {
                                "View": [
                                    {
                                        "Mountain": true
                                    },
                                    {
                                        "River": true
                                    }
                                ]
                            },
                            {
                                "Lot Features": [
                                    {
                                        "Irregular": true
                                    },
                                    {
                                        "Level": true
                                    }
                                ]
                            }
                        ]
                    }
                ],
                "DisplayCompliance": {
                    "IDXLogoSmall": {
                        "LogoUri": "http://somesite.com/logo/small.jpg",
                        "Type": "Uri"
                    },
                    "View": "Detail",
                    "IDXLogo": {
                        "LogoUri": "Acme Realty",
                        "Type": "Text"
                    }
                }
            }
        ],
        "Pagination": {
            "TotalRows": 78,
            "PageSize": 25,
            "TotalPages": 4,
            "CurrentPage": 1
        }
    }
}

POST Request

Request body:

{
   "D":{
      "PropertyType": "A",
      "PropertySubType": "SF",
      "ListPrice": 1079900,
      "StreetNumber": "611",
      "StreetDirPrefix": null,
      "StreetName": "8th",
      "StreetSuffix": "St",
      "StreetDirSuffix": "S",
      "StreetAdditionalInfo": null,
      "City": "Fargo",
      "StateOrProvince": "ND",
      "PostalCode": "58103",
      "YearBuilt": 1884,
      "BuildingAreaTotal": 7275,
      "BathsThreeQuarter": 1,
      "BathsTotal": 8,
      "BathsFull": 5,
      "BedsTotal": 8,
      "BathsHalf": 2,
      "Longitude": -96.792246,
      "Latitude": 46.868464,
      "SubdivisionName": "Westgate",
      "MLSAreaMinor": "West",
      "CountyOrParish": null,
      "ListAgentId": "20080917142739989238000000",
      "CustomFields": {
        "Contract Information": {
          "Book Section": "Residential w/ Acreage",
          "Area": "North (Bonner & Boundary)"
        }
      }
   }
}

POST Response

The standard success/fail response with additional error information is returned.

Individual Listing

`/<API Version>/listings/<Listing.Id>`
`/<API Version>/contacts/<Contact.Id>/listings/<Listing.Id>`

HTTP Method	Description	Conditional	Notes
GET	Retrieve listing information for a single listing.	No
POST	Returns HTTP 405 (Method Not Allowed)	No	Not implemented
PUT	Updates a listing record.	No	Only `StandardFields` and `CustomFields` can be set using this service. The listing rules data will inform the application which fields are writable and required. The `Errors` response attribute will be present on failures, as most listing rule violations are considered fatal for this service.
DELETE	Returns HTTP 405 (Method Not Allowed)	No	Not implemented

GET Request

Parameters:

Parameter	Required	Notes
Standard expansion parameters	No
Standard selection parameters	No

GET Response

See the GET request section for for the Listings service.

PUT Request

Request body:

{
   "D":{
      "PostalCode": "58103",
      "YearBuilt": 1884
   }
}

PUT Response

The standard success/fail response with additional error information is returned.

My, Office, and Company Listings

`/<API Version>/my/listings`
`/<API Version>/office/listings`
`/<API Version>/company/listings`

HTTP Method	Description	Notes
GET	Retrieves listings listed by the current user, or under the current user's office or company.	See parameters below
POST,PUT,DELETE	Returns HTTP 405 (Method Not Allowed)	Not implemented

GET Request

Parameters:

Parameter	Required	Comments
Standard search and paging syntax	No

GET Response

See the GET response section above for the data format.

Nearby Listings

`/<API Version>/listings/nearby`
`/<API Version>/contacts/<Contact.Id>/listings/nearby`

The Nearby Listings service is unique in that it automatically sorts the listing results by proximity to the provided _lat and _lot values, nearest first.

HTTP Method	Description	Notes
GET	Retrieves listing data nearby a given coordinate
POST,PUT,DELETE	Returns HTTP 405 (Method Not Allowed)	Not implemented

GET Request

Parameters:

Parameter	Required
Standard proximity parameters	Yes
Standard search and paging syntax	Yes
Sub-resource search parameters	No
Standard selection parameters	No

GET Response

See the GET response section below for the data format.

Listings Description

Editability, visibility, searchability and list item labels for standard fields will vary among users. Because of this, the settings for standard listing fields are discoverable using the Standard Fields service. Detailed below are attributes and expansions that are not documented in other services.

Restricted Fields

Fields that are not MlsVisible for a given listing's PropertyType will be masked (i.e. have a value of "********"). See the the Standard Fields service for more details.

Attribute	Data Type	Description
`Permissions`	Expansion	The Permissions expansion details if and how the current user can modify the listing. See the Permissions expansion for more details. `"Permissions": { "Editable": true, "EditableSettings": { "Photos": true, "Documents": true, "Videos": true, "VirtualTours": true, "PriceChange": true, "StatusChange": true, "BrokerTours": true, "OpenHouses": true, "TourOfHomes": true, "AddListing": true, "ChangeListing": true }, "AvailableStandardStatusChanges": [ "Active", "Pending", "Closed" ] }`
`Editable`	Boolean	If `true`, the current user can modify at least some aspects of the listing data. Consult `EditableSettings` for more details on what can be changed.
`Permissions.EditableSettings`	JSON Object	Details which aspects of the listing data the current user can modify.
`AddListing`	Boolean	If `true`, the current user can add the listing
`BrokerTours`	Boolean	If `true`, the current user can add the listing to a broker tour.
`Documents`	Boolean	If `true`, the current user can add and manage documents for the listing.
`ChangeListing`	Boolean	If `true`, the current user can modify at least some aspects of the listing data. This is the same as `Editable.`
`OpenHouses`	Boolean	If `true`, the current user can modify the listing's open houses.
`Photos`	Boolean	If `true`, the current user can add and manage photos for the listing.
`PriceChange`	Boolean	If `true`, the current user can change the `ListPrice` for the listing.
`StatusChange`	Boolean	If `true`, the current user can modify the listing's `MlsStatus`.
`TourOfHomes`	Boolean	If `true`, the current user can modify the listing's tour of homes.
`Videos`	Boolean	If `true`, the current user can add and manage videos for the listing.
`VirtualTours`	Boolean	If `true`, the current user can add and manage virtual tours for the listing.
`UserInterfaceDisplay`	JSON Object	Additional fields for listing presentation.
`ContingencyFlag`	Character	Useful for UIs that show the contingent code for the listing.

Not all listing data is suitable for display.
When using the Listings Service, you must consult the corresponding meta data services (e.g. Property Types and Standard Fields) for the PropertyType standard field and any other field where the HasList is true in the meta data.

See an example here.

Expansions

Expansion	Roles	Single Record Only?	Selection Support?	Description
`BrokerDistributionExclusions`	Private	Yes	No	The distributions which this listing should be excluded from. Use this expansion in conjunction with the broker distribution meta data.
`BuyerAgentPhoto`	All	Yes	No	The buying agent's photo if the buying agent information is available.
`BuyerOfficePhoto`	All	Yes	No	The buying office's photo if the buying office information is available.
`CoBuyerAgentPhoto`	All	Yes	No	The co-buying agent's photo if the co-buying agent information is available.
`CoBuyerOfficePhoto`	All	Yes	No	The co-buying office's photo if the co-buying office information is available.
`CoListAgentPhoto`	All	Yes	No	The co-listing agent's photo if the co-listing agent information is available.
`CoListOfficePhoto`	All	Yes	No	The co-listing office's photo if the co-listing office information is available.
`ContactActivity`	Private	No	No	A summary of total actions performed on the listing by the current contact. Attributes are `Viewed` and `Shared`.
`Creator`	All	Yes	No	The account record for the user that created the listing.
`CumulativeDaysOnMarket`	All	No	No	The cumulative number of days the listing has on been on market. Technically a Standard Fields, and is potentially searchable or disabled.
`CustomFields`	All	No	No	Custom fields are unstandardized listing data. As such, they will not be consistent among different MLSs. They are also not guaranteed to be static, so avoid writing software whose functionality depends on a particular custom field. Cannot be used in conjunction with any other custom fields expansion. This expansions applies the MLS-defined human-readable labels to all custom fields and values, and thus cannot be used with the custom fields meta data.
`CustomFieldsRaw`	All	No	No	Nearly identical to the `CustomFields` expansions, with the exception that human-friendly labels are not applied to fields and values. Use this expansion in conjunction with the custom fields meta data.
`CustomFieldsExpanded`	All	No	No	All custom field data for the listing including data which is also displayed in StandardFields. Cannot be used in conjunction with any other custom fields expansion. This expansions applies the MLS-defined human-readable labels to all custom fields and values, and thus cannot be used with the custom fields meta data.
`CustomFieldsExpandedRaw`	All	No	No	Nearly identical to the `CustomFieldsExpanded` expansions, with the exception that human-friendly labels are not applied to fields and values. Use this expansion in conjunction with the custom fields meta data.
`DaysOffMarket`	Private	Yes	No	The total number of days the listing has spent off market. Available for select MLSs, and requires special privilege to access.
`DaysOnMarket`	All	No	No	The number of days since the listing has been or was on market. Technically a Standard Fields, and is potentially searchable or disabled.
`Documents`	All	No	Yes	The list of documents attached to the listing.
`ExpirationDate`	Private	Yes	No	The date when the listing expires, which is a date value.
`FloorPlans`	All	No	No	The Floor Plans attached to the listing.
`FloPlans`	All	Yes	No	The FloPlans attached to the listing.
`ListAgentPhoto`	All	No	No	The listing agent's photo if the listing agent information is available.
`ListOfficePhoto`	All	No	No	The listing office's photo if the listing office information is available.
`NotesCount`	All	No	No	The number of notes for the listing.
`OpenHouses`	All	No	Yes	Upcoming open houses for the listing.
`Permissions`	Private	Yes	No	Details if the current user can edit the listing as well as what actions can be performed on the current listing. See more info in the Response Description.
`PortalCarts`	Portal, VOW	No	No	A list portal carts the listing is in.
`Photos`	All	No	Yes	All photos for a listing. Cannot be used in conjunction with `PrimaryPhoto`
`PrimaryPhoto`	All	No	No	Returns only the primary photo for the listing. Cannot be used in conjunction with `Photos`
`PrivateOfficeRemarks`	Private	Yes	No	The private office remarks for the listing, which is a text value.
`RentalCalendar`	All	No	No	Upcoming dates through the next three months when the property will be unavailable for rental. Consult the Property Types service to see which property types support this expansion.
`RentalCalendarExpanded`	All	Yes	No	Includes more detailed information about the listing's `RentalCalendar`. `"RentalCalendarExpanded": { "Enabled" => true, "StartDate": "2018-01-01", "EndDate": "2019-01-01", "RentalCalendar" => [ { "Id": "20110003930012897000000000", "Type": "Rented", "StartDate": "2018-03-14", "EndDate": "2018-03-15" } ] }` `Enabled`: If `false`, this listing has no `RentalCalendar` support. `StartDate`: Before this date, no rental calendar events can be created. `EndDate`: After this date, no rental calendar events can be created. `RentalCalendar`: Identical to the results of the `RentalCalendar` expansion, although this attribute includes all upcoming dates.
`Rooms`	All	No	Yes	Room data for the listing.
`RoomsRaw`	All	No	Yes	Nearly identical to the `Rooms` expansions, with the exception that human-friendly labels are not applied to fields and values. Use this expansion in conjunction with the rooms meta data.
`StarRating`	All	No	No	Orders listings in a `Favorites` cart by their rating by the user.
`Supplement`	All	No	No	Supplement data about the listing, which is a text value.
`TourOfHomes`	Private	No	Yes	Upcoming tour of home events for the listing.
`Units`	All	No	Yes	A list of units associated with the listing.
`UnitsRaw`	All	No	Yes	Nearly identical to the `Units` expansions, with the exception that human-friendly labels are not applied to fields and values. Use this expansion in conjunction with the units meta data.
`UserInterfaceDisplay`	All	No	Yes	Additional fields for listing presentation.
`Videos`	All	No	Yes	Videos for the listing.
`VirtualTours`	All	No	Yes	Virtual tours for the listing.

Listings

Listing Display Rules

Supported Roles

Available Services

Listings

/<API Version>/listings /<API Version>/contacts/<Contact.Id>/listings

GET Request

GET Response

POST Request

POST Response

Individual Listing

/<API Version>/listings/<Listing.Id> /<API Version>/contacts/<Contact.Id>/listings/<Listing.Id>

GET Request

GET Response

PUT Request

PUT Response

My, Office, and Company Listings

/<API Version>/my/listings /<API Version>/office/listings /<API Version>/company/listings

GET Request

GET Response

Nearby Listings

/<API Version>/listings/nearby /<API Version>/contacts/<Contact.Id>/listings/nearby

GET Request

GET Response

Listings Description

Restricted Fields

Expansions

`/<API Version>/listings`
`/<API Version>/contacts/<Contact.Id>/listings`

`/<API Version>/listings/<Listing.Id>`
`/<API Version>/contacts/<Contact.Id>/listings/<Listing.Id>`

`/<API Version>/my/listings`
`/<API Version>/office/listings`
`/<API Version>/company/listings`

`/<API Version>/listings/nearby`
`/<API Version>/contacts/<Contact.Id>/listings/nearby`