Filter list responses

Most services in the Display & Video 360 API provide a LIST method for bulk retrieval of resources. These LIST methods usually support filtering results through a filter query parameter. Use this parameter to optimize your API usage by only retrieving what you need.

This guide shows how to use the filter parameter effectively.

Filter structure

A filter parameter value is a string, consisting of one or more restrictions that can be combined with AND or OR operators, and grouped using parentheses.

Restrictions are of the form {field} {operator} {value}. Here's an example:

entityStatus="ENTITY_STATUS_ACTIVE"

The filter string length cannot exceed 500 characters. If your filter string exceeds 500 characters, do one of the following:

  • Split the logic into multiple filter strings, and retrieve the resources using separate LIST requests.
  • Remove some of the logic from the filter string, and use it to filter the retrieved resources locally.

Wrap restriction values in quotes to ensure logic is properly applied.

URL-encode your filter strings if you are making LIST calls directly without using a client library.

See Logic between restrictions for more details on formatting your queries.

Filterable fields

Each LIST method's filterable fields are listed in the method's filter parameter description. In most cases, you can filter on a subset of a resource's standard fields. In some rare cases, there are additional fields you can use only for filtering.

Each field in the parameter's description supports at least one of the following comparable operators:

Comparable Operators
EQUALS (=) Resource field value is equal to given value.

Example: entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=) Resource field value is less than or equal to given value. Often used when comparing a date or datetime.

Example: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=) Resource field value is greater than or equal to given value. Often used when comparing a date or datetime.

Example: updateTime>="2023-03-01T12:00:00Z"
HAS (:) Resource field value contains the given value. If the resource field is a string, it will check if the given value is an existing substring. If the resource field is an array, it will check if the array contains the given value.

Example: lineItemIds:"1234"

If no operators are specified for the field in the parameter's description, you can only use the EQUALS (=) operator. Some fields support multiple operators.

Some filterable fields, such as those for dates and times, require the comparable value to follow a specific format. The format is specified next to the field in the filter parameter description.

Logic between restrictions

You can combine multiple restrictions to narrow or expand the response from your LIST request.

You can usually combine multiple restrictions with AND and OR logical operators. Each LIST method specifies which operators it supports. Some methods only support using a single restriction in the filter parameter.

Consider the following restrictions when building filter strings with AND or OR logical operators:

  • AND must be used between restrictions, or groups of restrictions, that filter different fields, or that filter the same field differently. Here are some examples:
    • updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE"
    • updateTime>="2023-03-01T12:00:00Z" AND updateTime<="2023-04-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED")
  • OR must be used between individual restrictions that filter by the same field. Here's an example:
    • (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")

  • You can't use OR to combine two groups of restrictions. Use multiple LIST requests with different filter values instead. For example, use the following separate LIST requests:

    • (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")
    • (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

    Don't use the OR operator to combine them:

    (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123") OR (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

  • Parentheses might be implied if you don't use them to group restrictions in a filter string. For example, the following filter string:

    updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT"

    is interpreted as:

    updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")