Filter syntax

JSON API’s general filtering syntax and its supported operations can be used across all new APIs. Please note that support for given operators and fields is highly specific to each endpoint. You can refer to the filter query parameter in the API reference documentation for each specific operator and field support.

The filtering syntax for Klaviyo’s new APIs uses the ?filter query parameter for all endpoints that support filter operations. The following filter syntax can be used for more complex filtering operations across all endpoints:

URL encoding

Filter expressions can contain non-URL-safe characters. We recommend that you always URL-encode your request URLs in order to ensure filter expressions function properly.

Filter operations

Below are the supported filter operations supported for the standard filter syntax.

• equals
  • Example: ?filter=equals(last_name,"Smith")
  • Supported field types: string, boolean, number, datetime, array
• less-than
  • Example: ?filter=less-than(value,25)
  • Supported field types: number, datetime
• less-or-equal
  • Example: ?filter=less-or-equal(datetime,2001-01-01T11:00:00Z)
  • Supported field types: number, datetime
• greater-than
  • Example: ?filter=greater-than(datetime,2022-04-01T11:30:00Z)
  • Supported field types: number, datetime
• greater-or-equal
  • Example: ?filter=greater-or-equal(percentage,33.33)
  • Supported field types: number, datetime
• contains
  • Example: ?filter=contains(description,"cooking")
  • Supported field types: string, array
• contains-any
  • Example: ?filter=contains-any(description,["contains","something","in","this","array"])
  • Supported field types: string, array
• contains-all
  • Example: ?filter=contains-all(description,["contains","exactly","this","array"])
  • Supported field types: string, array
• ends-with
  • Example: ?filter=ends-with(description,"End")
  • Supported field types: string
• starts-with
  • Example: ?filter=starts-with(description,"Start")
  • Supported field types: string
• any
  • Example: ?filter=any(chapter,["Intro","Summary","Conclusion"])
  • Supported field types: string, number, datetime, boolean
• not
  • Example: ?filter=not(equals(last_name,null))
  • Accepts other operator functions as arguments, and cannot accept nested functions
  • not(equals(name,Ben)) is valid, not(or(equals(name,Tim),equals(name, Bob))) is not
• or
  • Example: ?filter=or(equals(last_name,"Smith"),equals(last_name,"qwerty"))
  • Accepts other operator functions as arguments, and cannot accept nested functions beyond 1 level deep
• and
  • Example: ?filter=and(equals(first_name,"Jane"),equals(email,"[email protected]"))
  • Accepts other operator functions as arguments, and cannot accept nested functions beyond 1 level deep

📘

Klaviyo’s APIs also interpret comma-separated filter expressions as an alias for an and wrapper function.
For example: filter=and(equals(field1,"foo"),or(equals(field2,"bar"),equals(field2,"foobar")))
can be simplified to
filter=equals(field1,"foo"),or(equals(field2,"bar"),equals(field2,"foobar"))

This can be particularly helpful for filtering on a date range. For example, pulling all events for a specific metric for a specific time range would look like the below, swapping out your own metric_id and datetime values:

filter=equals(metric_id,"UxxK4u"),greater-or-equal(datetime,2023-02-07),less-than(datetime,2023-02-15)

Comparison literals

• string: Arguments representing string literals are expressed with quotation marks (we will accept either single quoted or double-quoted strings). Single or double-quoted characters within strings (quoted with like quote characters) MUST be escaped with a single backslash (i.e. ‘Tony\’s ball’)
  Comparisons to all string literals are case-sensitive, unless otherwise noted in endpoint specific documentation
• boolean: Booleans are expressed as unquoted true and false literal values
• number: Numbers are expressed as standard integer or float representations
  datetime: Datetimes are expressed as unquoted ISO-8601 RFC-3339 formatted strings. For example, 2012-04-21T11:30:00-04:00
• array: Array literals are expressed using square brackets ([ ])
• null: Null is a reserved literal to represent null values for fields of any type