Saved Searches

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

Note: due to compatibility constraints, existing searches with a null Filter attribute cannot be modified. Additionally, flexmls Web does not yet support searches created through 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 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:
  • None

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'",
              "ModificationTimestamp": "2011-03-14T08:39:38-05:00"
            },
            {
              "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'",
              "ModificationTimestamp": "2012-01-11T09:50:18-05:00"
           }
       ]
     }  
}

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:
  • None

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'",
              "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.
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

Expansions

None.

API Explorer

Interact with this service using the API Explorer.