Custom Object Fields

You can use this API to add fields to your custom objects. Basic text fields, date fields, as well as customizable drop-down and number fields are available. The fields correspond to the custom object fields that admins can add using the Zendesk admin interface.

The fields are only visible to agents and admins.

Standard Custom Object Fields

Some fields, such as name and external id, are predefined and required for every object. The standard fields can't be manually created, deleted, or deactivated, and only the title, description, and properties attributes can be edited. The purpose of these standard fields is to allow customers to edit the display title and description of the name and external id fields on a custom object's records. Standard field keys begin with the standard:: prefix.

About dropdown and multiselect fields

Most custom fields let agents enter a single value such as free-form text or a date. The dropdown field lets agents choose a single value from a list of options. The multiselect field lets agents choose one or more values from a list of options. Each option has a name that's visible to the agent and an underlying value that's not visible. In the API, these options are listed in the dropdown and multiselect field's custom_field_options property. Each option in the list has a name and value property.

In the Zendesk admin interface, the "Value" field corresponds to the name property and the "Tag" field corresponds to the value property.

Occasionally, a value can be duplicated through API requests. When this happens, the field becomes uneditable until the duplicated value is removed.

Each dropdown or multiselect field supports a maximum of 2000 options.

About lookup relationship fields

Lookup relationship fields are used to connect custom objects to other objects in Zendesk. The lookup relationship field can be defined on a standard object and point to a custom object or within the custom object and point to another custom object or standard object. See Lookup relationships.

About currency fields

Currency fields let agents enter monetary values in a specific currency. Each currency field supports a single ISO 4217 currency code (for example, "USD"), specified in the allowed_currencies attribute of the field's properties object. Only a subset of ISO 4217 codes is supported. For the list, see Supported currency codes. The currency code can't be changed after the field is created.

About parent relationship fields

Parent relationship fields create a parent-child relationship between two objects. Unlike lookup fields, parent fields enforce a strict dependency where the child record cannot exist without a parent. Parent fields are a special type of lookup field with additional constraints and behaviors:

• Always required - Parent fields are automatically set as required. The child record must always reference a valid parent record.
• Cascade deletion - Deleting a parent record automatically deletes all associated child records asynchronously via a background job. Child records are first tombstoned and then permanently deleted after a 30-day retention period.
• Cascade permissions - Optionally, permissions on child records can cascade from the parent. When cascade_permissions_enabled is true in the field's properties, agents must provide a parent record context to list or search child records. See Custom Object Permissions.
• Immutable target - The relationship_target_type cannot be changed after creation, just like lookup fields.

Constraints

• Parent fields can only be created on custom objects (not on tickets, users, or organizations)
• A child object can have a maximum of 2 parent fields
• No self-referential relationships (an object cannot be its own parent)
• No depth greater than 1 (an object that is already a child cannot be a parent of another object, and vice versa)
• Parent fields cannot be created if the child object already has existing records
• Valid relationship_target_type values for parent fields are: "zen:user", "zen:organization", "zen:ticket", and "zen:custom_object:{key}"
• Only one parent field per child object can have cascade_permissions_enabled set to true

About roll-up summary fields

Roll-up summary fields are read-only, calculated fields on a parent custom object that automatically aggregate values from child records in a parent-child relationship. The aggregated value is computed asynchronously and stored on the parent record.

Roll-up summary fields are a special type of integer, decimal, or date fields with additional roll-up configuration in the properties object.

A roll-up summary field's readonly attribute is always true. Optionally, when creating the roll-up summary field, filters can be specified to restrict which child records are included in the summary.

The values are calculated automatically from child records. Roll-up summary field calculations occur asynchronously when child records are created, updated, or deleted. Depending on the number of child records included in the calculation, the value could be updated in near real-time or hourly.

Configuration properties

The properties object on a roll-up field consists of the following properties:

