Listings

The Listings API is used to retrieve listing information and run searches on listings. Requests must be authenticated according to these instructions or HTTP 401 (Unauthorized) will be returned.

  1. Applicable API Key Roles
  2. Available Services
    1. Retrieving full listing information
    2. Search for listings: /listings/
    3. Get an individual listing: /listings/XX/
    4. Get my listings: /my/listings/
    5. Get office listings: /office/listings/
    6. Get company listings: /company/listings/
  3. Response Format
  4. Determine if a listing is editable
  5. Make a price change

Applicable API Key Roles

This service is available to API keys with private or IDX roles. Within the IDX role, both IDX and Portal permissions may access this service. Listing data is restricted based on the API key and user’s current permission level. For example, IDX API keys will only have access to IDX listings.  More information about roles may be found here.

Available Services

Retrieving full listing information

Listing services below generally are broken into two types: 1) searches run with specified criteria where zero or more listings are returned; and 2) a lookup on a specific listing ID that retrieves just that one listing, or no listing if the ID doesn’t match. The first type of service returns a set of listings. If a _limit parameter is supplied and it is set to a number greater than 1, then there are limits as to what fields are returned. For example, no custom fields are returned in this case. If the _limit parameter is set to 1 or if the second type of service is used, the developer may request that other fields excluded in the multi-result response be included via _expand, up to all available fields.  This is useful for retrieving full listing information by list number, without first having to run a search followed by a request to an individual listing’s URI.

Search for Listings

URI: /<API Version>/listings/

HTTP Method Description Notes
GET Search for listings based on criteria and retrieve listing information for those listings. Listings and data will be filtered based on the API key’s permission level. See parameters below
POST,PUT,DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

Parameters:

Parameter Required Comments
Standard search parameters No If not specified, defaults to all listings that are visible with the current user’s permission.
Standard search and paging syntax No If not specified, defaults to the first page of listings and the default set of fields.
Hot sheet search parameters No The maximum date range that the /listings/ service supports is a 31 day span. If not specified, defaults to the last 24 hours.
Sub-resource search parameters No Example sub-resources include photos, open houses, etc.
Listing Response Field Selection No Any of the StandardFields attributes, such as PostalCode, BedsTotal, etc. may be specified in a comma-separated list.

GET Response

This service returns data in the Listing Response Format.

Get an Individual Listing

URI: /<API Version>/listings/XX/

XX represents the listing ID as returned by any service that returns listing IDs (/listings/, for example).

HTTP Method Description Notes
GET Retrieve listing information for a single listing. The listing and its data will be filtered based on the current permission level. See parameters below
POST,PUT,DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

Parameters:

GET Response

This service returns data in the Listing Response Format.

Get My Listings

URI: /<API Version>/my/listings/

HTTP Method Description Notes
GET Retrieves listings listed by the current user. Using this service as a member will return just the member’s listings. Using this service as an office will return just the office’s listings. Likewise, for companies and the MLS. See parameters below
POST,PUT,DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

Parameters:

GET Response

This service returns data in the Listing Response Format.

Get Office Listings

URI: /<API Version>/office/listings/

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

GET Request

Parameters:

  • None.

GET Response

This service returns data in the Listing Response Format.

Get Company Listings

URI: /<API Version>/company/listings/

HTTP Method Description Notes
GET Retrieves listings listed by the current user’s company (a company is a collection of offices under the same ownership). If the user does not belong to a company, this service retrieves listings from the current user’s office. See parameters below
POST,PUT,DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

Parameters:

  • None.

GET Response

This service returns data in the Listing Response Format.

Listing Response Format

The response currently only delivers standard fields. Over time, more fields will become available in the standard fields section, and the non-searchable custom (non-standard) field section encapsulates the fields that aren’t available in standard format. Note that the fields in the custom fields section vary dramatically from MLS to MLS, so code accordingly.

Below is a sample response. Note that CustomFields may only be requested to be returned when an individual listing is queried by ID. Fields that have information that is not accessible at the current permission level will be returned with a series of asterisks instead of the actual data. For example, the PrivateRemarks field will typically be returned with a series of asterisks when accessing listing data using an IDX API key.

{
    "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": "********",
                    "ExpirationDate": "********",
                    "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.flexmls.com/demomls/20080917142739989238000000-t.jpg",
                            "Uri300": "http://photos.com/demomls/20080917142739989238000000.jpg",
                            "Uri640": "http://resize.flexmls.com/demomls/640x480/true/20080917142739989238000000-o.jpg",
                            "Uri800": "http://resize.flexmls.com/demomls/800x600/true/20080917142739989238000000-o.jpg",
                            "Uri1024": "http://resize.flexmls.com/demomls/1024x768/true/20080917142739989238000000-o.jpg",
                            "Uri1280": "http://resize.flexmls.com/demomls/1280x1024/true/20080917142739989238000000-o.jpg",
                            "UriLarge": "http://photos.flexmls.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.flexmls.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": "<>"
                        }
                    ],
                    "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
                                        }
                                    ]
                                }
                            ],
                            "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"
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                }
            }
        ],
        // Note that Pagination is returned only if the request includes _pagination=1
       "Pagination": {
            "TotalRows": 78,
            "PageSize": 25,
            "TotalPages": 4,
            "CurrentPage": 1
        }
    }
}

Determine if a listing is editable

For private API key roles only, to determine if a listing is editable, add _expand=Permissions to a request for an individual listing (either /vX/listings/XX or /vX/listings with _limit=1). The following attribute will be added to the response at the same level as ResourceUri and Id, with sub-attributes indicating whether the user may perform status changes (and which statuses), price changes, and/or edit photos:

    "Permissions": {
        "Editable": true,
        "EditableSettings": {
            "StatusChange": true,
            "PriceChange": true,
            "Photos": true,
            "AvailableStatusChanges": [
                "A","P","C"
            ]
        }
    }

Make a price change

This is for private API key roles only.

To change the price on a listing, issue a PUT to /vX/listings/XX with the following request body, changing the value of the price appropriately:

{
    "D": {
        "ListPrice": 100000
    }
}

Only users who can edit the listing and perform price changes will be able to perform this action. See the how to determine if a listing is editable section above for more details.

The standard success/fail response format without resource creation is returned as a response.

Comments on this entry are closed.