> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Fields

> Add structured data to tickets with 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.

<Note>
  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.
</Note>

***

## 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` |

<Tip>
  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.
</Tip>

***

## Creating Custom Fields

Team admins create custom fields in team settings.

<Steps>
  <Step title="Open team settings">
    Navigate to **Settings** for your team.
  </Step>

  <Step title="Go to Ticket types">
    Select the **Ticket types** section in the team settings sidebar. Custom fields are configured per ticket type inside this page.
  </Step>

  <Step title="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
  </Step>

  <Step title="Save">
    Click **Save** to make the field available on tickets.
  </Step>
</Steps>

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

***

## 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.

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

### 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.

<Steps>
  <Step title="Open team settings">
    Navigate to **Settings** for your team.
  </Step>

  <Step title="Go to Ticket types">
    Select the **Ticket types** section in the team settings sidebar.
  </Step>

  <Step title="Enable AI inference">
    Toggle **AI Custom Field Inference** on.
  </Step>
</Steps>

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.

<Note>
  AI inference does not support **Date** fields. If you need dates populated automatically, use a workflow.
</Note>

### 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:

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

**Read current values** on a ticket:

```typescript theme={null}
const values = await serval.common.getTicketCustomFieldValues({ ticketId });
```

**Set values** on a ticket:

```typescript theme={null}
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:**

```bash cURL theme={null}
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:**

```bash cURL theme={null}
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:**

```bash cURL theme={null}
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.).

***

## Removing Dropdown Options

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**.

<Tip>
  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.
</Tip>