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.

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

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_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 presented 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
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	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_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,
  "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.json",
  "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.

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 and id.

For accounts without access to multiple ticket forms, positions can be changed using the Update Ticket Field endpoint or the Ticket Forms page in Zendesk Support (Admin > Manage > Ticket Forms). The Ticket Forms page shows the fields for the account. The order of the fields is used in the different products to show the field values in the tickets.

For accounts with access to multiple ticket forms, positions can only be changed using the Update Ticket Field endpoint because products use the order defined on each form to show the field values instead of the general position of the ticket field in the account.

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

• Agents

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

Limits

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.

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/ticket_fields.json \
  -v -u {email_address}:{password}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/ticket_fields?creator=&locale="
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/ticket_fields")
		.newBuilder()
		.addQueryParameter("creator", "")
		.addQueryParameter("locale", "");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/ticket_fields',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
  params: {
    'creator': '',
    'locale': '',
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://example.zendesk.com/api/v2/ticket_fields?creator=&locale="
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/ticket_fields")
uri.query = URI.encode_www_form("creator": "", "locale": "")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

{
  "ticket_fields": [
    {
      "active": true,
      "agent_description": "Agent only description",
      "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,
      "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,
      "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.json",
      "visible_in_portal": true
    }
  ]
}

Count Ticket Fields

• GET /api/v2/ticket_fields/count
• GET /api/v2/ticket_fields/count

Returns an approximate count of system and custom ticket fields in the account. If the count exceeds 100,000, the count will return a cached result. This cached result will update every 24 hours.

The count[refreshed_at] property is a timestamp that indicates when the count was last updated.

Note: When the count exceeds 100,000, count[refreshed_at] may occasionally be null. This indicates that the count is being updated in the background, and count[value] is limited to 100,000 until the update is complete.

Allowed For

• Agents

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/count.json \
  -v -u {email_address}:{password}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/ticket_fields/count"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/ticket_fields/count")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/ticket_fields/count',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://example.zendesk.com/api/v2/ticket_fields/count"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/ticket_fields/count")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

{
  "count": {
    "refreshed_at": "2020-04-06T02:18:17Z",
    "value": 102
  }
}

Show Ticket Field

• GET /api/v2/ticket_fields/{ticket_field_id}

Allowed for

• Agents

Sideloads

The following sideloads are supported:

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

Parameters

Name	Type	In	Required	Description
creator	boolean	Query	false	If true, 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, then creator_app_name is null
ticket_field_id	integer	Path	true	The ID of the ticket field

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{ticket_field_id}.json \
  -v -u {email_address}:{password}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/ticket_fields/34?creator="
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/ticket_fields/34")
		.newBuilder()
		.addQueryParameter("creator", "");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/ticket_fields/34',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
  params: {
    'creator': '',
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://example.zendesk.com/api/v2/ticket_fields/34?creator="
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/ticket_fields/34")
uri.query = URI.encode_www_form("creator": "")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

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

Create Ticket Field

• POST /api/v2/ticket_fields

Creates any of the following custom field types:

Custom field type	Description
text	Default custom field type when type is not specified
textarea	For multi-line text
checkbox	To capture a boolean value. Allowed values are true or false
date	Example: 2021-04-16
integer	String composed of numbers. May contain an optional decimal point
decimal	For numbers containing decimals
regexp	Matches the Regex pattern found in the custom field settings
partialcreditcard	A credit card number. Only the last 4 digits are retained
multiselect	Enables users to choose multiple options from a dropdown menu
tagger	Single-select dropdown menu. It contains one or more tag values belonging to the field's options. Example: ( {"id": 21938362, "value": ["hd_3000", "hd_5555"]})
lookup	A field to create a relationship (see lookup relationships) to another object such as a user, ticket, or organization

See About custom field types in the Zendesk Help Center.

Allowed For

• Admins

Field limits

We recommend the following best practices for ticket fields limits. Creating more than these amounts can affect performance.

• 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

Code Samples

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}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/ticket_fields"
	method := "POST"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/ticket_fields")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("POST", body)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'POST',
  url: 'https://example.zendesk.com/api/v2/ticket_fields',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://example.zendesk.com/api/v2/ticket_fields"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"POST",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/ticket_fields")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

201 Created

// Status 201 Created

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

Update Ticket Field

• PUT /api/v2/ticket_fields/{ticket_field_id}

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:

{"ticket_field": {
    "custom_field_options": [
      {"name": "Apple Pie", "value": "apple"},
      {"name": "Pecan Pie", "value": "pecan"}
    ]
  }
}

Example Request

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
      },
      ...
    ]
  }
}

Allowed for

• Admins

Parameters

Name	Type	In	Required	Description
creator	boolean	Query	false	If true, 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, then creator_app_name is null
ticket_field_id	integer	Path	true	The ID of the ticket field

Limits

This is the limit definition for the update action.

Rate Limits	Scopes	Interval	Sandbox	Trial	Default
Standard	Account	1 minute	50	25	75
With High Volume API Add On	Account	1 minute	50	25	75

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

