Ticket Fields

Zendesk Support allows admins to customize the fields displayed on the ticket form. Basic text fields as well as customizable dropdown and number fields are available. You can customize The visibility of these fields for end users in the admin interface. See About ticket fields in the Zendesk Support Help Center.

JSON Format

Ticket fields have the following attributes

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned upon creation
url string yes no The URL for this resource
type string no* yes The type of the ticket field: "checkbox", "date", "decimal", "integer", "regexp", "tagger", "text", or "textarea". *Type is not editable once created.
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 The description of the purpose of this ticket field, shown 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 A relative position for the ticket fields that determines the order of ticket fields on a ticket. Note that positions 0 to 7 are reserved for system fields
active boolean no no Whether this field is available
required boolean no no If it's required for this field to have a value when updated by agents
collapsed_for_agents boolean no no If this field should be shown to agents by default or be hidden alongside infrequently used fields. Classic interface only
regexp_for_validation string no no Regular expression field only. The validation pattern for a field value to be deemed valid.
title_in_portal string no no The title of the ticket field when shown to end users
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 available to end users
editable_in_portal boolean no no Whether this field is editable by end users
required_in_portal boolean no no If it's required for this field to have a value when updated by end users
tag string no no A tag value to set for checkbox fields when checked
created_at date yes no The time the ticket field was created
updated_at date yes no The time of the last update of the ticket field
system_field_options array yes no Presented for a ticket field of type "tickettype", "priority" or "status"
custom_field_options array no yes Required and presented for a ticket field of type "tagger"
removable boolean yes no If this field is not a system basic field that must be present for all tickets on the account
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
}

List Ticket Fields

GET /api/v2/ticket_fields.json

Returns a list of all ticket fields in your account. Fields are returned in the order that you specify in your Ticket Fields configuration in Zendesk Support. Clients should cache this resource for the duration of their API usage and map the id for each ticket field to the values returned under the fields attributes on the Ticket resource.

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,
      "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,
    "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
  • tagger (custom dropdown)
Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/ticket_fields.json \
  -H "Content-Type: application/json" -X POST \
  -d '{"ticket_field": {"type": "text", "title": "Age"}}' \
  -v -u {email_address}:{password}
Example Response
Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/ticket_fields/{id}.json

{
  "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,
    "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 \
  -H "Content-Type: application/json" -X PUT \
  -d '{ "ticket_field": { "title": "Your age" }}' \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK
Location: https://{subdomain}.zendesk.com/api/v2/ticket_fields/89.json

{
  "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,
    "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.

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 \
  -H "Content-Type: application/json" -X PUT \
  -d '{"ticket_field": {"custom_field_options": [{"name": "Apple Pie", "value": "apple"}, {"name": "Pecan Pie", "value": "pecan"}]}}' \
  -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 a 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 a Ticket Field Option

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

Creates a new or updates an existing 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 \
  -H "Content-Type: application/json" -X POST \
  -d '{"custom_field_option": {"name": "Grapes", "position": 2, "value": "grape"}}' \
  -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 \
  -H "Content-Type: application/json" -X POST \
  -d '{"custom_field_option": {"id": 10002, "name": "Pineapples", "position": 2, "value": "pineapple"}}' \
  -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