Object Types

An object type is a blueprint for creating object records of the same type. You can design an object type for creating people, contracts, products, or anything else. For more information, see Object types in the Custom objects handbook.

You can control access to the object type definition and object records of the type by adjusting its policies.

JSON format

Object Types 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
key	string	true	true	A user-defined unique identifier. Writable on create only. See key property
schema	object	false	true	A description of the object record, up to a maximum of 32 KB. See schema property
updated_at	string	true	false	The time of the last update of the object type
version	integer	false	false	The version of this schema

key property

The key property is a unique identifier for the object type that you define yourself. The key must be between 2 and 32 characters long. Examples include "product", "cell_phone", and "2019-car".

schema property

The schema property describes the properties of the object records created from the type. It can also validate property values. The schema follows the JSON Schema specification. To learn more, see Creating a schema for a custom object in the Develop Help Center.

Zendesk applies the following schema validation rules:

• Empty schemas - The schema and the properties properties cannot be empty.

• Property naming rules - Any property in the schema has to conform to the following naming rules:

  • Property names cannot be prefixed with an "_" character.

  • "*" cannot be used as schema property name.

  • Property names cannot contain the following characters: "\b", "\f", "\n", "\r", "\t", "\u0007", "\u0013"

• Mandating additionalProperties as false - The additionalProperties property is an immutable property added to all new JSON Schemas and set to false. Any schema containing additionalProperties set to true will encounter an 400 Bad Request error. The validation rule restricts the ability to create object records that contain non-schema attributes.

• Supported types - The type property supports the following types: "boolean", "integer", "number", "string", and "array". The value of the type property cannot be set to an array of supported types. For example, ["string"] is an invalid type value. When defining an array, the items property must be present alongside defining the type property of the array. The type property of the array can be one of the following values "boolean", "integer", "number", "string".

• Supported keywords - Custom objects support the following JSON Schema keywords: "title", "description", "properties", "type", "items", "required", and "additionalProperties". The improper placement of the supported properties can also result in a 400 Bad Request error.

You can use the Validate Object Types endpoint to validate the schema of your object types. The error messages returned by the endpoint are outlined in Schema validation reference for object types .

Example

{
  "created_at": "2020-04-24T23:47:19.000Z",
  "key": "product",
  "schema": {
    "properties": {
      "id": {
        "description": "The unique identifier for a product",
        "type": "string"
      },
      "name": {
        "description": "The name of the product",
        "type": "string"
      }
    },
    "required": [
      "id",
      "name"
    ]
  },
  "updated_at": "2020-04-24T23:47:19.000Z"
}

List Object Types

• GET /api/sunshine/objects/types

Returns the account's object types. Zendesk object types such as "zen:user" are not included.

Allowed for

• Everyone

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/sunshine/objects/types \
  -v -u {email_address}:{password}

Go

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

func main() {
	url := "https://support.zendesk.com/api/sunshine/objects/types"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	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://support.zendesk.com/api/sunshine/objects/types")
		.newBuilder();

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

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/sunshine/objects/types',
  headers: {
	'Content-Type': 'application/json',
  },
};

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

Python

import requests

url = "https://support.zendesk.com/api/sunshine/objects/types"
headers = {
	"Content-Type": "application/json",
}

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

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/sunshine/objects/types")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
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

