The API supports narrowing down the result set on each of the index pages via a filtering mechanism. Filters are passed as GET parameters, and you can add as many filters as you'd like to each request. Here are a few example urls:
# Returns all vehicles where the color is red https://secure.fleetio.com/api/v1/vehicles?q[color_eq]=red # Returns all vehicles that are 2010 or newer https://secure.fleetio.com/api/v1/vehicles?q[year_gteq]=2010 # Returns all vehicles that have a secondary meter https://secure.fleetio.com/api/v1/vehicles?q[secondary_meter_true]=1 # Returns all vehicles where the color is red AND the model year is 2010 or newer https://secure.fleetio.com/api/v1/vehicles?q[color_eq]=red&q[year_gteq]=2010
Let's talk about how filters are constructed.
You may have noticed a pattern emerging from the filters in the above examples. For one, each filter is wrapped in a
q block. You'll also notice that inside the
q is what appears to be a field name combined with an operator. Finally, being GET parameters, each filter is assigned a value. Let's break down each piece.
This is simply something we use to differentiate filter parameters from regular parameters. If a parameter is wrapped in
q, then we know for a fact that you're trying to filter. Be sure to always wrap your parameters in
The filter name is a combination of two things, a field name and an operator, which we call the predicate. The field name is just that, the name of the field to which you want to apply the filter. The predicate is the operation that is applied to the field. We currently support the following predicates:
- eq (equals, case sensitive)
- matches (case insensitive)
- lt (less than)
- lteq (less than or equal to)
- gt (greater than)
- gteq (greater than or equal to)
- cont (contains, used for matching partial strings)
- in_s (similar to SQL's
inoperator, accepts a string of comma separated values. Ex:
- true (boolean operator for true)
- false (boolean operator for false)
To construct the filter name, simply concatenate the field name and the predicate, adding an underscore in between.
You've already told us what you want to narrow down and how, but you haven't yet told us by what. This is where the value comes in. If you want all vehicles where the color is red, you simply pass
red as the value to
q[color_eq]=. If you want all vehicles where the id > 100, pass
100 as the value to
The value is a bit different for the
null predicates. We aren't comparing them with any value, we simply want the records where the predicate evaluates to true. When dealing with these four predicates, you can pass any value as long as it's not blank. Here at Fleetio we like to use
1 as the value, but that's just our personal preference.
Let's say that you want to construct a filter that returns all vehicles that have been created since January 1st, 2016. You take the field name,
created_at, concatenate with the greater than or equal to predicate,
gteq, add an underscore, and wrap it in q. The resulting filter is
q[created_at_gteq]. Now just add the value. In our case we want anything >= 2016-01-01, resulting in
What if we want that same result set, but only for vehicles that have no license plate? We just add another filter to our request using the
null predicate: q[license_plate_null]=1. The resulting url is:
If you want to use filters with cURL, you'll need to use the special
--globoff flag, otherwise cURL will choke on the
's used in the filters. So, your cURL request would look something like this:
curl \ --globoff \ --header "Authorization: Token YOUR_API_KEY" \ --header "Account-Token: YOUR_ACCOUNT_TOKEN" \ "https://secure.fleetio.com/api/v1/vehicles?q[created_at_gteq]=2016-01-01&q[license_plate_null]=1"
We take all filters in a request and
AND them together. There is currently no support for
OR. The best solution for applying
OR filters is to just issue several requests.
Custom fields require their own special filters. To tell Fleetio that you're searching for a custom field, your field name needs to be in this format:
CUSTOM_FIELD_NAME is the name of your custom field in Fleetio, for example:
PREDICATE is any predicate from the following list:
- eq (equals)
- not_eq (not equals)
- cont (contains)
- not_cont (does not contain)
- start (starts with)
- end (ends with)
- blank (record has or does not have custom field set. use 0 or 1 for values. more detail below)
Putting it all together, if you wanted to search for a work order with a custom field named
invoice_number containing the string 123, you would make the following call to the API:
To use the blank predicate for custom fields, use 0 or 1 as values. For example
q[custom_field_invoice_number_blank]=0 indicates that the custom field invoice number is not blank, and
q[custom_field_invoice_number_blank]=1 indicates that the custom field invoice number is blank
Checkbox (boolean) custom field values are stored as "true" or "false" strings, so if you wanted to search Work Orders for a boolean custom field named
paid, you would make the following call:
We treat sorting as just another
q wrapped predicate,
q[s]. Here are a few examples:
# Sort vehicles by name in ascending order https://secure.fleetio.com/api/v1/vehicles?q[s]=name+asc # Sort vehicles by name in descending order https://secure.fleetio.com/api/v1/vehicles?q[s]=name+desc # Sort vehicles by name without specifying an order, defaults to asc https://secure.fleetio.com/api/v1/vehicles?q[s]=name # You can sort by any field https://secure.fleetio.com/api/v1/vehicles?q[s]=created_at+desc # You can combine sorting and filters in a single request https://secure.fleetio.com/api/v1/vehicles?q[created_at_gteq]=2016-01-01&q[license_plate_null]=1&q[s]=created_at+desc
You can apply filters to any of the "index" endpoints that we provide. Want to get all of the fuel entries since January 1st?
Want all meter entries where the void flag is set to true?
Want to know if the number of Freds you have working in your company is too high?
The possibilities are endless!*
* Possibilities actually finite