Custom Fields

Fleetio provides many pre-defined program fields to store details for various data records. You may wish to track additional information, and Custom Fields give you a place to store and report these values.

An unlimited number of Custom Fields are available for Contacts, Expense Entries, Fuel Entries, Issues, Parts, Purchase Details, Purchase Orders, Service Entries, Vehicles, Vehicle Assignments, Vehicle Renewal Reminders, Vendors, and Work Orders.

Custom Fields consist of two parts - a Label to name the field, and a Data Type that determines what sort of data this field supports. Available Data Types are:

Data TypeValue
TextAny text value is acceptable. Can be words, numbers, etc. as long as they are in String format. Examples: "Excellent", "9", or "1.5".
Drop-downThe same as Text, except this is constrained to a pre-defined set of text values. Examples: "Excellent", "9", or "1.5"
CheckboxBoolean. Examples: true or false.
DateDate value. Example: "2018-08-09 12:00:00 -0600"

To illustrate how Custom Fields work, let's say we want to store the T-shirt size for our Contacts in Fleetio so we can buy them a swaggy company shirt every now and then. Fleetio doesn't have a way to store this information by default for Contacts - there isn't a field for "Shirt Size" for Contacts. So we would create a Custom Field for Contacts, with a label called "Shirt Size". In this case, we also want to define the possible values it can have - (Small, Medium, Large, Extra Large, etc.). We wouldn't want anyone saying their T-shirt size was "Eleventeen", now would we? So we will choose the Drop-down data type to constrain the possible answers to our list of values.

In order to create or update Custom Fields, we'll have to use the Fleetio UI. Full documentation available here. For example:

38403840

Once we've created the Custom Fields for a given entity via the Fleetio UI, we can then utilize those custom fields in our API requests to pull or push information in and out of Fleetio. One important thing to note is that spaces get converted into _'s, and all uppercase letters are downcased. So Shirt Size as the Label in the UI will become shirt_size in API requests / responses.

For example, let's say we have a Contact with the ID of 1234, and we want to give them a shirt_size of Medium, we could do this using cURL like so:

curl \
  --request PATCH \
  --header "Authorization: Token abcdefghijklmnopqrstuvwxyz" \
  --header "Account-Token: 9876543210" \
  --header "Content-Type: application/json" \
  --data '{"custom_fields": { "shirt_size": "Medium"}}' \
  "https://secure.fleetio.com/api/v1/contacts/1234"

Now, you can see this value in the Fleetio web UI for this user:

33603360

And that's all there is to it! To learn more about working with Custom Fields, check out our guide on Filtering with Custom Fields.