Legacy Object Types

A legacy object type is a blueprint for creating legacy object records of the same type. You can design a legacy object type for creating people, contracts, products, or anything else. For more information, see Legacy object types in the Legacy custom objects handbook.

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

JSON format

Legacy 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 legacy 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 legacy 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 legacy object type

key property

The key property is a unique identifier for the legacy 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 legacy 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 legacy 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 legacy 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 - Legacy 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 Legacy Object Types endpoint to validate the schema of your legacy object types. The error messages returned by the endpoint are outlined in Schema validation reference for legacy 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 Legacy Object Types

• GET /api/sunshine/objects/types

Returns the account's legacy object types. Standard 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}/token:{api_token}

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"
    },
    {
      "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"
    }
  ]
}

Validate Legacy Object Types

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

Validates and generates a report of all the legacy 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}/token:{api_token}

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 Legacy Object Type

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

Returns the legacy 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 legacy object type that you define yourself

Code Samples

curl

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

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 Legacy Object Type

• POST /api/sunshine/objects/types

Creates a legacy object type describing the properties of the legacy 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}/token:{api_token}

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 Legacy Object Type

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

Rules for updating a legacy object type:

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

• Include the full, updated legacy 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 standard Zendesk object types (users, tickets, organizations, etc.). For example, the key in the request path can't be "zen:user:123".

Rules for updating a legacy object type schema:

• 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 legacy 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}/token:{api_token}

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 Legacy Object Type

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

Deletes the legacy object type with the specified key.

You can only delete a legacy object type if all legacy object records created from the type have been deleted. See Delete Legacy 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 legacy 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}/token:{api_token}

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