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 Support Help Center. New custom ticket fields become available in the Tickets API. See Setting custom field values in 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,
...

JSON Format

Custom and system ticket fields have the following properties.

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned when created
url string yes no The URL for this resource
type string no* yes System or custom field type. *Editable for custom field types and only on creation. See Create Ticket Field
title string no yes The title of the ticket field
raw_title string no no The dynamic content placeholder if present, or the "title" value if not. See Dynamic Content
description string no no Describes the purpose of the ticket field to users
raw_description string no no The dynamic content placeholder if present, or the "description" value if not. See Dynamic Content
position integer no no The relative position of the ticket field on a ticket. Note that for accounts without ticket forms, positions 0 to 7 are reserved for system fields
active boolean no no Whether this field is available
required boolean no no If true, agents must enter a value in the field to change the ticket status to solved
collapsed_for_agents boolean no no If true, the field is shown to agents by default. If false, the field is hidden alongside infrequently used fields. Classic interface only
regexp_for_validation string no no For "regexp" fields only. The validation pattern for a field value to be deemed valid
title_in_portal string no no The title of the ticket field is mandatory when the field is visible to end users in Help Center
raw_title_in_portal string no no The dynamic content placeholder if present, or the "title_in_portal" value if not. See Dynamic Content
visible_in_portal boolean no no Whether this field is visible to end users in Help Center
editable_in_portal boolean no no Whether this field is editable by end users in Help Center
required_in_portal boolean no no If true, end users must enter a value in the field to create the request
tag string no no For "checkbox" fields only. A tag added to tickets when the checkbox field is selected
created_at date yes no The time the custom ticket field was created
updated_at date yes no The time the custom ticket field was last updated
system_field_options array yes no Presented for a system ticket field of type "tickettype", "priority" or "status"
custom_field_options array no yes Required and presented for a custom ticket field of type "multiselect" or "tagger"
sub_type_id integer no no 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
removable boolean yes no If false, this field is a system field that must be present on all tickets
agent_description string no no A description of the ticket field that only agents can see
Example
{
  "id":                    34,
  "url":                   "https://company.zendesk.com/api/v2/ticket_fields/34.json",
  "type":                  "subject",
  "title":                 "Subject",
  "raw_title":             "{{dc.my_title}}",
  "description":           "This is the subject field of a ticket",
  "raw_description":       "This is the subject field of a ticket",
  "position":              21,
  "active":                true,
  "required":              true,
  "collapsed_for_agents":  false,
  "regexp_for_validation": null,
  "title_in_portal":       "Subject",
  "raw_title_in_portal":   "{{dc.my_title_in_portal}}",
  "visible_in_portal":     true,
  "editable_in_portal":    true,
  "required_in_portal":    true,
  "tag":                   null,
  "created_at":            "2009-07-20T22:55:29Z",
  "updated_at":            "2011-05-05T10:38:52Z",
  "removable":             false
  "agent_description":     "This is the agent only description for the subject field"
}

List Ticket Fields

GET /api/v2/ticket_fields.json

Returns a list of all system and custom ticket fields in your account. Fields are returned in the order specified on the Ticket Fields page in Zendesk Support (Admin > Manage > Ticket Fields). Consider caching this resource to use with the Tickets API.

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/ticket_fields.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

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

Show Ticket Field

GET /api/v2/ticket_fields/{id}.json

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{id}.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

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

Create Ticket Field

POST /api/v2/ticket_fields.json

Creates any of the following custom field types:

  • text (default when no "type" is specified)
  • textarea
  • checkbox
  • date
  • integer
  • decimal
  • regexp
  • multiselect (multi-select dropdown menu)
  • tagger (single-select dropdown menu)

See About custom field types in the Zendesk Support Help Center.

Allowed For
  • Admins
Field limits
  • 400 ticket fields per account if your account doesn't have ticket forms
  • 400 ticket fields per ticket form if your account has ticket forms
Using curl
curl https://{subdomain}.zendesk.com/api/v2/ticket_fields.json \
  -d '{"ticket_field": {"type": "text", "title": "Age"}}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}
Example Response
Status: 201 Created

{
  "ticket_field": {
    "id":                    89,
    "url":                   "https://company.zendesk.com/api/v2/ticket_fields/89.json",
    "type":                  "text",
    "title":                 "Age",
    "raw_title":             "Age",
    "description":           "Age",
    "raw_description":       "Age",
    "position":              9999,
    "active":                true,
    "required":              true,
    "collapsed_for_agents":  false,
    "regexp_for_validation": null,
    "title_in_portal":       "Age",
    "raw_title_in_portal":   "Age",
    "visible_in_portal":     false,
    "editable_in_portal":    false,
    "required_in_portal":    false,
    "tag":                   null,
    "agent_description":     "Agent only description"
    "created_at":            "2012-04-02T22:55:29Z",
    "updated_at":            "2012-04-02T22:55:29Z"
  }
}

Update Ticket Field

