Skip to content

Custom fields

Enterprise feature (new in 1.20.6, helpdesk). See the Helpdesk overview.

A ticket has a priority, a team, an owner, a category and tags. A custom field is anything else your teams need to record on a ticket: a device type, an order number, a location, a date something is promised for.

A desk admin creates the fields and assigns each one to the teams that need it. Every ticket of those teams shows the field in its side panel, and agents fill it in there.

Until you add a field, tickets look exactly as they always have.

Desk settings → Forms and fields → Custom fields lists the fields. It needs the desk capability Helpdesk settings (Admins, out of the box).

New field opens the editor:

  • Label: what agents see beside the field, such as “Device type”.
  • Kind: one of the kinds below.
  • Help line (optional): one sentence shown where the field is filled in.
  • Options: for a “Pick one” field, the choices. Each can carry a short hint.
  • Teams: All teams, or Chosen teams and one or more teams.
  • Who sees it: Agent only or Public (see Agent only and Public).
Kind What an agent enters
Short text One line, up to 500 characters.
Long text Several lines.
Pick one One of the field’s options.
Yes / no Yes, No, or nothing yet.
Date A calendar day.
Date and time A day and a time of day, as the clock reads it.
Number A number.
A person Someone with an account in the workspace.

These are the same kinds a request type’s form and a Before you solve closing field use.

Each field has a key, made from its label when you create it (“Device type” becomes device_type). The editor shows it as you type. The key is unique and never changes, even when you rename the field, so the API, webhooks and the Claude connector can rely on it.

Each row shows the field’s label, Public or Agent only, its kind and options, its teams, its key and how many tickets hold a value for it. From the row you can:

  • Move up and Move down: tickets list the fields in this order.
  • Edit: change the label, help line, options, teams or who sees it.
  • Archive: see Archiving and deleting.
  • Delete.
  • Renaming a field or an option changes what people read. Values stay.
  • Removing an option from a “Pick one” field: tickets that chose it still show it. It can’t be chosen again.
  • The kind can change freely while no ticket holds a value. After that it can only change between Short text and Long text. To change it further, archive the field and add a new one.
  • Changing the teams takes effect at once: tickets of a team you remove stop showing the field (their values are kept), and tickets of a team you add show it.

A ticket whose team has fields shows a Custom fields card in the side panel, under the properties. Each field is edited in place:

  • Pick one and Yes / no open a menu. None clears the value.
  • Short text, Number, Date and Date and time open a small box to type in. Saving it empty clears the value.
  • Long text reads under its label, with a pencil to edit it.
  • A person opens a people picker.

Anyone who can work the ticket can fill in its custom fields, the same as its category and tags. Each change leaves a line on the ticket’s timeline (“Ana set Device type to Laptop”), which only agents see.

A ticket with no team shows only the fields set to All teams.

The filled-in fields are printed with the ticket’s details when you print it or save it as a PDF.

When a ticket moves to another team it shows that team’s fields.

Values already filled in are kept. A field that isn’t assigned to the new team is simply not shown. If the ticket comes back, or you assign the field to the new team too, the value is there again.

  • Agent only: only agents see the field. It never reaches the requester: not on their request, not in any email, not in the customer portal, and not in their personal data export.
  • Public: agents and requesters see it. Once it has a value, the requester sees it, read-only, in a Details card on their request in Get help and in the customer portal. An empty Public field is not shown to them.

Only agents fill in custom fields. Requesters can’t edit them.

In the ticket’s side panel, a Public field has an eye beside its label, so agents know the requester will see what they enter.

Things worth knowing:

  • Switching a field from Public to Agent only hides it from requesters at once. Nothing is left behind in their conversation, because the timeline lines of custom fields are always agents-only.
  • The customer portal doesn’t show A person fields, as it never shows a colleague’s full name to a customer.
  • Requester emails don’t carry custom fields, Public or not.

Requiring a field before a ticket is solved

Section titled “Requiring a field before a ticket is solved”

