SearchExecute v1.2

Executes a search.

What can I do with searchExecute?

Get a count of subscribers matched by the search criteria.

  • Use list_id to save matched subscribers to a list.
  • Check completed to see the status of your search processing.
  • The errorcode and error attributes will describe any issues which may arise during search processing. Read more

The result set can differ per sub-user if the user executing a search doesn't have access to a list due to folder restrictions.

GET /searchExecute or /searchExecute/:id

AttributeTypeFilterSortDescription
id
intYesYesUnique ID of the resource.
completed
boolNoNoFalse if search processing has not yet started, or if search processing is underway; true if search processing has completed (whether successfully or unsuccessfully).
error
string/nullNoNoIf an error occurs when processing a search, this attribute will contain a human-readable description of the error. If the search completes successfully, this attribute will return an empty string. If the search has not yet completed, this attribute will return null.
errorcode
int/nullNoNoIf an error occurs when processing a search, this attribute will contain a numeric error code. If the search completes successfully, this attribute will return zero (0). If the search has not yet completed, this attribute will return null.
list_id
int/nullNoNoID of a list to which subscribers matching the search should be added.
progress
decimal/nullNoNoApproximate progress of search processing, in the range 0-1. When search processing starts, this attribute will return zero (0); the returned value will increase towards 1 as the search is executed. This attribute will return null if a search has failed, or has not yet been run.
search_id
intYesNoID of the search to execute.
store
boolNoNoWhether to temporarily store the results e.g. for exporting or a subscriber lookup.
subscriber_count
int/nullNoNoThe number of subscribers matched by the search criteria and visible to the user who executed the search.
user_id
intYesNoID of the user who requested execution of the search.
cdate
decimalNoYesCreation timestamp.
mdate
decimalNoNoLast modification timestamp.

Admin users can see everybody's search execution requests; regular users can see only their own requests.

HEAD /searchExecute or /searchExecute/:id

AttributeTypePresenceDescription
id
intOptionalUnique ID of the resource.
search_id
intOptionalID of the search to execute.
user_id
intOptionalID of the user who requested execution of the search.

POST /searchExecute

AttributeTypePresenceDescription
list_id
int/nullOptionalID of a list to which subscribers matching the search should be added.
search_id
intRequiredID of the search to execute.
store
boolOptionalWhether to temporarily store the results e.g. for exporting or a subscriber lookup.

Admin users can execute everybody's searches; regular users can execute only their own searches.

Results will be stored for 7 days after last use, after which they will expire and no longer be available. When storing results, note that there will be a small delay before the stored results are ready to be used.

PUT /searchExecute or /searchExecute/:id

This method is not supported.

DELETE /searchExecute or /searchExecute/:id

This method is not supported.

Error codes

This endpoint exposes any errors encountered during the search processing through the errorcode attribute. Please note, this errorcode differs to those exposed through erroneous requests because this errorcode is permanent and request-agnostic.

Error Description
1
Internal error.
2
Syntax error.
3
Resource error.
4
List search syntax error.
5
Subscriber data search syntax error.
6
Geolocation search syntax error.
7
Engagement search syntax error.
8
Behaviour search syntax error.

Examples

JSON response

{
    "id"               : 123456,
    "completed"        : false,
    "error"            : null,
    "errorcode"        : null,
    "list_id"          : null,
    "progress"         : 0.24,
    "search_id"        : 98765,
    "store"            : false,
    "subscriber_count" : 17542,
    "user_id"          : 12345,
    "cdate"            : 123456,
    "mdate"            : 123456
 }