Developer Documentation
Platform Overview
Authentication
API Services
Overview Accounts Accounts: Associations Accounts: Metadata Accounts: Profile Appstore: Users Broker Distributions Broker Tours Consumers Consumers: Linked Agents Contacts Contacts: Activity Contacts: Export Contacts: Tags Contacts: Portal Accounts Developers: Identities Developers: Keys Developers: Authorizations Developers: Billing Summary Developers: Change History Developers: Domains Developers: News Feed Webhooks Developers: Roles Developers: Syndications Developers: Templates Developers: Usage Detail Developers: Usage Summary Devices Flexmls: Email Links Flexmls: Listing Meta Origins Flexmls: Listing Meta Translations Flexmls: Listing Meta Field List Translations Flexmls: Listing Reports Flexmls: Mapping Layers Flexmls: Mapping Shapegen IDX IDX Links Listing Carts Listing Carts: Portal/VOW Carts Incomplete Listings Incomplete Listings: Documents Incomplete Listings: Documents Metadata Incomplete Listings: Document Uploads Incomplete Listings: Floor Plans Incomplete Listings: FloPlans Incomplete Listings: Photos Incomplete Listings: Photos Metadata Incomplete Listings: Photo Uploads Incomplete Listings: Required Documents Incomplete Listings: Rooms Incomplete Listings: Tickets Incomplete Listings: Units Incomplete Listings: Videos Incomplete Listings: Videos Metadata Incomplete Listings: Virtual Tours Incomplete Listings: Virtual Tours Metadata Listings Listings: Clusters Listings: Documents Listings: Documents Metadata Listings: Floor Plans Listings: FloPlans Listings: Historical Listings: History Listings: Hot Sheet Parameters Listings: Notes Listings: Search Parameters Listings: Open Houses Listings: Photos Listings: Photos Metadata Listings: Photo Uploads Listings: Document Uploads Listings: Rental Calendar Listings: Required Documents Listings: Rooms Listings: Rules Listings: Tour of Homes Listings: Tickets Listings: Units Listings: Validation Listings: Videos Listings: Videos Metadata Listings: Virtual Tours Listings: Virtual Tours Metadata Listing Meta: Custom Fields Listing Meta: Custom Field Groups Listing Meta: Field Order Listing Meta: Field Relations Listing Meta: Property Types Listing Meta: Rooms Listing Meta: Standard Fields Listing Meta: Units Registered Listings Market Statistics News Feed News Feed: Curation News Feed: Events News Feed: Groups News Feed: Metadata News Feed: Restrictions News Feed: Schedule News Feed: Settings News Feed: Templates Notifications Open Houses Overlays Overlays: Shapes Portals Portals: Listing Categories Portals: Metadata Preferences Saved Searches Saved Searches: Provided Saved Searches: Restrictions Saved Searches: Tags Search Templates: Quick Searches Search Templates: Views Search Templates: Sorts Shared Links System Info System Info: Languages System Info: Search Templates
Supporting Documentation
Examples
RESO Web API
RETS
FloPlan
Terms of Use

Saved Searches

The Saved Searches service allows retrieval and management of saved searches for the current user.

flexmls Web Compatibility

Saved searches stored in the API have restrictions on their Filter attribute so that they can be exported to flexmls Web. Searches that do not meet these requirements cannot be saved in the API.

  1. Supported Roles
  2. Available Services
    1. Saved Searches
    2. Contact Saved Searches
    3. Individual Saved Searches
    4. Purge All News Feeds for a Search
    5. Saved Search Validation
  3. Saved Search Description
  4. Annotations
  5. Expansions
 

Supported Roles

Role Reads Writes Notes
IDX Yes No
Public Yes No
VOW Yes Yes
Portal Yes Yes
Private Yes Yes

More information about roles may be found here.

 

Available Services

Saved Searches

Saved searches as a subresource of contacts are only available in a private role.

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

HTTP Method Description Notes
GET Returns a list of all items for the current user
POST Creates a new saved search. If the AutoName attribute is set to true in the payload, the provided Name will be automatically modified in the event of a conflict so that it is unique.
PUT,DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

Parameters:

GET Response

Example:

