Custom Objects

Custom objects enable you to extend the Zendesk data model and bring in data unique to your business so that you can model your business within Zendesk. You can use the custom objects API to create, read, update, and delete objects that you define yourself. You can also use it to define and manage relationships with other objects, including native Zendesk objects like tickets and users.

This is the New Custom Objects API. It's not compatible with custom data developed using the Legacy Custom Objects API.

Custom Object Limits

Category	Limit
Suite Team	3
Suite Growth	5
Support Enterprise and Suite Professional	30
Suite Enterprise and Suite Enterprise Plus	50

Additional limitations

• Only admins can create custom objects.
• Each custom object can have a maximum of 100 fields. The standard fields, such as name, aren't counted against this limit.
• Suite Team and Suite Growth plans can define a maximum of 5 lookup relationship fields per custom object. All other plans can configure up to 10 per custom object.

JSON format

Custom Objects are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
created_at	string	true	false	The time the object type was created
created_by_user_id	string	true	false	Id of a user who created the object
description	string	false	false	User-defined description of the object
key	string	true	true	A user-defined unique identifier. Writable on create only
raw_description	string	false	false	The dynamic content placeholder, if present, or the "raw_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
raw_title_pluralized	string	false	false	The dynamic content placeholder, if present, or the "raw_title_pluralized" value, if not. See Dynamic Content Items
title	string	false	true	User-defined display name for the object
title_pluralized	string	false	true	User-defined pluralized version of the object's title
updated_at	string	true	false	The time of the last update of the object
updated_by_user_id	string	true	false	Id of the last user who updated the object
url	string	true	false	Direct link to the specific custom object

List Custom Objects

• GET /api/v2/custom_objects

Lists all undeleted custom objects for the account

Allowed For

• Agents

Code Samples

Curl

curl --request GET https://example.zendesk.com/api/v2/custom_objects \
--header "Content-Type: application/json" \
-u username:password

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects"
	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/custom_objects")
		.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/custom_objects',
  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/custom_objects"
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/custom_objects")
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

curl - Get custom objects

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

Example response(s)

200 OK

// Status 200 OK

{
  "custom_objects": [
    {
      "created_at": "2022-09-02T22:44:35Z",
      "created_by_user_id": "16485",
      "description": "The list of cars in our fleet",
      "key": "car",
      "raw_description": "{{dc.car_description}}",
      "raw_title": "{{dc.car_title}}",
      "raw_title_pluralized": "{{dc.car_title_plural}}",
      "title": "Car",
      "title_pluralized": "Cars",
      "updated_at": "2022-09-02T22:44:35Z",
      "updated_by_user_id": "10234",
      "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/01GC0617DV48CAXK6WA4DW51HD.json"
    },
    {
      "created_at": "2022-08-01T22:44:35Z",
      "created_by_user_id": "123123",
      "description": "The list of vessels in our fleet",
      "key": "vessel",
      "raw_description": "{{dc.vessel_description}}",
      "raw_title": "{{dc.vessel_title}}",
      "raw_title_pluralized": "{{dc.vessel_title_plural}}",
      "title": "Vessel",
      "title_pluralized": "Vessel",
      "updated_at": "2022-09-02T22:44:35Z",
      "updated_by_user_id": "251251",
      "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/01GC9TXVMNT6VHB5GBGAR09WPF.json"
    }
  ]
}

Create Custom Object

• POST /api/v2/custom_objects

Creates an object describing all the properties required to create a custom object record

Allowed For

• Admins

Example body

{
  "custom_object": {
    "key": "apartment",
    "title": "Apartment",
    "title_pluralized": "Apartments"
  }
}

Code Samples

Curl

