Ticket Fields

You can use this API to get system and custom ticket fields. For a list of system fields, see About ticket fields in Help Center.

You can also use the API to create custom ticket fields. See About custom field types in the Zendesk Help Center. New custom ticket fields become available in the Tickets API. See Setting custom field values in Tickets.

When multi-recipient email tickets are enabled, Zendesk adds a system-managed text field with the key standard::multi_recipient_email_tickets. Its value identifies tickets created from the same inbound email and can't be updated through the API. Learn about multi-recipient email tickets.

You can make ticket fields visible on the request form in Help Center for end users. To make a ticket field visible to end users, make it both visible and editable in Help Center. Example:

{  "visible_in_portal": true,  "editable_in_portal": true}

Relationship field types

Two ticket field types create a relationship to another object:

lookup - References a single target record. See Lookup relationships.
multi_lookup - References multiple target records of the same object type, up to max_selections. See About multi-lookup relationship fields.

For a multi_lookup field, visible_in_portal, editable_in_portal, and required_in_portal can be set to true only when relationship_target_type is a custom object.

JSON format

Ticket Fields are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
active	boolean	false	false	Whether this field is available
agent_can_edit	boolean	true	false	Whether this field is editable by agents
agent_description	string	false	false	A description of the ticket field that only agents can see
collapsed_for_agents	boolean	false	false	If true, the field is shown to agents by default. If false, the field is hidden alongside infrequently used fields. Classic interface only
created_at	string	true	false	The time the custom ticket field was created
creator_app_name	string	false	false	Name of the app that created the ticket field, or a null value if no app created the ticket field
creator_user_id	integer	false	false	The id of the user that created the ticket field, or a value of "-1" if an app created the ticket field
custom_field_options	array	false	false	Required and presented for a custom ticket field of type "multiselect" or "tagger"
custom_statuses	array	true	false	List of customized ticket statuses. Only present for a system ticket field of type "custom_status"
description	string	false	false	Describes the purpose of the ticket field to users
editable_in_portal	boolean	false	false	Whether this field is editable by end users in Help Center
id	integer	true	false	Automatically assigned when created
key	string	true	false	A unique key that identifies the ticket field. System-managed fields use a `standard::` prefix.
max_selections	integer	true	false	Present for multi_lookup fields only. The maximum number of target records the field accepts. Defaults to 20
position	integer	false	false	The relative position of the ticket field on a ticket. Note that for accounts with ticket forms, positions are controlled by the different forms
raw_description	string	false	false	The dynamic content placeholder if present, or the `description` value if not. See Dynamic Content
raw_title	string	false	false	The dynamic content placeholder if present, or the `title` value if not. See Dynamic Content
raw_title_in_portal	string	false	false	The dynamic content placeholder if present, or the "title_in_portal" value if not. See Dynamic Content
regexp_for_validation	string	false	false	For "regexp" fields only. The validation pattern for a field value to be deemed valid
relationship_filter	object	false	false	A filter definition that allows your autocomplete to filter down results
relationship_target_type	string	false	false	Present for "lookup" and "multi_lookup" fields. A representation of what type of object the field references. Options are "zen:user", "zen:organization", "zen:ticket", or "zen:custom_object:{key}", where key is a custom object key. For example, "zen:custom_object:apartment".
removable	boolean	true	false	If false, this field is a system field that must be present on all tickets
required	boolean	false	false	If true, agents must enter a value in the field to change the ticket status to solved
required_in_portal	boolean	false	false	If true, end users must enter a value in the field to create the request
sub_type_id	integer	false	false	For system ticket fields of type "priority" and "status". Defaults to 0. A "priority" sub type of 1 removes the "Low" and "Urgent" options. A "status" sub type of 1 adds the "On-Hold" option
system_field_options	array	true	false	Presented for a system ticket field of type "tickettype", "priority" or "status"
tag	string	false	false	For "checkbox" fields only. A tag added to tickets when the checkbox field is selected
title	string	false	true	The title of the ticket field
title_in_portal	string	false	false	The title of the ticket field for end users in Help Center
type	string	false	true	System or custom field type. Editable for custom field types and only on creation. See Create Ticket Field
updated_at	string	true	false	The time the custom ticket field was last updated
url	string	true	false	The URL for this resource
visible_in_portal	boolean	false	false	Whether this field is visible to end users in Help Center

Example