{
    "D": {
        "Success": true,
        "Results": [
            {
              "ResourceUri": "/vX/savedsearches/20100815220615294367000000",
              "Id":  "20100815220615294367000000",
              "OwnerId": "20090815223215294334000000",
              "Name": "Search name here",
              "ContactIds": [],
              "UnsubscribedContactIds": [],
              "Description": "A longer description of the search",
              "Filter": "City Eq 'SomeCity'",
              "QuickSearchId": null,
              "ModificationTimestamp": "2011-03-14T08:39:38-05:00",
              "Tags": [],
              "Annotations": []
            },
            {
              "ResourceUri": "/vX/savedsearches/20100615220615292711000000",
              "Id":  "20100615220615292711000000",
              "OwnerId": "20090815223215294334000000",
              "Name": "Second search name here",
              "ContactIds": ["20120128220616323622000000"],
              "UnsubscribedContactIds": [],
              "Description": "A longer description of the search",
              "Filter": "City Eq 'Another City'",
              "QuickSearchId": null,
              "ModificationTimestamp": "2012-01-11T09:50:18-05:00",
              "Tags": ["Favorites"],
              "Annotations": []
           },
           {
              "ResourceUri": "/vX/savedsearches/2013011834897289072000000",
              "Id":  "2013011834897289072000000",
              "OwnerId": "20090815223215294334000000",
              "Name": "Third search name here",
              "ContactIds": [],
              "UnsubscribedContactIds": [],
              "Description": "A longer description of the search",
              "Filter": "Location Eq polygon('25.8022 -80.1639,32.1406 -64.7831,17.7721 -64.6513,25.8022 -80.1639')",
              "QuickSearchId": null,
              "ModificationTimestamp": "2013-01-18T07:29:11-05:00",
              "Tags": ["Favorites"],
              "Annotations": [{
                "Type": "Shape",
                "Match": {
                  "Substring": "polygon('25.8022 -80.1639,32.1406 -64.7831,17.7721 -64.6513,25.8022 -80.1639')"
                },
                "Attributes": {
                  "Label": "Bermuda Pentagon",
                  "Color": "CCCCFF"
                }
              }]
           },
       ]
     }
}

POST Request

Example:

{
    "D": {
      "Name": "My new saved search",
      "Description": "An optional longer description",
      "Filter": "City Eq 'My City'"
    }
}
 

POST Response

The standard success/fail response format is returned.

 

Contact Saved Searches

/<API Version>/contacts/savedsearches

Allows access to all searches created by consumers on the current user's portal. This will not include provided searches.

HTTP Method Description Conditional Notes
GET All searches created by consumers No
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
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
Pagination No
 
 

GET Response

See the GET request section for for the saved searches service.

 

Individual Saved Searches

Saved searches as a subresource of contacts are only available in a private role.

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

HTTP Method Description Notes
GET Returns a list of all items for the current user
POST Returns HTTP 405 (Method Not Allowed) Not implemented
PUT Updates a saved search record If the AutoName attribute is set to true in the payload, the provided Name will be automatically modified in the event of a conflict so that it is unique.
DELETE Deletes a saved search record Forbidden if the search has more than one Active news feed subscription or is still associated with an IDX link.

GET Request

Parameters:

Parameter Required
Standard expansion parameters No

GET Response

Example:

{
    "D": {
        "Success": true,
        "Results": [
            {
              "ResourceUri": "/vX/savedsearches/20100815220615294367000000",
              "Id":  "20100815220615294367000000",
              "OwnerId": "20090815223215294334000000",
              "Name": "Search name here",
              "Description": "A longer description of the search",
              "Filter": "City Eq 'SomeCity'",
              "QuickSearchId": null,
              "ModificationTimestamp": "2011-03-14T08:39:38-05:00"
            }
        ]
    }
}
 

PUT and DELETE Response

The standard success/fail response format is returned.

 

Purge All News Feeds for a Search

/<API Version>/savedsearches/<SavedSearch.Id>/newsfeeds

HTTP Method Description Conditional Notes
GET Returns HTTP 405 (Method Not Allowed) No Not implemented
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Schedules for deletion all news feeds for this search. No All feeds will be queued for deletion, and will be immediately set to Active: false.

DELETE Request

Parameters:

 

DELETE Response

The standard 'accepted for processing' response is returned.

 
 

Saved Search Validation

/<API Version>/savedsearches/validation

