Filtering

Filtering is useful because it allows you to get specific data out of the whole collection. For example, getting call transcripts only from a specific date and time.

Request parameter

To filter the API endpoint, use the filter query parameter in the request.

Request parameter value

The value of the parameter supports the following syntax (ABNF):

• upalpha = "A" / "B" / "C" / "D" / "E" / "F" / "G" / "H" / "I" / "J" / "K" / "L" / "M" / "N" / "O" / "P" / "Q" / "R" / "S" / "T" / "U" / "V" / "W" / "X" / "Y" / "Z"

• lowalpha = "a" / "b" / "c" / "d" / "e" / "f" / "g" / "h" / "i" / "j" / "k" / "l" / "m" / "n" / "o" / "p" / "q" / "r" / "s" / "t" / "u" / "v" / "w" / "x" / "y" / "z"

• alpha = lowalpha / upalpha

• digit = "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9"

• hex = "A" / "B" / "C" / "D" / "E" / "F" / "a" / "b" / "c" / "d" / "e" / "f" / digit

• escaped = "%" hex hex

• val = 1*( alpha / digit / escaped )

• cond-field = val

• cond-oper = "=" / "!=" / ">" / "<" / ">=" / "<="

• cond-value = val *( ";" val )

• condition = cond-field cond-oper cond-value

• filter = "(" condition *( "," condition ) ")"

How to use

• The filter value must be surrounded by parenthesis.

• A single condition is a tuple of field, operator and a value.

• Multiple conjunctive (AND) conditions can be separated by a comma (",").

• For a single condition, multiple disjunctive (OR) values can be separated by semicolon (";"). This is only supported for "=" and "!=" operators.

• Non-alphanumeric characters in the value must be escaped using URL escaping (with "%").

• When sending as a query parameter, the whole filter is escaped (i.e., non-alphanumeric characters are double escaped).

• For date-time fields, the value can be set without time (YYYY-MM-DD) or as complete RFC 3339 UTC time (YYYY-MM-DDTHH:MM:SS.LLLZ). If the value is without time, the time "00:00:00" is assumed.

Examples

• Equals 7 or 12 (id=7;12):

GET /api/v1/calls?filter=(id%3D7%3B12)

• Above 7 and below 12 (id>7,id<12):

GET /api/v1/calls?filter=(id%3E7%2Cid%3C12)

• Above 7 and below 12, but not 10 (id>7,id<12,id!=10):

GET /api/v1/calls?filter=(id%3E7%2Cid%3C12%2Cid!%3D10)

• Double escaping of strings (name=first%20last):

GET /api/v1/calls?filter=(name%3Dfirst%2520last)

• Using dates to filter specific day (setupTime>=2022-04-26,setupTime<2022-04-27):

GET /api/v1/calls?filter=(setupTime%3E%3D2022-04-26%2CsetupTime%3C2022-04-27)

• Using times to filter specific hour (setupTime>=2022-04-26T15:00:00.000Z,setupTime<2022-04-26T16:00:00.000Z):

GET /api/v1/calls?filter=(setupTime%3E%3D2022-04-26T15%3A00%3A00.000Z%2CsetupTime%3C2022-04-26T16%3A00%3A00.000Z)

Searching by Text

For APIs that allow filtering by free text, the "text" field is used inside the filter. For example:

• Free text only (text=some%20words):

GET /api/v1/calls?filter=(text%3Dsome%2520words)

• Free text with other filters such as the date filter (setupTime>=2022-04-26,setupTimee<2022-04-27,text=some%20words):

GET /api/v1/calls?filter=(setupTime%3E%3D2022-04-26%2CsetupTime%3C2022-04-27%2Ctext%3Dsome%2520words)