Requiring Custom Fields

Required Custom Fields must have a value during create and update operations. If a value is not provided, the operation will fail with an error message.

To mark a Custom Field as Required, Navigate to the Custom Fields Accounts Settings and set the "Required" toggle switch to "ON" for the field.

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 required for Contacts, like this:

Now, let's update one of our Contacts with their Shirt Size.

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

Successful request, both key and value included.

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:

Unsuccessful request, value excluded.

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:

Unsuccessful request, key excluded.

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!