Getting started with legacy custom objects
The Zendesk REST API provides many object types for storing and managing your customer data, from tickets, users, organizations, and more. However, it can't provide every possible object type that your organization might need. For example, you might want to associate each new ticket with a retail store to get a better picture of the customer and of the store.
Use the Legacy Custom Objects API to define a new object type in Zendesk, then create objects from the new object type. A custom object can be just about anything, including service contracts, products, households, or customer visits. The API lets you create, read, update, or delete the objects.
You can use your legacy custom objects in your integrations or with the Zendesk Apps framework to extend existing Zendesk product functionality.
This guide shows you how to create and use legacy custom objects with the Zendesk API. The example takes an IT team that maintains the computers of company employees. The IT team wants to include details about each computer in the support tickets that employees submit when they have trouble with one of them. You can define a new computer object type in Zendesk, then create an object for each computer to store details about each one. You can also associate computers with tickets to monitor their reliability.
Enabling legacy custom objects
Legacy custom objects are only available to customers who were using them prior to September 2023 and can't be turned on now. If you're new to custom objects, see the latest Custom Objects APIs instead.
Defining a legacy custom object type
At its most basic, a legacy object type consists of a key and a schema that describes the data. The key is the name you want to use to identify the object type. Example: "computer".
After discussions with the IT team, you agree to define a legacy object type for all the personal computers (PCs) in the company. Each PC should be represented as an object record with the following very basic properties:
| Name | Type | Mandatory | Comment |
|---|---|---|---|
| id | string | yes | Unique identifier assigned to the computer by IT |
| model | string | no | Make and model of the computer |
| is_laptop | boolean | no | Whether or not the computer is is_laptop |
These details make up your schema. Notice that the schema doesn't contain any PC information. It just describes that information. To learn more, see Creating a schema for a custom object.
To create the "pc" object type, include the schema in a POST request to the following endpoint:
POST /api/sunshine/objects/types
Note: The Legacy Custom Objects API introduces a new Zendesk API design. For example, the paths don't have a version number and the resources don't have .json extensions. The existing v2 APIs are unaffected.
Try it yourself
-
Save the following JSON object in a file named pc_object_type.json.
{"data": {"key": "pc","schema": {"properties": {"id": {"type": "string","description": "Unique identifier assigned to the computer by IT"},"model": {"type": "string",