Custom Fields

Custom fields let you attach structured key-value data to tickets beyond the built-in properties like status, priority, and labels. Use custom fields to capture information specific to your team’s processes — such as cost centers, affected systems, departments, locations. Custom fields are configured per team and apply to all tickets on that team. You can populate them manually, with AI inference, or programmatically through workflows and the public API.

Custom fields live under Settings → Ticket types in the team sidebar. Pick a ticket type (Requests, Tasks, Incidents, etc.) to view and edit the fields it captures.

Supported Field Types

Each custom field has a data type that determines what values it can hold and how it appears in the UI.

Type	Name	Description	Example Value
Text	Office Location	Free-form text	`Building 3, Floor 2`
Number	Cost Estimate	Numeric value	`4200`
Boolean	Requires Approval	Yes or No	`Yes`
Date	Target Completion	Date and time	`2026-03-15 10:30 AM`
Dropdown	Request Area	Single selection from predefined options	`Hardware`
Multi-select	Affected Systems	Multiple selections from predefined options	`Hardware`, `Network`
Item Reference	Affected CI/Asset	Link to an item in your team’s databases, optionally limited to specific item types	`LAPTOP-0042`

Dropdown and multi-select fields are useful when you want consistent, searchable values. AI inference also works with these types — the model picks from your predefined options. Each option can carry a description that tells the model when that option applies.

Creating Custom Fields

Team admins create custom fields in team settings.

Open team settings

Navigate to Settings for your team.

Go to Ticket types

Select the Ticket types section in the team settings sidebar. Custom fields are configured per ticket type inside this page.

Add a new field

Click Add Field and configure the new row:

Field Name: A descriptive name for the field, for example “Cost Center” or “Affected System”
Data type: One of the supported field types
Item type (Item Reference fields only): The item types the field can link to. Select one or more item types to limit the field to those tables, or leave it on Any item type

Define options (Dropdown and Multi-select only)

Click the options button on the row to open the option editor. Each option has a value and a display name. The value is the stored identifier and is fixed once saved. The display name is the label people see, and you can rename it any time.Click the description icon on an option to add an optional description that says when that option applies. On a Request Area field, for example, “Hardware” might carry “Laptops, monitors, docking stations, and other physical equipment, including replacements and repairs.” AI inference reads these descriptions to choose between options, so write them the way you would brief a new agent. Click Done to keep your edits.

Save

Click Save changes to make the field available on tickets.

You can give a field its own description only when you create it from a ticket’s expanded field section. Settings → Ticket types has no field description input, and you can’t edit one after creation. Put guidance for AI inference on the options instead.

Custom fields apply to all tickets on the team. There is no way to limit a field to a subset of tickets.

Setting Values on Tickets

From the Ticket Detail

Select the Fields tab next to Activity. Fields appear in their configured sections, including empty fields marked Not set:

Hover over or focus a field value, then click it to edit. For an empty field, click Not set.
Enter or select a value
Click Save to confirm.

Long text values show a three-line preview. Click the value to open the full text in the editor. On read-only tickets, click show more to read the full value and show less to collapse it. To clear a field value, hover over or focus the field, then click its clear icon. Read-only tickets display field values without editing controls.

The Fields tab displays groups in one column, with text previews capped at three lines. Expand an individual group to focus on its fields.Team admins can expand a section, then click Add field in the expanded editor to create a field.

With AI Inference

Serval can automatically populate custom fields using AI, similar to how AI infers labels. When enabled, the model reads the ticket’s name, description, and conversation history to determine appropriate values. AI inference supports Text, Number, Boolean, Dropdown, and Multi-select field types. For dropdown and multi-select fields, the model picks from your predefined options. It sees each option’s display name and description, so it judges an option with no description by its name alone. When the model sets a value, the ticket activity records the reason it chose that option.

Open team settings

Navigate to Settings for your team.

Go to Ticket types

Select the Ticket types section in the team settings sidebar.

Enable AI inference

Open a ticket type and turn on Set fields with AI in the Custom fields card. The setting applies to every ticket type on the team.

If inference keeps leaving a dropdown empty or picking the wrong option, add or sharpen the option descriptions. The model only sets a field when the ticket clearly indicates a value, and a bare option name like “Confidential” seldom gives it enough to go on.

When enabled, inference runs automatically each time a ticket is created or updated. It only populates fields that do not already have a value — it will not overwrite values set by an agent, workflow, or previous inference run.

AI inference does not support Date fields. If you need dates populated automatically, use a workflow.

With Catalyst

Workflows have built-in actions for reading and writing custom fields. Use Catalyst to describe what you want in natural language, or call the helpers directly in code. Discover available fields — list all custom field definitions for the team:

const options = await serval.common.listCustomFieldOptions({
  teamId: ctx.currentTeam.id,
});

Read current values on a ticket:

const values = await serval.common.getTicketCustomFieldValues({ ticketId });

Set values on a ticket:

await serval.common.setTicketCustomFieldValues({
  ticketId,
  fieldValueInputs: [
    { fieldKey: "cost-center", value: "ENG-042" },
    { fieldKey: "affected-system", value: "Billing" },
  ],
});

With the Public API