Property	Type	Description
rollup_aggregation_type	string	The aggregation operation: "COUNT", "SUM", "MIN", or "MAX". The "COUNT" aggregation type must be paired with the integer field type
rollup_child_object	string	The Zendesk resource name (ZRN) of the child object. Example: "zen:custom_object:order_item"
rollup_aggregated_field	string	The key of the child field to aggregate. Not required for COUNT
rollup_aggregated_field_title	string	Read-only. The title of the aggregated child field
rollup_filter_criteria	object	Optional filter conditions defined as all or any arrays that restrict which child records are included

Recalculation behavior

Roll-up values are re-calculated asynchronously based on the number of child records per parent.

Tier	Child count	Behavior
1	1 to 1,000	Near real-time debounced recalculation (within seconds)
2	1,001 – 10,000	Hourly recalculation. Values may become stale
3	Above 10,000	Not calculated. The roll-up value isn't maintained

These thresholds apply to recalculation only — child records are never blocked from being created.

JSON format

Custom Object Fields are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
active	boolean	false	false	If true, this field is available for use
created_at	string	true	false	The time the field was created
custom_field_options	array	false	false	Required and presented for a custom field of type "dropdown". Each option is represented by an object with a name and value property
description	string	false	false	User-defined description of this field's purpose
id	integer	true	false	Automatically assigned upon creation
key	string	false	true	A unique key that identifies this custom field. This is used for updating the field and referencing in placeholders. The key must consist of only letters, numbers, and underscores. It can't be only numbers
position	integer	false	false	Ordering of the field relative to other fields
properties	object	false	false	A set of field-specific properties. For the standard::name field, this includes autonumbering and uniqueness settings (which can't be used together). For currency fields, this includes the allowed currency code. For parent fields, includes the cascade_permissions_enabled setting. For roll-up summary fields, includes the aggregation configuration.
raw_description	string	false	false	The dynamic content placeholder, if present, or the description value, if not. See Dynamic Content Items
raw_title	string	false	false	The dynamic content placeholder, if present, or the title value, if not. See Dynamic Content Items
readonly	boolean	true	false	If true, the field value cannot be set or updated by API consumers. Currently only applies to roll-up summary fields, where the value is computed automatically.
regexp_for_validation	string	false	false	Regular expression field 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. For lookup fields, options are "zen:user", "zen:organization", "zen:ticket", "zen:article", "zen:brand", and "zen:custom_object:{key}" where key is a custom object key. For example "zen:custom_object:apartment". For parent fields, valid options are "zen:user", "zen:organization", "zen:ticket", and "zen:custom_object:{key}". Cannot be changed after creation.
required	boolean	false	false	If true, the field must have a value when creating or updating custom object records.
system	boolean	true	false	If true, only active and position values of this field can be changed
tag	string	false	false	Optional for custom field of type "checkbox"; not presented otherwise.
title	string	false	true	The title of the custom field
type	string	false	true	The custom field type: "checkbox", "currency", "date", "decimal", "dropdown", "integer", "lookup", "multiselect", "parent" (custom objects only), "regexp", "text", or "textarea"
updated_at	string	true	false	The time of the last update of the field
url	string	true	false	The URL for this resource

Example

{
  "active": true,
  "created_at": "2022-09-07T23:21:59Z",
  "description": "Make",
  "id": 4398096842879,
  "key": "make",
  "position": 0,
  "properties": {
    "autoincrement_enabled": true,
    "autoincrement_next_sequence": 1,
    "autoincrement_padding": 5,
    "autoincrement_prefix": "Order # ",
    "is_unique": false
  },
  "raw_description": "Make",
  "raw_title": "Make",
  "regexp_for_validation": null,
  "required": false,
  "system": false,
  "title": "Make",
  "type": "text",
  "updated_at": "2022-09-07T23:22:00Z",
  "url": "https://company.zendesk.com/api/v2/custom_objects/car/fields/4398096842879"
}

List Custom Object Fields

• GET /api/v2/custom_objects/{custom_object_key}/fields

Lists all undeleted custom fields for the specified object.

Allowed For

• Agents

Pagination

• Cursor pagination (recommended)
• Offset pagination

See Pagination.

Parameters

Name	Type	In	Required	Description
include_standard_fields	boolean	Query	false	Include standard fields if true. Exclude them if false
custom_object_key	string	Path	true	The key of a custom object

Code Samples

Curl

curl --request GET https://example.zendesk.com/api/v2/custom_objects/car/fields?include_standard_fields=true \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token}

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/fields?include_standard_fields=true"
	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 "{email_address}/token:{api_token}"

	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/custom_objects/car/fields")
		.newBuilder()
		.addQueryParameter("include_standard_fields", "true");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

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

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/fields',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  params: {
    'include_standard_fields': 'true',
  },
};

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

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/custom_objects/car/fields?include_standard_fields=true"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"GET",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/fields")
uri.query = URI.encode_www_form("include_standard_fields": "true")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Get custom object fields, with standard fields included

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/fields?include_standard_fields=true \
  -v -u {email_address}/token:{api_token}