curl --request POST https://example.zendesk.com/api/v2/custom_objects \
--header "Content-Type: application/json" \
-u username:password \
--data-raw '{
  "custom_object": {
    "key": "apartment",
    "title": "Apartment",
    "title_pluralized": "Apartments"
  }
}'

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects"
	method := "POST"
	payload := strings.NewReader(`{
  "custom_object": {
    "key": "apartment",
    "title": "Apartment",
    "title_pluralized": "Apartments"
  }
}`)
	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 "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/custom_objects")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
{
  \"custom_object\": {
    \"key\": \"apartment\",
    \"title\": \"Apartment\",
    \"title_pluralized\": \"Apartments\"
  }
}""");

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 data = JSON.stringify({
  "custom_object": {
    "key": "apartment",
    "title": "Apartment",
    "title_pluralized": "Apartments"
  }
});

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

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

Python

import requests
import json

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

payload = json.loads("""{
  "custom_object": {
    "key": "apartment",
    "title": "Apartment",
    "title_pluralized": "Apartments"
  }
}""")
headers = {
	"Content-Type": "application/json",
}

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

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/custom_objects")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
request.body = %q({
  "custom_object": {
    "key": "apartment",
    "title": "Apartment",
    "title_pluralized": "Apartments"
  }
})
request.basic_auth "username", "password"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

curl - Create custom object

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

my_object.json

{
  "custom_object": {
    "key": "car",
    "title": "Car",
    "title_pluralized": "Cars"
  }
}

curl - Create custom object snippet

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

Example response(s)

201 Created

// Status 201 Created

{
  "custom_object": {
    "created_at": "2022-09-02T22:44:35Z",
    "created_by_user_id": "16485",
    "description": "The list of cars in our fleet",
    "key": "car",
    "raw_description": "{{dc.car_description}}",
    "raw_title": "{{dc.car_title}}",
    "raw_title_pluralized": "{{dc.car_title_plural}}",
    "title": "Car",
    "title_pluralized": "Cars",
    "updated_at": "2022-09-02T22:44:35Z",
    "updated_by_user_id": "10234",
    "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/01GC0617DV48CAXK6WA4DW51HD.json"
  }
}

Show Custom Object

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

Returns an object with the specified key

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 \
--header "Content-Type: application/json" \
-u username:password

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car"
	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/custom_objects/car")
		.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/custom_objects/car',
  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/custom_objects/car"
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/custom_objects/car")
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

curl - Get custom object by key

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

Example response(s)

200 OK

// Status 200 OK

{
  "custom_object": {
    "created_at": "2022-09-02T22:44:35Z",
    "created_by_user_id": "16485",
    "description": "The list of cars in our fleet",
    "key": "car",
    "raw_description": "{{dc.car_description}}",
    "raw_title": "{{dc.car_title}}",
    "raw_title_pluralized": "{{dc.car_title_plural}}",
    "title": "Car",
    "title_pluralized": "Cars",
    "updated_at": "2022-09-02T22:44:35Z",
    "updated_by_user_id": "10234",
    "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/01GC0617DV48CAXK6WA4DW51HD.json"
  }
}

Update Custom Object

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

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

• Takes a custom_object object that specifies the properties to update
• The key property cannot be updated

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 --request PATCH https://example.zendesk.com/api/v2/custom_objects/car \
--header "Content-Type: application/json" \
-u username:password

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car"
	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 "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/custom_objects/car")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
""");

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("PATCH", 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: 'PATCH',
  url: 'https://example.zendesk.com/api/v2/custom_objects/car',
  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/custom_objects/car"
headers = {
	"Content-Type": "application/json",
}

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

print(response.text)

Ruby

require "net/http"
uri = URI("https://example.zendesk.com/api/v2/custom_objects/car")
request = Net::HTTP::Patch.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

curl - Update custom object by key

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

updated_custom_object.json

{
  "custom_object": {
    "title": "Electric Car",
    "title_pluralized": "Electric Cars"
  }
}

curl - Update custom object by key snippet

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

Example response(s)

200 OK

// Status 200 OK

{
  "custom_object": {
    "created_at": "2022-09-02T22:44:35Z",
    "created_by_user_id": "16485",
    "description": "The list of cars in our fleet",
    "key": "car",
    "raw_description": "{{dc.car_description}}",
    "raw_title": "{{dc.car_title}}",
    "raw_title_pluralized": "{{dc.car_title_plural}}",
    "title": "Car",
    "title_pluralized": "Cars",
    "updated_at": "2022-09-02T22:44:35Z",
    "updated_by_user_id": "10234",
    "url": "https://{subdomain}.zendesk.com/api/v2/custom_objects/01GC0617DV48CAXK6WA4DW51HD.json"
  }
}

Delete Custom Object

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

Permanently deletes the custom object with the specified key

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 --request DELETE https://example.zendesk.com/api/v2/custom_objects/car \
--header "Content-Type: application/json" \
-u username:password

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/car"
	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/custom_objects/car")
		.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/custom_objects/car',
  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/custom_objects/car"
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/custom_objects/car")
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

curl - Delete custom object by key

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

Example response(s)

204 No Content

// Status 204 No Content

null

Custom Objects Limit

• GET /api/v2/custom_objects/limits/object_limit

List the current count and the limit for custom objects

Allowed For

• Admins

Code Samples

Curl

curl --request GET https://example.zendesk.com/api/v2/custom_objects/limits/object_limit \
--header "Content-Type: application/json" \
-u username:password

Go

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

func main() {
	url := "https://example.zendesk.com/api/v2/custom_objects/limits/object_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 "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/custom_objects/limits/object_limit")
		.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/custom_objects/limits/object_limit',
  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/custom_objects/limits/object_limit"
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/custom_objects/limits/object_limit")
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

curl - Get custom objects count and limit

curl https://{subdomain}.zendesk.com/api/v2/custom_objects/limits/object_limit \
  -v -u {email_address}:{password}

Example response(s)

200 OK

// Status 200 OK

{
  "count": 19,
  "limit": 50
}