API Support

Filtering and Sorting Results

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.

Constructing a filter

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.

q[]

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 q[].

The filter name

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 in operator, accepts a string of comma separated values. Ex: q[name_in_s]=name1,name2
  • true (boolean operator for true)
  • false (boolean operator for false)
  • present
  • null

To construct the filter name, simply concatenate the field name and the predicate, adding an underscore in between.

The value

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 q[id_gt]=.

The value is a bit different for the true, false, present, and 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.

Bringing it together

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 q[created_at_gteq]=2016-01-01.

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:

https://secure.fleetio.com/api/v1/vehicles?q[created_at_gteq]=2016-01-01&q[license_plate_null]=1

Filtering quirks with cURL

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"

And & Or

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

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_CUSTOM_FIELD_NAME_PREDICATE

CUSTOM_FIELD_NAME is the name of your custom field in Fleetio, for example: invoice_number
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:

https://secure.fleetio.com/api/v1/work_orders?q[custom_field_invoice_number_cont]=123

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 custom field types

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:

https://secure.fleetio.com/api/v1/work_orders?q[custom_field_paid_eq]=true

Sorting

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

Not just for vehicles!

You can apply filters to any of the "index" endpoints that we provide. Want to get all of the fuel entries since January 1st?

https://secure.fleetio.com/api/v1/fuel_entries?q[created_at_gteq]=2016-01-01

Or maybe just January 1st?

https://secure.fleetio.com/api/v1/fuel_entries?q[submitted_at_gteq]=2016-01-01&q[submitted_at_lt]=2016-01-02

Want all meter entries where the void flag is set to true?

https://secure.fleetio.com/api/v1/meter_entries?q[void_true]=1

Want to know if the number of Freds you have working in your company is too high?

https://secure.fleetio.com/api/v1/contacts?q[first_name_eq]=Fred

The possibilities are endless!*

* Possibilities actually finite