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. Individual Saved Searches
    3. Saved Search Validation
  3. Saved Search Description
  4. Expansions
  5. API Explorer

Supported Roles

Role Reads Writes Notes
IDX Yes No
VOW 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.

URI: /<API Version>/savedsearches

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

HTTP Method Description Notes
GET Returns a list of all items for the current user
POST Create a new saved search
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": [],
              "Description": "A longer description of the search",
              "Filter": "City Eq 'SomeCity'",
              "QuickSearchId": null,
              "ModificationTimestamp": "2011-03-14T08:39:38-05:00",
              "Tags": []
            },
            {
              "ResourceUri": "/vX/savedsearches/20100615220615292711000000",
              "Id":  "20100615220615292711000000",
              "OwnerId": "20090815223215294334000000",
              "Name": "Second search name here",
              "ContactIds": ["20120128220616323622000000"],
              "Description": "A longer description of the search",
              "Filter": "City Eq 'Another City'",
              "QuickSearchId": null,
              "ModificationTimestamp": "2012-01-11T09:50:18-05:00",
              "Tags": ["Favorites"]
           }
       ]
     }
}

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.

Individual Saved Searches

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

URI: /<API Version>/savedsearches/<Id>

URI: /<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 Forbidden if the existing Filter attribute is null
DELETE Deletes a saved search record Forbidden if the existing Filter attribute is null

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.

Saved Search Validation

URI: /<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 Searchable Writeable Required Description
ResourceUri Character No No No The URI to the saved search.
Id Character Yes No No The unique id for the saved search.
OwnerId Character No No No The id of the owner the search belongs to.
Name Character Yes Yes Yes The name of the search, unique per user. Maximum of 50 characters.
Description Character No Yes No A detailed description of the search. Maximum of 1000 characters.
Filter Character No Yes Yes The search filter to save. Maximum of 20000 characters.
QuickSearchId Character No Yes 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 Array of Character No Yes No An array of Contact Ids. Searches may be provided to a contact by adding the contact ID to this attribute
Tags Array of Character No Yes Yes An array of Tags associated with this search. Currently, the only supported tag is Favorites
Provided Boolean No No No Indicates a retrieved SavedSearch was provided by the agent to a contact
NewsFeedSubscriptionSummary Expansion 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.

Expansions

Expansion Roles Single Record Only? Selection Support? Description
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, VOW No No Includes all provided searches for the current VOW account or contact.
ReferencingQuickSearchIds All No No An Id list for all quick searches that reference this search via the SavedSearch attribute.

API Explorer

Interact with this service using the API Explorer.