Filtering
All filtering related query parameters begin with filter
.
Filtering using a target
Imagine by default that nothing is filterable. For each list endpoint, we specify filter parameter names or “targets” (in the endpoint documentation). The most basic example: filter[$target]=$value.
These targets could be whatever we (Teamwork CRM team) decide, and they can do whatever we’d like under the hood.
An example might be title
and basic usage would look like filter[title]=test
. I.e. show me the deals which have a title of test
.
Operators
A more advanced version would be filter[$target][$operator]=$value
; e.g. filter[title][in]=test,hello
. The operator is optional. It defaults to eq
but can be any of the following:
Operator | Example | Description |
---|---|---|
eq |
foo |
Value is equal to |
in |
open,closed |
Value exists in comma-separated list of values |
like |
*foo* |
Value is like (uses wildcard). Wildcards at start at end is like “contains”, just at the start would be “ends with”, and just at the end would be “starts with” |
gt | 2018-02-26T00:00:00Z | Value is greater than |
gte | 1 | Value is greater than or equal to |
lt | 2 | Value is less than |
lte | 3 | Value is less than or equal to |
Binding
There can also be an “alias” given to a filter; e.g. filter[$target][$operator][$alias]=$value
. The alias is optional and will default to the $target
if omitted. Aliases can contain [a-zA-Z0-9-_]
.
The alias allows the API user to build more complex conditions to filter on. By default every filter provided is put together with AND
. What if you wanted “this filter or this other filter”? Or “this or not this other filter”? That’s what filter[binding]
is for.
?filter[binding]=$expression
$expression
can contain aliases and symbols;
Operator | Type | Example |
---|---|---|
& |
AND |
a&b |
| |
OR |
a|b |
! |
NOT |
!a |
() |
Brackets | (a|b)&c |
If a binding is given it must contain all provided filters.
Example
First name is “John” or last name is not “Smith”
GET contacts
?filter[firstName][eq][alias1]=John
&filter[lastName][randomAliasName]=Smith
&filter[binding]=alias1|!randomAliasName
Feedback
If you have any feedback or suggestions, feel free to contact us at api@teamwork.com.