Custom Fields¶

Custom fields add your own properties to a project's tickets, such as "Browser", "Operating system" or "Customer". They belong to a single project and are managed under Project Settings → Custom Fields (/{project}/settings/custom_fields), which needs the project_settings permission.

Field options¶

Option	Description
Name	Label shown on tickets and forms. Required
Slug	Identifier used in filters, sorting and the API. Required, see Slugs
Type	text, select or integer, see Field types
Values	For select fields: the allowed options, one per line. Required for select
Multiple	For select fields: allow more than one option to be chosen
Default value	Pre-filled value
Regex	Pattern the value must match. Required for text and integer
Min length / Max length	Length limits for text and integer. 0 disables a limit. Left blank, min is 0 and max is 255
Required	Ticket can't be saved without a value
Ticket types	The ticket types the field applies to, or all types

Field types¶

Text : Free text. The value must match the regex and the length limits. The default regex for a new field is ^(.*)$, which accepts anything.

Integer : A number. Validated the same as text (regex and length) and must also be numeric. Values are returned as integers in the API.

Select : A choice from a fixed list. The value must be one of the lines in Values. With Multiple enabled, every selected value must be in the list.

Slugs¶

The slug must:

• start with a letter
• contain only letters, numbers and underscores
• be unique within the project

Pick a slug that doesn't match a built-in ticket filter such as status, type, milestone, owner or summary, since filters and sorting look the slug up by name.

Limiting a field to ticket types¶

Choose which ticket types a field applies to, or select All to apply it to every type. Values are only validated and saved for tickets of a matching type, and Required is only enforced for those tickets. A "Browser" field might only make sense for Defect, for example.

Using custom fields¶

Filtering tickets¶

Use the slug as a query parameter on the ticket list:

/{project}/tickets?browser=Firefox
/{project}/tickets?browser=Firefox,Chrome
/{project}/tickets?browser=!Safari

• Matching is a "contains" search, not an exact match.
• Use * as a wildcard.
• Separate several values with commas (any match) and prefix with ! to exclude.

See Ticket Properties for the other built-in filters.

Sorting¶

Pass the slug to order_by, e.g. ?order_by=browser.asc.

API¶

Custom field definitions are available from GET /api/{project}/custom-fields. Each ticket in the ticket list includes its custom field values under the field's slug.

When creating or updating a ticket, send values keyed by the field ID (not the slug):

custom_fields[3]=Firefox
custom_fields[4][]=Windows&custom_fields[4][]=Linux   # multiple select

A value that fails validation, or a missing required value, makes the request fail with an error for that field.

Notes¶

Custom fields are per project. To use the same field in another project, create it again there.