Custom Fields

Custom fields let you add structured data to tickets beyond the default properties. Track order numbers, product types, priority scores, or any other information relevant to your workflow.

Field Types

Keva supports 9 field types:

Creating Custom Fields

Navigate to Settings

Go to Settings → Custom Fields

Add a Field

1. Click Add Field
2. Configure the field:
   • Name: Display name (e.g., "Order ID")
   • Type: Select field type
   • Required: Whether agents must fill it
   • Description: Help text for agents

Configure Options (Select/Multi-select)

For select fields, add options:

1. Click Add Option
2. Enter option label
3. Optionally set a color
4. Repeat for all options

Save

Click Create Field to save.

The request boundary accepts exactly the nine field types shown above. Names are non-empty, keys use the existing lowercase snake_case form and are limited to 50 characters, workspace IDs are UUIDs or null, and option entries use string value/label fields with an optional string color. Boolean and integer metadata keeps its JSON type; unknown top-level members are ignored. These are source/request-shape boundaries only: value lengths, option counts, min/max ordering, terminal-status closure, configured database concurrency, and edge policy remain separate open decisions.

The complete definition-creation JSON request body is limited to 1 MiB (1,048,576 bytes). Requests over this limit return 413 Payload Too Large. Malformed JSON and non-object JSON bodies are rejected before workspace, duplicate-key, or database transaction work.

Using Custom Fields

On Ticket Detail

Custom fields appear in the ticket sidebar:

1. Open a ticket
2. Find Custom Fields section
3. Click a field to edit
4. Enter/select value
5. Changes save automatically

In Filters

Custom fields are not currently available as inbox list filters. Custom fields can be viewed and edited on an individual ticket detail page. Open a ticket and use the Custom Fields section.

In Search

Custom field values are not currently searchable from the inbox. The authenticated dashboard API exposes custom field values for a specific ticket. See the API Access section below for the authenticated read and update routes.

Field Validation

Required Fields

If a field is marked required:

• Ticket creation rejects a missing or empty value.
• Non-empty ticket-value updates use the field-type validator; null currently clears a value without a status-aware guard.
• Closure enforcement is not implemented yet. The terminal-status policy (whether this applies to closed only or also solved/resolved) remains an open product decision, so Keva does not claim that required fields currently block terminal status changes.

Type Validation

Each field type enforces validation:

• Number: Must be numeric
• Email: Must be valid email format
• URL: Must be valid URL
• Date: Must be valid date

Examples

E-commerce Support

SaaS Support

Technical Support

Managing Fields

Edit a Field

1. Go to Settings → Custom Fields
2. Click the field to edit
3. Make changes
4. Save

The complete definition-update JSON request body is limited to 1 MiB (1,048,576 bytes). Requests over this limit return 413 Payload Too Large. The field key and field type remain immutable after creation.

Reorder Fields

Drag and drop fields to change display order.

Archive a Field

Instead of deleting:

1. Click field settings
2. Select Archive
3. Field hidden but data preserved

Delete a Field

1. Click field settings
2. Select Delete
3. Confirm deletion

API Access

Custom field values are available via API:

# Read ticket custom fields in the authenticated dashboard
GET /api/tickets/{id}/custom-fields

# Update ticket custom fields in the authenticated dashboard
PATCH /api/tickets/{id}/custom-fields
 
{"values":{"order_id":"ORD-12345","category":"billing"}}

The public v1 ticket API currently exposes standard ticket fields only; it does not expose a /api/v1/tickets/{id}/custom-fields route.

The authenticated in-product ticket editor sends updates to PATCH /api/tickets/{id}/custom-fields as a {"values": {...}} JSON object. The values member must be an object keyed by UUID field IDs; arrays, null, and malformed field IDs are rejected before the mutation helper. Unknown envelope members are ignored, an empty object remains a successful no-op, and null still clears a value. Keva admits that body only after the caller has both ticket-edit and custom-field-edit access, the exact ticket is in the tenant, and the caller is a member of its workspace. The complete request body is limited to 1 MiB; larger declared or streamed payloads return 413. An empty values object is a successful no-op, null clears a field, and invalid or unavailable fields can be rejected individually while other valid fields are applied.

Full API documentation →

Permissions

Custom field management requires:

• View: Any team member
• Edit values: Agent or above
• Create/Edit fields: Admin only
• Delete fields: Admin only