Custom ticket fields let you capture additional structured data on every ticket. The API returns both system fields (e.g. status, priority) and custom fields you create.

The ticket field object

Attribute	Type	Description
id	string	Unique identifier (system fields use system_* prefix)
title	string	Display name
fieldKey	string	Machine-readable key (immutable after creation)
type	string	Field type (immutable after creation)
description	string | null	Field description
position	integer	Display order
active	boolean	Whether the field is active
requiredForAgents	boolean	Required when agents submit tickets
requiredForEndUsers	boolean	Required on end-user forms
visibleToEndUsers	boolean	Shown on end-user forms
editableByEndUsers	boolean	Editable by end users
regexPattern	string | null	Validation regex
defaultValue	string | null	Default value
options	array | null	For dropdown/multiselect types
createdAt	string	Creation time (ISO 8601 UTC)
updatedAt	string	Last update time (ISO 8601 UTC)

Supported field types

text, textarea, number, decimal, checkbox, date, dropdown, multiselect, regex

List ticket fields

GET /helpdesk/api/v1/ticket_fields

Returns system fields (on the first page) followed by custom fields. Supports cursor pagination.

Query parameters

Parameter	Type	Required	Description
active	boolean	no	Filter by active status
page_size	integer	no	Results per page
after	string	no	Cursor for next page
sort_by	string	no	position, title, created_at (default: position)
sort_order	string	no	asc or desc

Response

{
  "ticketFields": [ ... ],
  "meta": { "pageSize": 25, "hasMore": false },
  "links": { "next": null }
}

Retrieve a ticket field

GET /helpdesk/api/v1/ticket_fields/:id

Works for both system and custom fields.

Create a ticket field

POST /helpdesk/api/v1/ticket_fields

Requires admin permission.

Request body

{
  "ticketField": {
    "title": "Region",
    "type": "dropdown",
    "fieldKey": "region",
    "description": "Customer region",
    "requiredForAgents": false,
    "options": [
      { "name": "North America", "value": "na", "default": true },
      { "name": "Europe", "value": "eu", "default": false }
    ]
  }
}

Update a ticket field

PUT /helpdesk/api/v1/ticket_fields/:id

Requires admin permission. The type and fieldKey attributes are immutable and cannot be changed after creation. System fields (system_*) cannot be modified.

Delete a ticket field

DELETE /helpdesk/api/v1/ticket_fields/:id

Requires admin permission. System fields cannot be deleted.

---

Ticket Field Options

Manage individual options for dropdown and multiselect fields without replacing the full list.

The option object

Attribute	Type	Description
id	string	Option identifier (e.g. opt_000)
name	string	Display label
value	string	Machine-readable value (must be unique per field)
default	boolean	Whether this is the default option

List options

GET /helpdesk/api/v1/ticket_fields/:fieldId/options

Response

{
  "customFieldOptions": [ ... ]
}

Retrieve an option

GET /helpdesk/api/v1/ticket_fields/:fieldId/options/:optionId

Create an option

POST /helpdesk/api/v1/ticket_fields/:fieldId/options

Requires admin permission. Maximum of 2000 options per field.

Request body

{
  "customFieldOption": {
    "name": "Asia Pacific",
    "value": "apac",
    "default": false
  }
}

Update an option

PUT /helpdesk/api/v1/ticket_fields/:fieldId/options/:optionId

Requires admin permission.

Delete an option

DELETE /helpdesk/api/v1/ticket_fields/:fieldId/options/:optionId

Requires admin permission. Fails if the option is currently in use on tickets.

Error codes

Code	Status	Description
BAD_REQUEST	400	Missing required request body
IMMUTABLE_FIELD	422	Cannot change type or fieldKey after creation
SYSTEM_FIELD	422	System fields cannot be modified or deleted
INVALID_FIELD_TYPE	422	Options only available for dropdown/multiselect fields
DUPLICATE_OPTION_VALUE	409	An option with this value already exists
TOO_MANY_OPTIONS	422	Maximum of 2000 options per field
OPTION_IN_USE	422	Cannot delete an option that is in use on tickets