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:

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:

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:

Require Custom Fields

We can also require custom fields. Requiring a custom field can be done with a toggle on the specific field in the Fleetio UI. Detailed instructions about toggling custom field requirements can be found here.

A value for a required custom field must be present in the request payload when creating or updating a given record with one caveat. The API will not enforce the presence of a required custom field's value if that field is not included in the custom_fields object of the request payload. Let's break that down.

Let's say we made our Shirt Size custom field for our Contacts required. Like this:

Now, let's update one of our Contacts with their Shirt Size. Here's how the validation breaks down.

If we make a request to update this Contact's Shirt size from Medium to Large, like in the request below, everything works, and the Contact is updated! Our request was successful because we included the shirt_size key and a value for it: Large.

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

If we make a request to update this Contact's Shirt size and exclude a value, the validation fails and tells us that a Shirt Size value is required.

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

If we make a request to update this Contact like the one below where we exclude the shirt_size key from the custom_fields object, the request succeeds. Our Contact's name gets updated to "George", but the Shirt Size custom field is unchanged. Although Shirt Size is required, validation passes because we didn't include it in the custom_fields object of the payload.

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

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.