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 Description
  4. Expansions
  5. API Explorer

Supported Roles

Role Reads? Writes?
IDX Yes No
VOW (As Portal Group) 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:
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",
              "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 Description

Attribute Data Type Writeable? Required? Description
ResourceUri Character No No The URI to the saved search.
Id Character No No The unique id for the saved search.
OwnerId Character No No The id of the owner the search belongs to.
Name Character Yes Yes The name of the search, unique per user. Maximum of 50 characters.
Description Character Yes No A detailed description of the search. Maximum of 1000 characters.
Filter Character Yes Yes The search filter to save. Maximum of 20000 characters.
QuickSearchId Character 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 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 Yes Yes An array of Tags associated with this search. Currently, the only supported tag is Favorites

Expansions

None.

API Explorer

Interact with this service using the API Explorer.