--- updatedAt: 2025-05-12T21:57:48.000Z agentTools: projectIndex: https://developer.servicem8.com/llms.txt --- # List Custom Fields # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "version": "1.0.0", "title": "Custom Fields API", "description": "Custom fields allow you to add additional fields to the standard database schema per account.\nFor ServiceM8 apps, custom fields are commonly used for:\n* Collecting additional job or client information\n* Used in conjunction with Web Hooks to trigger workflows\n\n## When to Use Custom Fields\nOur 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.\n\nThe solution is to use badge custom fields, badge custom fields allow the user to ‘activate’ custom fields on a per record basis by activating a badge. For example, if you would like to track additional vehicle data (such an make, model, colour), you could add custom fields to every job in the system – even though not every job would be related to a vehicle, or you can create a ‘vehicle’ custom badge, and then attach make, model and colour to the custom badge.\n\nWhen users activate the vehicle badge on a job, your custom fields are immediately displayed, enabling the user to store the required data without compromising every future job entered.\n\n## Supported Objects\nCustom Fields are supported for the following object types:\n* Job\n* Company\n* Badge\n\n\n\n## Field Types\nYou can use any of the following field types when setting new custom fields:\n\n| Field Type | Description |\n|------------|-------------|\n| Text | A single line textbox. Multiline text and rich text are not supported. |\n| 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. |\n| Currency | Used for storing currency values. Currency symbol is based on the account's region settings. |\n| 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. |\n| 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. |\n| 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. |\n\n## Reading and Writing Custom Fields\nAfter a Custom Field has been created via the Custom Fields API, you can read and write values for that\nfield via the [REST API](/docs/overview-1). The field name specified when creating the custom field will\nbe prefixed with `customfield_`. So if you create a Custom Field with `field_name` = `favourite_ice_cream`,\nthat field will be available on the REST API as `customfield_favourite_ice_cream`.\n" }, "paths": { "/custom_fields_1.0": { "get": { "operationId": "get_custom_fields", "summary": "List Custom Fields", "tags": [ "Custom Fields" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomField" } }, "examples": { "response": { "value": [ { "uuid": "679f7069-97b0-4051-9c8e-f3bef1f3ab5b", "object": "job", "display_name": "Favourite Ice Cream", "field_name": "favourite_ice_cream", "field_type": "Text", "is_unique": 0, "sort_priority": 50, "max_length": 50 }, { "uuid": "ab9bee8d-ab3e-4381-8025-89c9506aa6db", "object": "job", "display_name": "Favourite Colour", "field_name": "favourite_colour", "field_type": "SelectList", "select_list_items": [ "Blue", "Green", "Red", "Other" ], "is_unique": 0, "sort_priority": 50, "max_length": 50 } ] } } } } } } } } }, "servers": [ { "url": "https://api.servicem8.com" } ], "components": { "schemas": { "CustomField": { "type": "object", "required": [ "object_name", "field_name", "display_name", "field_type" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Unique identifier for this Custom Field. Required if updating an existing Custom Field." }, "object_name": { "type": "string", "enum": [ "Job", "Company", "Badge" ], "description": "Indicates the object type that this custom field applies to." }, "object_uuid": { "type": "string", "format": "uuid", "description": "Indicates the object uuid when specifying a Badge custom field. Required when object type is Badge, not required otherwise." }, "field_name": { "type": "string", "description": "Indicates the field name to represent this custom field. This will become available via the REST API for GET/POST requests for the given account." }, "display_name": { "type": "string", "description": "The name of the custom field displayed to users." }, "is_unique": { "type": "boolean", "description": "True if values entered into this Custom Field should be enforced as unique between different records." }, "max_length": { "type": "integer", "description": "The maximum length of this field.", "minimum": 1, "maximum": 2000 }, "sort_priority": { "type": "integer", "description": "Controls the order of this custom field, as a percentage against other custom fields.", "minimum": 0, "maximum": 100 }, "field_type": { "type": "string", "description": "The type of input data this custom field will accept. See Field Types for options.", "enum": [ "Text", "Numeric", "Currency", "Date", "DateTime", "SelectList" ] }, "select_list_items": { "type": "array", "items": { "type": "string" }, "description": "An array of user visible select list options to select from for use with the field type SelectList. Required when field type is SelectList, not required otherwise." } } } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ```