Working with Fuel Entries

Overview

A single Fuel Entry can have multiple types of location data associated with it. For example: a Fuel Entry can have the location of the gas station where the fuel-up occurred, and it can have the location reported by the Vehicle's telematics hardware at the time the fuel-up occurred.

By comparing these two coordinates, we can determine if the Vehicle was actually present at the gas station when the fuel-up occurred (or if the Vehicle was somewhere else, indicating a possibly fraudulent fuel-up.)

The location of the gas station is stored automatically on the Fuel Entry if a vendor_id is saved on that Fuel Entry, and if that Vendor's location is saved in Fleetio.

tip

If a Fleetio customer has a fuel integration in Fleetio with one of our supported Fuel Card partners, this process happens automatically.

When a Fuel Entry is created, all you have to do is give it a vendor_id, and that Vendor's location will be saved as the location where the fuel-up occurred.

The second part of the process is saving the Vehicle's location at the time of the fuel-up as reported by the onboard telematics hardware.

To do this, we must fetch any and all Fuel Entries that need to be updated.

Fetching Relevant Fuel Entries

Use the GET /api/v1/fuel_entries endpoint to get a list of entries back.

Here is an example of how you'd fetch these Fuel Entries.

curl \
  --include \
  --header "Authorization: Token API_KEY" \
  --header "Account-Token: ACCOUNT_TOKEN" \
  "https://secure.fleetio.com/api/v1/fuel_entries"

That gets us a list of Fuel Entries for our Account, but we may only want to see results that were created today and which do not include GPS data. We can narrow down the result set by passing filters to the API.

For example:

curl \
  --globoff \
  --include \
  --header "Authorization: Token API_KEY" \
  --header "Account-Token: ACCOUNT_TOKEN" \
  "https://secure.fleetio.com/api/v1/fuel_entries?q[geolocation_gps_device_null]=1&q[created_at_gteq]=2023-06-06"

We've added two filters: q[geolocation_gps_device_null]=1 and q[created_at_gteq]=2023-06-06. The first filter excludes results with GPS data, while the second filter excludes records older than June 6, 2023.

Note that we had to use --globoff so that curl will interpret [] and {} as part of the url and not as a glob directive.

Updating the Fuel Entry

To update a Fuel Entry's position, we issue a request for each Fuel Entry (PATCH /api/v1/fuel_entries/:id), specifying values for geolocation[gps_device][latitude] and geolocation[gps_device][longitude].

For example:

curl \
  --include \
  --header "Authorization: Token API_KEY" \
  --header "Account-Token: ACCOUNT_TOKEN" \
  --request PATCH \
  --data "geolocation[gps_device][latitude]=32.8117055&geolocation[gps_device][longitude]=-97.0254227" \
  "https://secure.fleetio.com/api/v1/fuel_entries/123"

And that's it! Fleetio takes care of the rest.

You can verify that the GPS data was added successfully by viewing the Fuel Entry in the browser. If a fuel exception is fired, the Account Owner will receive an email, and the warning message will be visible on the Fuel Entry's detail page. Please keep in mind that the fuel exception calculator runs in the background and may take a few minutes to process.