Example response(s)

200 OK

// Status 200 OK

{
  "custom_object_fields": [
    {
      "active": true,
      "created_at": "2022-09-07T23:21:59Z",
      "description": "Name",
      "id": 4398096842877,
      "key": "standard::name",
      "position": 0,
      "properties": {
        "autoincrement_enabled": true,
        "autoincrement_next_sequence": 1,
        "autoincrement_padding": 5,
        "autoincrement_prefix": "Order # ",
        "is_unique": false
      },
      "raw_description": "Name",
      "raw_title": "Name",
      "regexp_for_validation": null,
      "required": true,
      "system": false,
      "title": "Name",
      "type": "text",
      "updated_at": "2022-09-07T23:22:00Z",
      "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/fields?id=4398096842877"
    },
    {
      "active": true,
      "created_at": "2022-09-07T23:21:59Z",
      "description": "External ID",
      "id": 4398096842878,
      "key": "standard::external_id",
      "position": 1,
      "raw_description": "External ID",
      "raw_title": "External ID",
      "regexp_for_validation": null,
      "required": false,
      "system": false,
      "title": "External ID",
      "type": "text",
      "updated_at": "2022-09-07T23:22:00Z",
      "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/fields?id=4398096842878"
    },
    {
      "active": true,
      "created_at": "2022-09-07T23:22:14Z",
      "description": "Model",
      "id": 4398096843007,
      "key": "model",
      "position": 2,
      "raw_description": "Model",
      "raw_title": "Model",
      "regexp_for_validation": null,
      "required": true,
      "system": false,
      "title": "Model",
      "type": "text",
      "updated_at": "2022-09-07T23:22:14Z",
      "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/fields?id=4398096843007"
    }
  ]
}

Create Custom Object Field

• POST /api/v2/custom_objects/{custom_object_key}/fields

Creates any of the following custom field types:

• text (default when no "type" is specified)
• textarea
• checkbox
• currency
• date
• integer
• decimal
• regexp
• dropdown
• lookup
• multiselect
• parent

Additionally, you can create a roll-up summary field by specifying an existing type (integer, decimal, or date) with roll-up configuration in the properties object. See About roll-up summary fields.

See About custom field types in Zendesk help.

Allowed For

• Admins

Parameters

Name	Type	In	Required	Description
custom_object_key	string	Path	true	The key of a custom object

Example body

{
  "custom_object_field": {
    "key": "color",
    "title": "Color",
    "type": "text"
  }
}

Code Samples

Curl