HTTP Method Description Conditional Notes
GET Returns HTTP 405 (Method Not Allowed) No Not implemented
POST Validates saved search data to be created, but does not perform the actual creation. No
PUT Returns HTTP 405 (Method Not Allowed) No Not implemented
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

POST Request

Request body:

{
    "D": {
      "Name": "My new saved search",
      "Description": "An optional longer description",
      "Filter": "City Eq 'My City'"
    }
}
 

POST Response

The standard success/fail response is returned.

 
 

Saved Search Description

Attribute Data Type Writeable Required Searchable Description
ResourceUri Character No No No The URI to the saved search.
Id Character No No Yes The unique Id of the saved search.
OwnerId Character No No No The Id of the user the search belongs to.
Name Character Yes Yes Yes The name of the search, unique per user. Maximum of 50 characters.
Description Character Yes No No A detailed description of the search. Maximum of 1000 characters.
Filter Character Yes, unless already null. Yes No The search filter to save. Maximum of 20000 characters.

Note: existing records with a null value have search criteria that could not be translated from the source system. This attribute cannot be updated for those searches.
QuickSearchId Character Yes No No The Id of the corresponding Quick Search. When present, the user prefers the criteria in the saved search to be used in conjunction with the referenced quick search.
ContactIds Character List Yes No No An array of contact Ids. Searches may be provided to a contact by adding the contact ID to this attribute.
UnsubscribedContactIds Character List No No No An array of contact Ids that list consumers that once had a news feed subscription for this search, but have deleted that subscription.
Tags Character List Yes No No An array of Tags associated with this search. Currently, the only supported tags are Favorites and Recent.
Provided Boolean No No No Indicates a retrieved SavedSearch was provided by the agent to a contact.
AutoName Boolean Yes No No Available as part of a POST or PUT body when creating or updating a saved search. If present, the provided Name will be automatically modified, in the event of a conflict, so that it is unique.
LastRunTimestamp Timestamp Updates only. Explicit permission required. No Yes The time the search was last run in a flexmls web application.
ModificationTimestamp Timestamp No No Yes The time the search was last updated.
CreatedTimestamp Timestamp No No No The time the search was created.
NewsFeedSubscriptionSummary Expansion No No No See the NewsFeedSubscriptionSummary expansion below.
ActiveSubscription Boolean No No No true if the current user or contact has at least one active news feed set up as a subscription to this search.
TotalActiveSubscriptionsCount Integer No No No The total number of active subscriptions across all users.
Annotations Various types Yes No No An array of Annotations associated with the Filter.
 

Annotations Description

The Annotations attribute provides an array of hashes which associate additional metadata with parts of a Filter. Currently this is used only to associate special labels and colors with shapes present in a filter. Annotations must be of a supported Type and correspond to a substring of the Filter; those that do not are dropped. Likewise, any Attributes not explicitly supported are dropped.

Attribute Data Type Writeable Required Searchable Description
Type Character Yes Yes No The type of Annotation. Currently only Shape is supported.
Match JSON Object Yes Yes No A hash which contains information linking the Annotation to the filter. Currently only Substring matching is supported.
Match.Substring Character Yes Yes No The substring of the Filter to which the Annotation corresponds.
Attributes JSON Object Yes Yes No A hash of values associated with the matched section of the Filter
Attributes.Label Character Yes No No The name associated with an Annotation of Shape type.
Attributes.Color Character Yes No No The hex color code associated with an Annotation of Shape type.
 

Expansions

Expansion Roles Single Record Only? Selection Support? Description
ContactNewsFeeds Private No No A list of news feed subscriptions the current user's contacts have for this search.
NewsFeeds All No No A list of news feed subscriptions the current user has for this search.
NewsFeedSubscriptionSummary All No No Information about news feeds set up as subscriptions to this search for the current user or contact.
Provided Private, Portal, VOW No No Includes all provided searches for the current Portal account or contact.
RecentListingUpdates All No No Timestamps and a SparkQL function for the offset the user has defined to be used in determining listing updates for this search.

{
  "Timestamps": ["OriginalEntryTimestamp"],
  "TimestampOffset": "days(-1)"
}
RecentListingUpdatesCount All Yes No Returns the count of listings matching the search whose timestamps specified in the RecentListingUpdates expansion were updated in the interval noted in the same expansion.
ReferencingQuickSearchIds All No No An Id list for all quick searches that reference this search via the SavedSearch attribute.