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.
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:
| Parameter | Required |
|---|---|
| Standard expansion parameters | No |
| Standard search and paging syntax | No |
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:
- None
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. |
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. |