curl --request POST https://example.zendesk.com/api/v2/custom_objects/car/fields \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token} \
--data-raw '{
  "custom_object_field": {
    "key": "color",
    "title": "Color",
    "type": "text"
  }
}'

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/fields"
	method := "POST"
	payload := strings.NewReader(`{
  "custom_object_field": {
    "key": "color",
    "title": "Color",
    "type": "text"
  }
}`)
	req, err := http.NewRequest(method, url, payload)

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

	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/custom_objects/car/fields")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"custom_object_field\": {
    \"key\": \"color\",
    \"title\": \"Color\",
    \"type\": \"text\"
  }
}""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

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

Nodejs

var axios = require('axios');
var data = JSON.stringify({
  "custom_object_field": {
    "key": "color",
    "title": "Color",
    "type": "text"
  }
});

var config = {
  method: 'POST',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/fields',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  data : data,
};

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

Python

import requests
import json
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/custom_objects/car/fields"

payload = json.loads("""{
  "custom_object_field": {
    "key": "color",
    "title": "Color",
    "type": "text"
  }
}""")
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"POST",
	url,
	auth=auth,
	headers=headers,
	json=payload
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/fields")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.body = %q({
  "custom_object_field": {
    "key": "color",
    "title": "Color",
    "type": "text"
  }
})
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Create custom object field

For clarity, the example places the JSON in a separate file and imports it into the cURL statement

my_object.json

{
  "custom_object_field": {
    "title": "Color",
    "key": "color",
    "type": "text"
  }
}

curl - Create custom object field snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/fields \
  -d @my_object.json \
  -H "Content-Type: application/json" -v -u {email_address}/token:{api_token} -X POST

curl - Create parent relationship field

Creates a parent relationship field linking a child object to a custom object. Parent fields are always required and support optional cascade permissions.

parent_field.json

{
  "custom_object_field": {
    "title": "Service Order",
    "key": "service_order",
    "type": "parent",
    "relationship_target_type": "zen:custom_object:service_order",
    "properties": {
      "cascade_permissions_enabled": true
    }
  }
}

curl - Create parent relationship field snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/fields \
  -d @parent_field.json \
  -H "Content-Type: application/json" -v -u {email_address}/token:{api_token} -X POST

curl - Create roll-up summary field

Creates a roll-up summary field that counts child records from a related object. The field type must be compatible with the aggregation type (COUNT requires integer).

rollup_field.json

{
  "custom_object_field": {
    "title": "Total Line Items",
    "key": "total_line_items",
    "type": "integer",
    "properties": {
      "rollup_aggregation_type": "COUNT",
      "rollup_child_object": "zen:custom_object:order_item"
    }
  }
}

curl - Create roll-up summary field snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/fields \
  -d @rollup_field.json \
  -H "Content-Type: application/json" -v -u {email_address}/token:{api_token} -X POST

Example response(s)

201 Created

// Status 201 Created

{
  "custom_object_field": {
    "active": true,
    "created_at": "2022-09-07T23:21:59Z",
    "description": "Make",
    "id": 4398096842879,
    "key": "make",
    "position": 0,
    "raw_description": "Make",
    "raw_title": "Make",
    "regexp_for_validation": null,
    "required": false,
    "system": false,
    "title": "Make",
    "type": "text",
    "updated_at": "2022-09-07T23:22:00Z",
    "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/fields?id=4398096842879"
  }
}

Show Custom Object Field

• GET /api/v2/custom_objects/{custom_object_key}/fields/{custom_object_field_key_or_id}

Returns a custom field for a specific object using a provided key or id of the field.

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
include_standard_fields	boolean	Query	false	If true, returns standard fields in addition to custom fields.
custom_object_field_key_or_id	string	Path	true	The key or id of a custom object field
custom_object_key	string	Path	true	The key of a custom object

Code Samples

Curl