PUT /api/v2/ticket_fields/{id}.json

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{id}.json \
  -d '{ "ticket_field": { "title": "Your age" }}' \
  -H "Content-Type: application/json" -X PUT \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "ticket_field": {
    "id":                    89,
    "url":                   "https://company.zendesk.com/api/v2/ticket_fields/89.json",
    "type":                  "text",
    "title":                 "Your age",
    "raw_title":             "Your age",
    "description":           "Your age",
    "raw_description":       "Your age",
    "position":              9999,
    "active":                true,
    "required":              true,
    "collapsed_for_agents":  false,
    "regexp_for_validation": null,
    "title_in_portal":       "Your age",
    "raw_title_in_portal":   "Your age",
    "visible_in_portal":     false,
    "editable_in_portal":    false,
    "required_in_portal":    false,
    "tag":                   null,
    "agent_description":     "Agent only description"
    "created_at":            "2012-04-02T22:55:29Z",
    "updated_at":            "2012-04-02T23:11:23Z"
  }
}

Updating drop-down field options

You can also use the update endpoint to add, update, or remove options in a drop-down custom field. Updating field options for multi-select fields works exactly the same as drop-down field options.

Important: Unless you want to remove some options, you must specify all existing options in any update request. Omitting an option removes it from the drop-down field, which removes its values from any tickets or macros.

Use the custom_field_options attribute to update the options. The attribute consists of an array of option objects, with each object consisting of a name and value property. The properties correspond to the "Title" and "Tag" text boxes in the admin interface. Example request body:

{
  "custom_field_options": [
    {"name": "Apple Pie", "value": "apple"},
    {"name": "Pecan Pie", "value": "pecan"}
  ]
}
Using curl
curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{id}.json \
  -d '{"ticket_field": {"custom_field_options": [{"name": "Apple Pie", "value": "apple"}, {"name": "Pecan Pie", "value": "pecan"}]}}' \
  -H "Content-Type: application/json" -X PUT \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "ticket_field": {
    "id":21938362,
    "type":"tagger",
    "title":"Pies",
    ...
    "custom_field_options": [
      {
        "id":21029772,
        "name":"Apple Pie",
        "raw_name":"Apple Pie",
        "value":"apple",
        "default":false
      },
      ...
    ]
  }
}

Delete Ticket Field

DELETE /api/v2/ticket_fields/{id}.json

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{id}.json \
  -v -u {email_address}:{password} -X DELETE
Example Response
Status: 204 No Content

List Ticket Field Options

GET /api/v2/ticket_fields/{field_id}/options.json

Returns a list of all custom ticket field options for the given dropdown ticket field.

Allowed For
  • Agents
Stability
  • Beta
Using curl
curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{field_id}/options.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
    "count": 2,
    "custom_field_options": [
        {
            "id": 10000,
            "name": "Apples",
            "position": 0,
            "raw_name": "Apples",
            "url": "http://{subdomain}.zendesk.com/api/v2/ticket_fields/1/options/10000.json",
            "value": "apple"
        },
        {
            "id": 10001,
            "name": "Bananas",
            "position": 1,
            "raw_name": "Bananas",
            "url": "http://{subdomain}.zendesk.com/api/v2/ticket_fields/1/options/10001.json",
            "value": "banana"
        }
     ],
     "next_page": null,
     "previous_page": null
}

Show Ticket Field Option

GET /api/v2/ticket_fields/{field_id}/options/{id}.json

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{field_id}/options/{id}.json \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
    "custom_field_option": {
        "id": 10001,
        "name": "Bananas",
        "position": 1,
        "raw_name": "Bananas",
        "url": "http://{subdomain}.zendesk.com/api/v2/ticket_fields/1/options/10001.json",
        "value": "banana"
    }
}

Create or Update Ticket Field Option

POST /api/v2/ticket_fields/{field_id}/options.json

Creates or updates an option for the given dropdown ticket field.

To update an option, include the id of the option in the "custom_field_option" object. Example:

{"custom_field_option": {"id": 10002, "name": "Pineapples", ... }

If an option exists for the given ID, the option will be updated. Otherwise, a new option will be created.

Allowed For
  • Admins
Using curl (Create)
curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{field_id}/options.json \
  -d '{"custom_field_option": {"name": "Grapes", "position": 2, "value": "grape"}}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}
Example Response
Status: 201 Created

{
    "custom_field_option": {
        "id": 10002,
        "name": "Grapes",
        "position": 2,
        "raw_name": "Grapes",
        "url": "http://{subdomain}.zendesk.com/api/v2/ticket_fields/1/options/10002.json",
        "value": "grape"
    }
}
Using curl (Update)
curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{field_id}/options.json \
  -d '{"custom_field_option": {"id": 10002, "name": "Pineapples", "position": 2, "value": "pineapple"}}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
    "custom_field_option": {
        "id": 10002,
        "name": "Pineapples",
        "position": 2,
        "raw_name": "Pineapples",
        "url": "http://{subdomain}.zendesk.com/api/v2/ticket_fields/1/options/10002.json",
        "value": "pineapple"
    }
}

Delete Ticket Field Option

DELETE /api/v2/ticket_fields/{field_id}/options/{id}.json

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{field_id}/options/{id}.json \
  -v -u {email_address}:{password} -X DELETE
Example Response
Status: 204 No Content