Code Samples

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}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/ticket_fields/34?creator="
	method := "PUT"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/ticket_fields/34")
		.newBuilder()
		.addQueryParameter("creator", "");
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("PUT", body)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'PUT',
  url: 'https://example.zendesk.com/api/v2/ticket_fields/34',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
  params: {
    'creator': '',
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://example.zendesk.com/api/v2/ticket_fields/34?creator="
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"PUT",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/ticket_fields/34")
uri.query = URI.encode_www_form("creator": "")
request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

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

Delete Ticket Field

• DELETE /api/v2/ticket_fields/{ticket_field_id}

Allowed for

• Admins

Parameters

Name	Type	In	Required	Description
creator	boolean	Query	false	If true, 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, then creator_app_name is null
ticket_field_id	integer	Path	true	The ID of the ticket field

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{ticket_field_id}.json \
  -v -u {email_address}:{password} -X DELETE

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/ticket_fields/34?creator="
	method := "DELETE"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/ticket_fields/34")
		.newBuilder()
		.addQueryParameter("creator", "");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("DELETE", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  url: 'https://example.zendesk.com/api/v2/ticket_fields/34',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
  params: {
    'creator': '',
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://example.zendesk.com/api/v2/ticket_fields/34?creator="
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"DELETE",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/ticket_fields/34")
uri.query = URI.encode_www_form("creator": "")
request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

204 No Content

// Status 204 No Content

null

List Ticket Field Options

• GET /api/v2/ticket_fields/{ticket_field_id}/options

Returns a list of custom ticket field options for the given drop-down ticket field.

Allowed For

• Agents

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Parameters

Name	Type	In	Required	Description
ticket_field_id	integer	Path	true	The ID of the ticket field

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{ticket_field_id}/options.json \
  -v -u {email_address}:{password}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/ticket_fields/34/options"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/ticket_fields/34/options")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/ticket_fields/34/options',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://example.zendesk.com/api/v2/ticket_fields/34/options"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/ticket_fields/34/options")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// 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/{ticket_field_id}/options/{ticket_field_option_id}

Allowed for

• Agents

Parameters

Name	Type	In	Required	Description
ticket_field_id	integer	Path	true	The ID of the ticket field
ticket_field_option_id	integer	Path	true	The ID of the ticket field option

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{ticket_field_id}/options/{ticket_field_option_id}.json \
  -v -u {email_address}:{password}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/ticket_fields/34/options/10001"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/ticket_fields/34/options/10001")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/ticket_fields/34/options/10001',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://example.zendesk.com/api/v2/ticket_fields/34/options/10001"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"GET",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/ticket_fields/34/options/10001")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// 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/{ticket_field_id}/options

Creates or updates an option for the given drop-down 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.

Response

Returns one of the following status codes:

• 200 with Location: /api/v2/ticket_fields/{ticket_field_id}/options.json if the ticket field option already exists in the database
• 201 with Location: /api/v2/ticket_fields/{ticket_field_id}/options.json if the ticket field option is new

Allowed For

• Admins

Rate Limit

You can make 100 requests every 1 minute using this endpoint. The rate limiting mechanism behaves as described in Monitoring your request activity in the API introduction.

Field Option Limits

• 2000 options per ticket field

Parameters

Name	Type	In	Required	Description
ticket_field_id	integer	Path	true	The ID of the ticket field

Code Samples

curl

Create Ticket Field Option

curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{ticket_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}

curl

Update Ticket Field Option

curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{ticket_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}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/ticket_fields/34/options"
	method := "POST"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/ticket_fields/34/options")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("POST", body)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'POST',
  url: 'https://example.zendesk.com/api/v2/ticket_fields/34/options',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://example.zendesk.com/api/v2/ticket_fields/34/options"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"POST",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/ticket_fields/34/options")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// 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"
  }
}

201 Created

// 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"
  }
}

Delete Ticket Field Option

• DELETE /api/v2/ticket_fields/{ticket_field_id}/options/{ticket_field_option_id}

Allowed for

• Admins

Parameters

Name	Type	In	Required	Description
ticket_field_id	integer	Path	true	The ID of the ticket field
ticket_field_option_id	integer	Path	true	The ID of the ticket field option

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/ticket_fields/{ticket_field_id}/options/{ticket_field_option_id}.json \
  -v -u {email_address}:{password} -X DELETE

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://example.zendesk.com/api/v2/ticket_fields/34/options/10001"
	method := "DELETE"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://example.zendesk.com/api/v2/ticket_fields/34/options/10001")
		.newBuilder();

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("DELETE", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  url: 'https://example.zendesk.com/api/v2/ticket_fields/34/options/10001',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests

url = "https://example.zendesk.com/api/v2/ticket_fields/34/options/10001"
headers = {
	"Content-Type": "application/json",
}

response = requests.request(
	"DELETE",
	url,
	auth=('<username>', '<password>'),
	headers=headers
)

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/ticket_fields/34/options/10001")
request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

204 No Content

// Status 204 No Content

null