{  "active": true,  "agent_can_edit": true,  "agent_description": "This is the agent only description for the subject field",  "collapsed_for_agents": false,  "created_at": "2009-07-20T22:55:29Z",  "description": "This is the subject field of a ticket",  "editable_in_portal": true,  "id": 34,  "key": null,  "position": 21,  "raw_description": "This is the subject field of a ticket",  "raw_title": "{{dc.my_title}}",  "raw_title_in_portal": "{{dc.my_title_in_portal}}",  "regexp_for_validation": null,  "removable": false,  "required": true,  "required_in_portal": true,  "tag": null,  "title": "Subject",  "title_in_portal": "Subject",  "type": "subject",  "updated_at": "2011-05-05T10:38:52Z",  "url": "https://company.zendesk.com/api/v2/ticket_fields/34",  "visible_in_portal": true}

List Ticket Fields

GET /api/v2/ticket_fields

Returns a list of all system and custom ticket fields in your account.

For end users, only the ticket fields with visible_in_portal set to true are returned.

Cursor pagination returns a maximum of 100 records per page and fields are returned in the order specified by their id.

If the results are not paginated, every field is returned in the response and fields are returned in the order specified by the position.

You can adjust the position of ticket fields by:

Using the Update Ticket Field endpoint
Using the Reorder Ticket Fields endpoint
Ticket Fields page in the Admin Center (Admin Center > Manage > Ticket > Fields > Actions > Edit order)

These adjustments determine the order in which fields are displayed in various locations. For accounts without access to multiple ticket forms, the order will also be used to display field values within tickets. However, for accounts with access to multiple ticket forms, the field order on the ticket page is defined within each form.

Consider caching this resource to use with the Tickets API.

Pagination

Cursor pagination (recommended)
No pagination

See Pagination.

Sideloads

The following sideloads are supported:

Name	Will sideload
users	The user or users that created the ticket field

Allowed For

Anyone

Parameters

Name	Type	In	Required	Description
creator	boolean	Query	false	Displays the `creator_user_id` and `creator_app_name` properties. If the ticket field is created by an app, `creator_app_name` is the name of the app and `creator_user_id` is `-1`. If the ticket field is not created by an app, `creator_app_name` is null
include_boundary_indicators	boolean	Query	false	When true, includes `has_more` indicator in the cursor pagination response meta. Only valid with cursor pagination (page[size], page[after], page[before]).
include_item_cursors	boolean	Query	false	When true, includes cursor values for each item in the cursor pagination response. Only valid with cursor pagination (page[size], page[after], page[before]).
locale	string	Query	false	Forces the `title_in_portal` property to return a dynamic content variant for the specified locale. Only accepts active locale ids. Example: `locale="de"`.
page	object	Query	false	Cursor-based pagination parameters (JSON:API style). Supports nested parameters: - `page[size]` - Number of records per page (default varies by endpoint, typically 100) - `page[after]` - Cursor token to fetch records after this position - `page[before]` - Cursor token to fetch records before this position Example: `?page[size]=50&page[after]=eyJvIjoiaWQiLCJ2IjoiYVFFPSJ9`
sort	string	Query	false	Field to sort results by. Prefix with `-` for descending order. When used with cursor pagination, this determines the cursor ordering. Example: `?sort=name` or `?sort=-created_at`

Limits

This endpoint has its own rate limit that is different from the account wide rate limit. When calls are made to this endpoint, this limit will be consumed and you will get a 429 Too Many Requests response code if the allocation is exhausted.

Headers

API responses include usage limit information in the headers for this endpoint.

Zendesk-RateLimit-ticket-fields-index: total={number}; remaining={number}; resets={number}

Zendesk-RateLimit-ticket-fields-index-deep-pagination: total={number}; remaining={number}; resets={number}

Within this header, “Total” signifies the initial allocation, “Remaining” indicates the remaining allowance for the current interval, and “Resets” denotes the wait time in seconds before the limit refreshes. You can see the Total, and Interval values in the below table.

Details

This is the limit definition for the Index action.

Rate Limits	Scopes	Interval	Sandbox	Trial	Default
Standard	Account	1 minute	40	20	300
With High Volume API Add On	Account	1 minute	40	20	450

"Default" applies to all Zendesk suite and support plans. Please refer to the general account limits for more information.

Tickets

Users

Organizations

Lookup Relationships

Groups

Ticket Management

Business Rules

Account Configuration

OAuth

Apps

Targets

Side Conversation

JIRA

Approvals

Tasks