You can also set and read custom field values directly via the REST API. Set custom field values:

cURL

curl -X PUT 'https://api.serval.com/v2/tickets/{ticket_id}/custom-field-values' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{
    "field_values": [
      {
        "field_key": "cost-center",
        "value": "ENG-042"
      }
    ]
  }'

Read custom field values:

cURL

curl -X GET 'https://api.serval.com/v2/tickets/{ticket_id}/custom-field-values' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

List available custom field definitions:

cURL

curl -X GET 'https://api.serval.com/v2/teams/{team_id}/custom-field-options' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Create a custom field definition:

cURL

curl -X POST 'https://api.serval.com/v2/teams/{team_id}/custom-field-options' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{
    "ticket_type": "TICKET_TYPE_REQUEST",
    "field_name": "Affected system",
    "data_type": "ENUM",
    "enum_options": [
      {
        "value": "Billing",
        "display_name": "Billing",
        "display_order": 0,
        "description": "Invoices, refunds, or the billing portal"
      },
      { "value": "Okta", "display_name": "Okta", "display_order": 1 }
    ]
  }'

Each ticket type has its own field schema, so a field created on TICKET_TYPE_REQUEST does not exist on TICKET_TYPE_JOURNEY. ENUM and MULTI_SELECT require enum_options; every other data type rejects them. Each option’s description is optional and is what AI inference reads to choose between options. For change tickets, also pass the ticket_subtype whose schema you’re editing.

Creating fields requires the create_custom_field_settings permission. On a scoped API key, grant the ticket-fields:write scope.

Fields are identified by their field_key in the public API.

Filtering by Custom Fields

Custom fields are available as filters in the ticket list:

Click the Filter button
Select a custom field from the filter menu
Choose an operator and value

Filter by ticket type to select only fields that apply to those types. This also distinguishes custom ticket types: a Security Incident field doesn’t apply to another custom type. An is empty filter matches only tickets of a type that uses that field. For dropdown and multi-select fields, you select from the predefined options. For text fields, you enter a search term. For number and date fields, you can use comparison operators (greater than, less than, etc.).

You can remove individual options from a Dropdown or Multi-select field. In Settings → Ticket types, expand the ticket type, open the field’s option editor, delete the options you no longer need, and save. Serval asks you to confirm before saving, because removing an option can’t be undone from the UI. Re-adding the same value later creates a new option rather than restoring the old one. Tickets that already use a removed option keep their current value. The option simply can’t be selected again. A field must always keep at least one option, so you can’t remove them all.

Hiding fields

You can hide a custom field from views without deprecating it. A hidden field stays fully readable and writable (workflows, AI, and the public API still use it), but is hidden from list columns, filters, sorting, grouping, and journey and queue views. On tickets, find it in the expandable hidden-fields disclosure. From Settings → Ticket types, open the field’s overflow menu and choose Hide from views (it gets a Hidden badge); choose Show in views to bring it back. Saved views that referenced the field keep working, and deprecation takes precedence: a field that’s both deprecated and hidden shows only in the deprecated section.

Deprecating and Restoring Fields

If a custom field is no longer needed, you can deprecate. Deprecating a field:

Hides it from new edits on tickets — agents can no longer set or change its value
Preserves all existing data — tickets that already have a value for the field retain it

To deprecate a field, go to Settings → Ticket types, expand the ticket type the field belongs to, and click the remove option on the field. To restore a deprecated field and make it editable again, find it in the deprecated section and click Restore.

Deprecation is reversible. If you change your mind or need the field again later, restoring it brings back full editing capability with all historical data intact.

You can’t restore a deprecated field while an active field on the same ticket type has its name. Rename or deprecate the active field first.

Changing a Field’s Data Type

A field’s data type can’t be changed once it’s saved. Workflows, views, and dashboards that use the field rely on its type, and existing ticket values can’t always be converted. To use a different type, deprecate the field and create a new one with the same name and the new type. Tickets that already have a value keep it on the deprecated field, and new values go to the new field. Update any workflows, views, or dashboards that used the old field to use the new one.

Overview

End User

Platform

Administration

Help Desk

Ticketing

Catalyst

Workflows

Forms

Skills

Knowledge Base

Databases

Access Management

Journeys

Suggestions

Campaigns

Team Solutions

CLI

Self-Hosting

Supported Field Types

Creating Custom Fields

Setting Values on Tickets

From the Ticket Detail

With AI Inference

With Catalyst

With the Public API

Filtering by Custom Fields

Hiding fields

Deprecating and Restoring Fields

Changing a Field’s Data Type

​Supported Field Types

​Creating Custom Fields

​Setting Values on Tickets

​From the Ticket Detail

​With AI Inference

​With Catalyst

​With the Public API

​Filtering by Custom Fields

​Removing Dropdown Options

​Hiding fields

​Deprecating and Restoring Fields

​Changing a Field’s Data Type

Supported Field Types

Creating Custom Fields

Setting Values on Tickets

From the Ticket Detail

With AI Inference

With Catalyst

With the Public API

Filtering by Custom Fields

Removing Dropdown Options

Hiding fields

Deprecating and Restoring Fields

Changing a Field’s Data Type