Application API Search saved searches

October 15, 2026 at 9:35 AM

Saved Searches

Members can save arbitrary search criteria with a name and run those at a later date. This section describes the APIs available for managing Saved Searches. All these APIs are protected.

/members/self/searches [POST]

Saves a set of search criteria with a given name.

Parameters

Any parameters accepted by POST /searches are accepted here. In addition, a name parameter is required (string, up to 64 characters).

Response Messages

403 Forbidden

The possible failcode entries are:

  • 20222 - name was not provided
  • 20223 - name was empty or too long (limit 32)
  • 20224 - id was provided (other APIs do accept id however)
  • 20225 - A saved search with this name already exists
{ "fail" : "Invalid Argument", "failcode" : [ ... ] }

200 OK - success

The result includes all the input parameters as well as:

  • id - a unique identifier for the newly saved search that can be used in other APIs (it is a 24 character hex string)

/members/self/searches [PUT]

Replaces / updates a saved search with a given identifier.

Parameters

Any parameters accepted by POST /searches are accepted here. In addition, both a name and an id parameter are required. The saved search identified by the id parameter must exist.

Response Messages

403 Forbidden

Either the name or id parameters were missing (both are required), or the id parameter does not identify an existing saved search.

{ "fail" : "Invalid Argument" }

200 OK - success

/members/self/searches/ID-or-NAME/delete [POST]

Deletes the saved search with the given identifier or name.

Parameters

none

Response Messages

403 Forbidden

The URI does not identify an existing saved search. We recommend using the 24 character hex identifier in the URI, rather than a saved search name.

{ "fail" : "Invalid Argument" }

200 OK - success

/members/self/searches [GET]

Returns the matching search criteria.

Parameters

Without parameters, will return all of a member’s saved searches, sorted by name. Optionally accepts name and/or id to restrict the search to just those that match.

Response Messages

403 Forbidden

If the name or id parameters are present but invalid.

{ "fail" : "Invalid Argument" }

200 OK - success

The result is an array of saved searches:

  • searches : zero or more saved searches, ordered by name; each saved search has an id, a name, and a set of search criteria
{ "searches" : [ { "id" : "...", "name" : "...", ... }, ... ] }

/searches/ID-or-NAME [POST]

Runs the saved search identified by identifier or name. Note the URI is /searches rather than part of /members/self.

Parameters

none

Response Messages

403 Forbidden

The URI does not identify an existing saved search. We recommend using the 24 character hex identifier in the URI, rather than a saved search name.

{ "fail" : "Invalid Argument" }

200 OK - success

The result is the same as POST /searches, as if the criteria from the saved search had been suppied in that API call.