SearchExecute Endpoint | Sign-Up.to Permission Marketing API

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

Attribute	Type	Filter	Sort	Description
id	int	Yes	Yes	Unique ID of the resource.
completed	bool	No	No	False 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/null	No	No	If 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/null	No	No	If 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/null	No	No	ID of a list to which subscribers matching the search should be added.
progress	decimal/null	No	No	Approximate 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	int	Yes	No	ID of the search to execute.
store	bool	No	No	Whether to temporarily store the results e.g. for exporting or a subscriber lookup.
subscriber_count	int/null	No	No	The number of subscribers matched by the search criteria and visible to the user who executed the search.
user_id	int	Yes	No	ID of the user who requested execution of the search.
cdate	decimal	No	Yes	Creation timestamp.
mdate	decimal	No	No	Last modification timestamp.

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

HEAD /searchExecute or /searchExecute/:id

Attribute	Type	Presence	Description
id	int	Optional	Unique ID of the resource.
search_id	int	Optional	ID of the search to execute.
user_id	int	Optional	ID of the user who requested execution of the search.

POST /searchExecute

Attribute	Type	Presence	Description
list_id	int/null	Optional	ID of a list to which subscribers matching the search should be added.
search_id	int	Required	ID of the search to execute.
store	bool	Optional	Whether 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
 }