🚧

Public Applications Only

The ServiceM8 Custom Fields API is only available to Public Applications. You will need to implement OAuth 2.0 Authentication and obtain an access token before you can use the Custom Fields API.

Custom fields allow you to add additional fields to the standard database schema per account.

ServiceM8 Custom Fields are commonly used for:

  • Collecting additional job or client information
  • Used in conjunction with Web Hooks to trigger workflows

When to Use Custom Fields

Our thoughts on custom fields are that they are inappropriate for most use cases. Custom fields slow down user data entry and complicate the user interface. Use them sparingly and only when you cannot innovate your way around using them. Custom fields will be applied to all Company/Job records you add them to – in the real world it’s likely only a subset of these records needed your custom field.

In most cases, storing the information in a Note or Photo is much easier, and should be preferred over custom fields unless there is a requirement to store the data in a structured format.

Supported Objects

Custom Fields are supported for the following object types:

  • Job
  • Company

Field Types

You can use any of the following field types when setting new custom fields:

Field TypeDescription
TextA single line textbox. Multiline text and rich text are not supported.
NumericA textbox which only stores numeric values. Do not use Numeric for numbers which aren't used in mathematical operations (e.g. phone numbers, reference numbers) -- use Text instead.
CurrencyUsed for storing currency values. Currency symbol is based on the account's region settings.
DateUsed for storing a date value. Updates to the field value via the API must be in "YYYY-MM-DD" format, but the UI will use the account's preferred date format based on their region settings.
DateTimeUsed for storing a date value with a timestamp. Updates to the field value via the API must be in "YYYY-MM-DD HH:MM:SS" format, but the UI will use the account's preferred date format based on their region settings.
SelectListRenders as a dropdown in the UI, allowing the user to select from predefined options. Updates to field values via the API do not validate that the new value matches a dropdown option.

Reading and Writing Custom Fields

After a Custom Field has been created via the Custom Fields API, you can read and write values for that field via the REST API. The field name specified when creating the custom field will be prefixed with customfield_. So if you create a Custom Field with field_name = favourite_ice_cream, that field will be available on the REST API as customfield_favourite_ice_cream.

How to Use the Custom Fields API

Refer to the Custom Fields API Reference for details of the Custom Fields endpoint.


Did this page help you?