Skip to main content
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.

​
Supported Field Types

Each custom field has a data type that determines what values it can hold and how it appears in the UI.
TypeNameDescriptionExample Value
TextOffice LocationFree-form textBuilding 3, Floor 2
NumberCost EstimateNumeric value4200
BooleanRequires ApprovalYes or NoYes
DateTarget CompletionDate and time2026-03-15 10:30 AM
DropdownRequest AreaSingle selection from predefined optionsHardware
Multi-selectAffected SystemsMultiple selections from predefined optionsHardware, 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.
1

Open team settings

Navigate to Settings for your team.
2

Go to Custom Fields

Select the Custom Fields section.
3

Add a new field

Click Add Field 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
4

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:
  1. Click the field you want to populate
  2. Enter or select a value
  3. 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.
1

Open team settings

Navigate to Settings for your team.
2

Go to Custom Fields

Select the Custom Fields section.
3

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:
  1. Click the Filter button
  2. Select a custom field from the filter menu
  3. 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.).

​
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 → Custom Fields 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.