Overview
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 Type | Description |
|---|---|
| Text | A single line textbox. Multiline text and rich text are not supported. |
| Numeric | A 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. |
| Currency | Used for storing currency values. Currency symbol is based on the account's region settings. |
| Date | Used 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. |
| DateTime | Used 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. |
| SelectList | Renders 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.
Updated almost 6 years ago