{
  "data": [
    {
      "created_at": "2018-01-01T10:20:30Z",
      "key": "product",
      "schema": {
        "properties": {
          "id": {
            "description": "product id",
            "type": "string"
          },
          "name": {
            "description": "product name",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name"
        ]
      },
      "updated_at": "2018-01-01T10:20:30Z",
      "version": 1
    },
    {
      "created_at": "2018-01-01T10:20:30Z",
      "key": "user",
      "schema": {
        "properties": {
          "id": {
            "description": "user id",
            "type": "string"
          },
          "name": {
            "description": "user name",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name"
        ]
      },
      "updated_at": "2018-01-01T10:20:30Z",
      "version": 2
    }
  ]
}

Validate Object Types

• GET /api/sunshine/objects/types/schema/report

Validates and generates a report of all the object types in the account. The report is based on the latest validations rules that have been implemented.

Allowed for

• Admins

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/sunshine/objects/types/schema/report/ \
  -X GET \
  -v -u {email_address}:{password}

Go

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

func main() {
	url := "https://support.zendesk.com/api/sunshine/objects/types/schema/report"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	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://support.zendesk.com/api/sunshine/objects/types/schema/report")
		.newBuilder();

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

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/sunshine/objects/types/schema/report',
  headers: {
	'Content-Type': 'application/json',
  },
};

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

Python

import requests

url = "https://support.zendesk.com/api/sunshine/objects/types/schema/report"
headers = {
	"Content-Type": "application/json",
}

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

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/sunshine/objects/types/schema/report")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
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

{
  "data": [
    {
      "message": [
        "The properties element of a schema cannot be empty."
      ],
      "object_type_key": "empty_schema_type"
    },
    {
      "message": [
        "data.schema instance value (\"object\") not found in enum (possible values: [\"boolean\",\"integer\",\"number\",\"string\",\"array\"])",
        "Invalid property name '_nested': Property name cannot start with '_'."
      ],
      "object_type_key": "nested_schema"
    }
  ]
}

Show Object Type

• GET /api/sunshine/objects/types/{object_type_key}

Returns the object type with the specified key.

Allowed for

• Everyone

Parameters

Name	Type	In	Required	Description
object_type_key	string	Path	true	The key property is a unique identifier for the object type that you define yourself

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/sunshine/objects/types/{key} \
  -v -u {email_address}:{password}

Go

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

func main() {
	url := "https://support.zendesk.com/api/sunshine/objects/types/product"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	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://support.zendesk.com/api/sunshine/objects/types/product")
		.newBuilder();

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

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://support.zendesk.com/api/sunshine/objects/types/product',
  headers: {
	'Content-Type': 'application/json',
  },
};

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

Python

import requests

url = "https://support.zendesk.com/api/sunshine/objects/types/product"
headers = {
	"Content-Type": "application/json",
}

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

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/sunshine/objects/types/product")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
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

{
  "data": {
    "created_at": "2018-01-01T10:20:30Z",
    "key": "product",
    "schema": {
      "properties": {
        "id": {
          "description": "product id",
          "type": "string"
        },
        "name": {
          "description": "product name",
          "type": "string"
        }
      },
      "required": [
        "id",
        "name"
      ]
    },
    "updated_at": "2018-01-01T10:20:30Z"
  }
}

Create Object Type

• POST /api/sunshine/objects/types

Creates an object type describing the properties of the object records to be created of that type.

Allowed for

• Admins

Code Samples

curl

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

resource_type.json

{
  "data": {
    "key": "product",
    "schema": {
      "properties": {
        "id": {
          "type": "string",
          "description": "product id"
        },
        "name": {
          "type": "string",
          "description": "product name"
        }
      },
      "required": [
        "id",
        "name"
      ]
    }
  }
}

curl snippet

curl https://{subdomain}.zendesk.com/api/sunshine/objects/types \
  -d @resource_type.json \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}

Go

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

func main() {
	url := "https://support.zendesk.com/api/sunshine/objects/types"
	method := "POST"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	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://support.zendesk.com/api/sunshine/objects/types")
		.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")
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'POST',
  url: 'https://support.zendesk.com/api/sunshine/objects/types',
  headers: {
	'Content-Type': 'application/json',
  },
};

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

Python

import requests

url = "https://support.zendesk.com/api/sunshine/objects/types"
headers = {
	"Content-Type": "application/json",
}

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

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/sunshine/objects/types")
request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")
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

{
  "data": {
    "created_at": "2018-01-01T10:20:30Z",
    "key": "product",
    "schema": {
      "properties": {
        "id": {
          "description": "product id",
          "type": "string"
        },
        "name": {
          "description": "product name",
          "type": "string"
        }
      },
      "required": [
        "id",
        "name"
      ]
    },
    "updated_at": "2018-01-01T10:20:30Z"
  }
}

Update Object Type

• PUT /api/sunshine/objects/types/{object_type_key}

Object type updating rules:

• Updates the schema property of an object type. It does not update the key.

• Include the full, updated object type in the request.

• Even though you can only update one property, this is a PUT endpoint, not a PATCH one.

• You can't update a Zendesk object type. For example, the key in the request path can't be "zen:user:123".

Object type schema updating rules:

• Updating the type property of any schema properties is not supported.

• Deleting schema properties is not supported.

Allowed for

• Admins

Parameters

Name	Type	In	Required	Description
object_type_key	string	Path	true	The key property is a unique identifier for the object type that you define yourself

Code Samples

curl

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

updated_resource_type.json

{
  "data": {
    "schema": {
      "properties": {
        "id": {
          "type": "string",
          "description": "product id"
        },
        "name": {
          "type": "string",
          "description": "product name"
        },
        "features": {
          "type": "string",
          "description": "product features"
        }
      },
      "required": [
        "id",
        "name"
      ]
    }
  }
}

curl snippet

curl https://{subdomain}.zendesk.com/api/sunshine/objects/types/{key} \
-d @updated_resource_type.json \
-H "Content-Type: application/json" -X PUT \
-v -u {email_address}:{password}

Go

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

func main() {
	url := "https://support.zendesk.com/api/sunshine/objects/types/product"
	method := "PUT"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	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://support.zendesk.com/api/sunshine/objects/types/product")
		.newBuilder();
RequestBody body = RequestBody.create(MediaType.parse("application/json"),
		"""
""");

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

Nodejs

var axios = require('axios');

var config = {
  method: 'PUT',
  url: 'https://support.zendesk.com/api/sunshine/objects/types/product',
  headers: {
	'Content-Type': 'application/json',
  },
};

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

Python

import requests

url = "https://support.zendesk.com/api/sunshine/objects/types/product"
headers = {
	"Content-Type": "application/json",
}

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

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/sunshine/objects/types/product")
request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")
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

{
  "data": {
    "created_at": "2019-01-01T10:20:30Z",
    "key": "product",
    "schema": {
      "properties": {
        "features": {
          "description": "product features",
          "type": "string"
        },
        "id": {
          "description": "product id",
          "type": "string"
        },
        "name": {
          "description": "product name",
          "type": "string"
        }
      },
      "required": [
        "id",
        "name"
      ]
    },
    "updated_at": "2019-01-02T06:45:00Z"
  }
}

Delete Object Type

• DELETE /api/sunshine/objects/types/{object_type_key}

Deletes the object type with the specified key.

You can only delete an object type if all object records created from the type have been deleted. See Delete Object Record.

Allowed for

• Admins

Parameters

Name	Type	In	Required	Description
object_type_key	string	Path	true	The key property is a unique identifier for the object type that you define yourself

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/sunshine/objects/types/{key} \
  -X DELETE \
  -v -u {email_address}:{password}

Go

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

func main() {
	url := "https://support.zendesk.com/api/sunshine/objects/types/product"
	method := "DELETE"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")

	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://support.zendesk.com/api/sunshine/objects/types/product")
		.newBuilder();

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

Nodejs

var axios = require('axios');

var config = {
  method: 'DELETE',
  url: 'https://support.zendesk.com/api/sunshine/objects/types/product',
  headers: {
	'Content-Type': 'application/json',
  },
};

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

Python

import requests

url = "https://support.zendesk.com/api/sunshine/objects/types/product"
headers = {
	"Content-Type": "application/json",
}

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

print(response.text)

Ruby

require "net/http"
uri = URI("https://support.zendesk.com/api/sunshine/objects/types/product")
request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")
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