URI Encoding

All examples below are formatted for readability, actual GET requests require URI encoding. See example below vs the URI encoded equivalent.

Formatted for readability:

/contacts?filter[first_name]=Marcel

URI encoded equivalent:

/contacts?filter%5Bfirst_name%5D=Marcel

TIP: Constructing manual URI encoded filters queries

To manually create URI encoded filter queries use the handy jQuery.param() function from your browser's console on any website with jQuery installed.

$.param({
   filter: {
      email: {
         $in: [
            "test1039@test.envoke.com",
            "test1052@test.envoke.com"
         ]
      }
   }
});

Result:

"filter%5Bemail%5D%5B%24in%5D%5B%5D=test1039%40test.envoke.com&filter%5Bemail%5D%5B%24in%5D%5B%5D=test1052%40test.envoke.com"

Simple filtering with GET requests

Return all contacts with the first name of "Marcel"

/contacts?filter[first_name]=Marcel

Multiple filters can be appended, and they will be joined with a logical AND operator.
The example below will return all contacts with the first name "Martin" and the email "martin@envoke.com".

/contacts?filter[first_name]=Martin&filter[email]=martin@envoke.com

Filtering Keywords & Operators

NOTE: All examples will be in displayed with pretty printed JSON for readability, but actual GET requests will require URI encoding.

Filters support nested levels of operators, and the filter object is modelled on that of mongoDB.

The supported keywords are:

$and = Logical AND. This is the default operator and is not required in most cases as two filters at the same level will produce an $and
$or = Logical OR
$ne = Not equal
$in = Match value in a set (can replace many OR conditions)
$regex = Match a regex pattern
$gt = Greater than
$lt = Less than
$gte = Greater than or equal
$lte = Less than or equal

NOTE: Not all fields support every operator. Unsupported fields will return as a validation error.

Example request showing a logical AND filter containing a regex match plus additional sort, limit and skip:

{
   "filter": {
      "marketing_rating_status": "PASSED_TO_SALES",
      "contact.email": {
         "$regex": "envoke|bettermail|agito"
      }
   },
   "sort": {
      "contact.email": "ASC"
   },
   "limit": 1,
   "skip": 5
}

URI encoded equivalent GET Request

/leads?filter%5Bmarketing_rating_status%5D=PASSED_TO_SALES&filter%5Bcontact.email%5D%5B%24regex%5D=envoke%7Cbettermail%7Cagito&sort%5Bcontact.email%5D=ASC&limit=1&skip=5

Example OR filter

{
   filter: {
      $or: [
         { first_name: "Marcel" },
         { first_name: "Marcus" }
      ]
   }
}

URI encoded equivalent GET Request

/contacts?filter%5B%24or%5D%5B0%5D%5Bfirst_name%5D=Marcel&filter%5B%24or%5D%5B1%5D%5Bfirst_name%5D=Marcus