API Filters

This section describes how to include filters with your API queries. Examples usages are:

• Returning all Ad Units with a name that contains "footer"

• Returning all Line Items that started delivering after 2021/01/01

• Returning all Line Items in a RUNNING or ENDED state

Example Queries

This introduces the filtering capabilities of the API with some concrete examples. A full description of all the available parameters is provided in the next section.

Return all Ad Units with a name that contains "footer"

This makes use of the filterBy and filterByLike query parameters.

https://api.adnuntius.com/api/v1/adunits?auth_token=TOKEN&filterBy=name&filterByLike=footer

Return all Line Items that started delivering after 2021/01/01

This makes use of the where query parameter.

https://api.adnuntius.com/api/v1/lineitems?auth_token=TOKEN&where=startedRunningDate>2021-01-01

Conditions can be added to the where clause by using the ; separator character. So if we wanted to search for Line Items that started delivering between 2021-01-01 and 2021-06-01 we could use:

https://api.adnuntius.com/api/v1/lineitems?auth_token=TOKEN&where=startedRunningDate>2021-01-01;startedRunningDate<2021-06-01

Return all Line Items in a RUNNING or ENDED state

This also makes use of the where query parameter, and introduces the in operator.

https://api.adnuntius.com/api/v1/lineitems?auth_token=TOKEN&where=executionState+in+RUNNING,ENDED

Likewise, you can also use a not in operator:

https://api.adnuntius.com/api/v1/lineitems?auth_token=TOKEN&where=executionState+not+in+RUNNING,ENDED

Full Parameter Description

Flags

The following flags are supported:

Flag	Description
includeActive	include objects with an ACTIVE state
includeInactive	include objects with an INACTIVE state
includeHidden	include objects with a HIDDEN state
excludeInvalid	exclude objects with validation warnings
onlyMine	only return objects that were created by the current API user

Basic Filtering Parameters

Flag	Description	Example
filterBy	the field name of the object	filterBy=name
filterByValue	an exact match on the filtered field value. Requires filterBy	filterBy=name&filterByValue=Campaign
filterByLike	a match on any values in the filtered field that contain the supplied string. Requires filterBy	filterBy=name&filterByLike=Camp
filterByNotLike	a match on any values in the filtered field that do NOT contain the supplied string. Requires filterBy	filterBy=name&filterByNotLike=Camp
excludeIfMissing	a non-null filter	excludeIfMissing=tierId

Advanced where Clause

You can chain multiple conditions together into a where clause using the following syntax:

where=CONDITION;CONDITION;CONDITION

where each CONDITION can be one of the following:

Condition	Example
Equals	name=Adnuntius
Not Equals	name!=Adnuntius
Greater Than	startDate>2021-01-01
Greater Than Or Equal to	startDate>=2021-01-01
Less Than	startDate<2021-01-01
Less Than Or Equal to	startDate<=2021-01-01
Is In	objectState+in+ACTIVE,INACTIVE
Is Not In	objectState+not+in+ACTIVE,INACTIVE
Is Null	description+is+null
Is Not Null	description+is+not+null

The where filter matches when ALL of the CONDITIONs are met.

Advanced Timestamp where Clauses

The following interval expressions are supported:

• X minutes later

• X minutes ago

• 1 hour later

• 1 hour ago

• X hours later

• X hours ago

• 1 day later

• 1 day ago

• 1 month later

• 1 month ago

• X months later

• X months ago

• 1 year later

• 1 year ago

• X years later

• X years ago

Where X is an integer > 0. The singular minute, hour, day, month and year are for convenience only. You can for example specify 1 hours ago, which is the same as 1 hour ago.