Custom Fields - Serval Documentation

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`

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.

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, choose the ticket type the field belongs to, and configure:

Name — A descriptive name for the field (e.g., “Cost Center”, “Affected System”)
Type — Choose a data type from the list above
Description — Explain the field’s purpose so agents know when and how to use it
For Dropdown or Multi-select types, define the list of options

Save

Click Save to make the field available on tickets.

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

Open a ticket and find the Custom Fields section in the right panel:

Click the field you want to populate
Enter or select a value
For dropdown, boolean, and multi-select fields, the value saves automatically. For text, number, and date fields, click Save to confirm.

To clear a field value, use the clear option in the field editor.

You can also create new custom fields directly from the ticket detail panel without navigating to team settings.

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.

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

Toggle AI Custom Field Inference 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 the Workflow Builder

Workflows have built-in actions for reading and writing custom fields. Use the workflow builder 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'

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

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.

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
Keeps the field visible in the ticket detail panel, marked as deprecated

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.

​Supported Field Types

​Creating Custom Fields

​Setting Values on Tickets

​From the Ticket Detail

​With AI Inference

​With the Workflow Builder

​With the Public API

​Filtering by Custom Fields

​Removing Dropdown Options

​Deprecating and Restoring Fields

Supported Field Types

Creating Custom Fields

Setting Values on Tickets

From the Ticket Detail

With AI Inference

With the Workflow Builder

With the Public API

Filtering by Custom Fields

Removing Dropdown Options

Deprecating and Restoring Fields