curl --request GET https://example.zendesk.com/api/v2/custom_objects/car/fields/make?include_standard_fields= \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token}

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/fields/make?include_standard_fields="
	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 "{email_address}/token:{api_token}"

	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/custom_objects/car/fields/make")
		.newBuilder()
		.addQueryParameter("include_standard_fields", "");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

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

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/fields/make',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
  params: {
    'include_standard_fields': '',
  },
};

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

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/custom_objects/car/fields/make?include_standard_fields="
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"GET",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/fields/make")
uri.query = URI.encode_www_form("include_standard_fields": "")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Get custom object field by key or id

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/fields/{custom_object_field_key_or_id} \
  -v -u {email_address}/token:{api_token}

Example response(s)

200 OK

// Status 200 OK

{
  "custom_object_field": {
    "active": true,
    "created_at": "2022-09-07T23:21:59Z",
    "description": "Make",
    "id": 4398096842879,
    "key": "make",
    "position": 0,
    "raw_description": "Make",
    "raw_title": "Make",
    "regexp_for_validation": null,
    "required": false,
    "system": false,
    "title": "Make",
    "type": "text",
    "updated_at": "2022-09-07T23:22:00Z",
    "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/fields?id=4398096842879"
  }
}

Update Custom Object Field

• PATCH /api/v2/custom_objects/{custom_object_key}/fields/{custom_object_field_key_or_id}

Updates individual custom object fields. The updating rules are as follows:

• Takes a custom_object_field object that specifies the properties to update.
• The key property cannot be updated.
• If updating a standard field, only the title, description, and properties attributes can be updated.
• Standard name field is always required. Therefore, the required property for standard name field isn't editable.
• The properties parameter is comprised of four parts and can't be changed if any records exist for the object.
  • autoincrement_enabled: A Boolean that enables and disables autonumbering. Must be false if is_unique is true.
  • autoincrement_prefix: A string value that is used as a prefix to the autogenerated numbers. It can't exceed 30 characters.
  • autoincrement_padding: An integer specifying the starting number of digits in the autogenerated numbers. This value may be between 0-9. However, if you create records in excess of of these digits, additional digits are added as necessary.
  • autoincrement_next_sequence: An integer that will be used as the next number in the autonumbering sequence. It can't be negative or less than the current autonumbering value.
  • is_unique: A Boolean that enforces uniqueness for manually entered record names. When true, custom object record names must be unique. Must be false if autoincrement_enabled is true.

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 an id, name, and value property. The name and value properties correspond to the "Title" and "Tag" text boxes in the admin interface respectively. For new drop-down options, specify "id":"null". Example request body:

{"custom_object_field": {
    "custom_field_options": [
      {"id": "null", "name": "Apple Pie", "value": "apple"},
      {"id": "null", "name": "Pecan Pie", "value": "pecan"}
    ]
  }
}

Example Request

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/fields/{custom_object_field_key_or_id}
  -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}/token:{api_token}

Allowed For

• Admins

Parameters

Name	Type	In	Required	Description
custom_object_field_key_or_id	string	Path	true	The key or id of a custom object field
custom_object_key	string	Path	true	The key of a custom object

Code Samples

Curl

curl --request PATCH https://example.zendesk.com/api/v2/custom_objects/car/fields/make \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token}

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/fields/make"
	method := "PATCH"
	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 "{email_address}/token:{api_token}"

	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/custom_objects/car/fields/make")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("PATCH", body)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'PATCH',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/fields/make',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
};

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

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/custom_objects/car/fields/make"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"PATCH",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/fields/make")
request = Net::HTTP::Patch.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Update a custom object field by key or id

For clarity, the example places the JSON in a separate file and imports it into the cURL statement

updated_field.json

{
  "custom_object_field": {
    "title": "Primary Color"
  }
}

curl - Update a custom object field by key or id snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/fields/{custom_object_field_key_or_id} \
-d @updated_field.json \
-H "Content-Type: application/json" -X PATCH \
-v -u {email_address}/token:{api_token}

curl - Update a custom object field's autonumbering properties

This example includes changes to the properties of a custom object's name field.

updated_field.json