A Before you solve requirement set can require a custom field. On the set’s page, under On the ticket, pick it from A custom field. It joins the list as “A custom field: Device type”.

When an agent solves a ticket whose field is still empty, the Before you solve dialog asks for it, and saves it with the solve. A field that isn’t assigned to the ticket’s team, or is archived, is not asked for.

  • Archive takes a field off every ticket and out of the Before you solve dialog. Its values are kept. It moves to the Archived list; Restore brings it back, with every value.
  • Delete removes the field and every ticket’s value for it. It asks first and says how many tickets hold a value. Deleting can’t be undone. A requirement set that required the field stops requiring it.

A deleted team drops out of its fields. A field whose teams are all gone is shown on no ticket until you give it a team.

From 1.20.8 the queue’s Filter dialog has a Custom fields block. Choose Add a custom field…, pick a field, then a condition that fits its kind:

Kind Conditions
Pick one is any of: tick one or more options, and Not filled in if you want those too
Yes / no is Yes, is No, is not filled in
Short text, Long text contains (any case), is empty, is not empty
Number equals, is at least, is at most, is empty
Date, Date and time is on, is before, is after, is empty. A date and time is compared by its day, as entered (the workspace’s time zone)
A person is (pick the person), is empty
  • Add up to 10 fields, one condition each. Every condition must match, together with the dialog’s other filters.
  • Teams. A field only has a value on the teams it is for. A condition never matches a ticket of another team, even one that kept a value from before it moved. Not filled in and is empty count only tickets of the field’s teams (every ticket, those with no team too, for an All teams field).
  • The list shows each condition as a chip under the Filtered line, such as Device type: Laptop, Phone. The chip’s × removes that condition.
  • Save view keeps the conditions with the view. See Saved views and filters.
  • Archived fields are not offered for new conditions. A saved view that already uses one keeps working, and its Filter dialog marks the field “(archived)”. A view whose field was deleted shows “This field was deleted” in its Filter dialog; remove the condition to show the list again.
  • Export CSV gives each live custom field a column of its own.

The API, webhooks and the Claude connector

Section titled “The API, webhooks and the Claude connector”
  • REST API: GET /tickets/{number} carries custom_fields, and PATCH /tickets/{number} sets them. GET /custom-fields lists the fields. From 1.20.8, GET /tickets filters by them with cf.<key>=<condition> (Filtering by a custom field), and hd_queue takes the same conditions as custom_fields. See API tokens and webhooks.
  • Webhooks: the ticket in every delivery carries custom_fields, and ticket.updated lists custom_fields in changes when one changed.
  • Claude connector: hd_read_ticket lists the ticket’s fields with their keys, kinds, options and values (custom_fields). hd_update_ticket takes custom_fields. The requester’s hd_read_request shows only Public fields that have a value.

Integrations that act as an agent read agent-only fields too, as an agent does.

Anonymizing a ticket removes the values that are free text or name a person (Short text, Long text, A person). Choices, numbers, dates and yes / no answers stay. Deleting a ticket deletes its values.

  • Requesters can’t fill in custom fields, and request forms don’t feed them.
  • Reports can’t be split by a custom field, and the queue’s list has no custom field column (filter by it, or export the list as CSV).
What Limit
Custom fields, archived ones included 100
Options in one “Pick one” field 50
Teams one field names 100 (or All teams)
A label 80 characters
A help line 500 characters

A change to a field takes effect at once on the server that saved it, and within 30 seconds on any other.

There is nothing to do. No fields exist until you add one, and tickets, requests and integrations work as before. 1.20.8 (filtering and Export CSV) adds no table or column, and saved views made before it work as they did.

Action Shown as
helpdesk.custom_field.created Created a helpdesk custom field
helpdesk.custom_field.updated Changed a helpdesk custom field (records what changed)
helpdesk.custom_field.archived Archived a helpdesk custom field
helpdesk.custom_field.restored Restored a helpdesk custom field
helpdesk.custom_field.reordered Reordered the helpdesk custom fields
helpdesk.custom_field.deleted Deleted a helpdesk custom field (records how many tickets held a value)