Advertiser API- Filtering

Filtering

Parameters of the Filter type allow the caller of an API method to restrict the results returned by the method to those which meet certain criteria. Fields that can be filtered are limited to those of the model whose type the function returns.

The default operator for filters is an equality filter that limits results to those models with a field matching a single value or one of a list of values. For example, if you wish to retrieve Offers whose status is "active" and whose currency is "USD", you can use the following filters:

&filters[status]=active&filters[currency]=USD

The default operator supports an array of values to achieve the effect of "is one of", so we can update our example to return Offers whose statuses are "paused" in addition to those that are "active" by using the parameter array notation "[]" to denote a list of statuses:

&filters[status][]=active&filters[status][]=paused&filters[currency]=USD

The default behavior for filters is to "AND" the conditions together so that results meet the criteria of every filter. It's also possible to construct a filter that "OR"s the conditions together. For example, if you wish to retrieve Offers whose status is "active" OR whose currency is "USD", you can construct a filter by prefixing each field with an "[OR]" block:

&filters[OR][status]=active&filters[OR][currency]=USD

In addition to the default equality operator, the following are additional comparison operators that can be used to limit results with a filter. Note that these are limited to comparing against a single value, rather than a list like the default operator.

• NOT_EQUAL_TO - Finds objects which do not have the provided value. Example: Retrieve Offers whose status is not equal to "active"

  &filters[status][NOT_EQUAL_TO]=active

• LESS_THAN - Finds objects which have a value less than the provided value. Example: Retrieve Offers whose id is less than 25

  &filters[id][LESS_THAN]=25

• LESS_THAN_OR_EQUAL_TO - Finds objects which have a value less than or equal to the provided value. Example: Retrieve Offers whose id is less than or equal to 25

  &filters[id][LESS_THAN_OR_EQUAL_TO]=25

• GREATER_THAN - Finds objects which have a value greater than the provided value. Example: Retrieve Offers whose id is greater than 25

  &filters[id][GREATER_THAN]=25

• GREATER_THAN_OR_EQUAL_TO - Finds objects which have a value greater than or equal to the provided value. Example: Retrieve Offers whose id is greater than or equal to 25

  &filters[id][GREATER_THAN_OR_EQUAL_TO]=25

• LIKE - Returns objects which have a value that matches the provided string, using case-insensitive search. The '%' character is a wildcard: use at the beginning of the string to find values ending in that string, at the end of the string to find values beginning with that string, or in the middle to find values bookended by two parts of the string. Example: Retrieve Offers whose names begin with "Atomic Tilt", such as "Atomic Tilt (iPhone/US)" or "Atomic Tilt (Android/SK)"

  &filters[name][LIKE]=Atomic Tilt%

  Example: Retrieve Offers whose names have "gift card" in them, such as "$1,500 Mondo Burger Gift Card" or "Mother's Day Flowers $500 Gift Card (Incent)"

  &filters[name][LIKE]=%gift card%

  Important: If you don't use a wildcard, the call only returns values that match the provided string, though still as a case-insensitive search.

• NOT_LIKE - Returns objects which have a value that does not match the provided string. The '%' character is a wildcard, with the same function as in the LIKE operator. Example: Retrieve Offers whose name does not contain "Free"

  &filters[name][NOT_LIKE]=%Free%

• NULL - Finds objects which have a value that is NULL. This is not the same as an empty string; you should use the EQUAL_TO conditional to find objects whose value is an empty string. Example: Retrieve Offers whose description is NULL

  &filters[description][NULL]=1

• NOT_NULL - Finds objects which have a value that is NOT NULL. This is not the same as an empty string; you should use the NOT_EQUAL_TO conditional to find objects whose value is not an empty string. Example: Retrieve Offers whose description is NOT NULL.

  &filters[description][NOT_NULL]=1

• TRUE - Finds objects which have a value that is the boolean true. Example: Retrieve Offers which are private

  &filters[is_private][TRUE]=1

• FALSE - Finds objects which have a value that is the boolean false. Example: Retrieve Offers which are not private

  &filters[is_private][FALSE]=1