{
  "custom_object_field": {
    "properties": {
      "autoincrement_enabled": true,
      "autoincrement_prefix": "Order Number: ",
      "autoincrement_padding": 5,
      "autoincrement_next_sequence": 1,
      "is_unique": false
    }
  }
}

curl - Update a custom object field's autonumbering properties snippet

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/fields/{custom_object_field_key_or_id} \
-d @updated_field.json \
-H "Content-Type: application/json" -X PATCH \
-v -u {email_address}/token:{api_token}

Example response(s)

200 OK

// Status 200 OK

{
  "custom_object_field": {
    "active": true,
    "created_at": "2022-09-07T23:21:59Z",
    "description": "Make",
    "id": 4398096842879,
    "key": "make",
    "position": 0,
    "raw_description": "Make",
    "raw_title": "Make",
    "regexp_for_validation": null,
    "required": false,
    "system": false,
    "title": "Make",
    "type": "text",
    "updated_at": "2022-09-07T23:22:00Z",
    "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/car/fields?id=4398096842879"
  }
}

Delete Custom Object Field

• DELETE /api/v2/custom_objects/{custom_object_key}/fields/{custom_object_field_key_or_id}

Deletes a field with the specified key. Note: You can't delete standard fields.

Allowed For

• Admins

Parameters

Name	Type	In	Required	Description
custom_object_field_key_or_id	string	Path	true	The key or id of a custom object field
custom_object_key	string	Path	true	The key of a custom object

Code Samples

Curl

curl --request DELETE https://example.zendesk.com/api/v2/custom_objects/car/fields/make \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token}

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/fields/make"
	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 "{email_address}/token:{api_token}"

	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/custom_objects/car/fields/make")
		.newBuilder();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

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

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/fields/make',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
};

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

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/custom_objects/car/fields/make"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"DELETE",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/fields/make")
request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Delete custom object field by key or id

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/fields/{custom_object_field_key_or_id} \
  -X DELETE \
  -v -u {email_address}/token:{api_token}

Example response(s)

204 No Content

// Status 204 No Content

null

Reorder Custom Fields of an Object

• PUT /api/v2/custom_objects/{custom_object_key}/fields/reorder

Sets a preferred order of custom fields for a specific object by providing field ids in the desired order.

Allowed For

• Admins

Parameters

Name	Type	In	Required	Description
custom_object_key	string	Path	true	The key of a custom object

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/fields/reorder \
  -d '{ "custom_object_field_ids": ["4398096843007", "4398096842879"] }' \
  -H "Content-Type: application/json" -v -u {email_address}/token:{api_token} -X POST

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/fields/reorder"
	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 "{email_address}/token:{api_token}"

	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/custom_objects/car/fields/reorder")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
""");
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

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

Nodejs

var axios = require('axios');

var config = {
  method: 'PUT',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/fields/reorder',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
};

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

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/custom_objects/car/fields/reorder"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"PUT",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/fields/reorder")
request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
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

null

Custom Object Fields Limit

• GET /api/v2/custom_objects/{custom_object_key}/limits/field_limit

List the current count and the limit for a custom object's fields

Allowed For

• Agents

Parameters

Name	Type	In	Required	Description
custom_object_key	string	Path	true	The key of a custom object

Code Samples

Curl

curl --request GET https://example.zendesk.com/api/v2/custom_objects/car/limits/field_limit \
--header "Content-Type: application/json" \
-u {email_address}/token:{api_token}

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car/limits/field_limit"
	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 "{email_address}/token:{api_token}"

	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/custom_objects/car/limits/field_limit")
		.newBuilder();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

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

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car/limits/field_limit',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
};

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

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://example.zendesk.com/api/v2/custom_objects/car/limits/field_limit"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"GET",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car/limits/field_limit")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Get custom object fields limit

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/{custom_object_key}/limits/field_limit \
  -v -u {email_address}/token:{api_token}

Example response(s)

200 OK

// Status 200 OK

{
  "count": 44,
  "limit": 400
}