A custom object can be just about anything, including a product, a service contract, or a customer visit. You can create custom objects in the Zendesk Admin Center or with theSunshine API, then use your custom objects to tailor your Zendesk account to fit your business needs. You can control access to your custom objects by specifying the permissions that apply to each object.

This guide shows you how to define a custom object in Admin Center. It uses a vacation rental business as an example. Customers can report problems with a rental property by calling or starting a chat with the business's support team, which creates tickets for them. The business would like to associate each ticket with a rental property in Support to help agents provide better customer service. The business would also like to use the information to get a better picture of the customer experience at each location to plan property improvements.

The following video provides an overview of custom objects in Admin Center, but note that the interface has a new look now:

Sunshine custom object enhancements (6:02)

Custom objects are available on all Zendesk Suite plans and Support.

To enable custom objects in your account

1. InAdmin Center, clickObjects and rulesin the sidebar, then selectCustom objects > Objects．
2. ClickGet started．
3. 激活自定义对象。

For the vacation rental business, you want each rental property to be represented by one custom object record in Zendesk. If the company buys another vacation property, you'd simply add an object record to represent it.

Rental properties share certain attributes. For example, each property has an address, a weekly rent, a number of bedrooms, and more. The attribute values vary by rental property. One might be a two-bedroom apartment in Lisbon for $600 a week while another might be a three-bedroom house in Aspen for $1100 a week.

Similarly, Sunshine custom objects of the same type (such as a "rental property" type) all share the same attributes. The attributes of a custom object are defined in a blueprint called anobject type．

At a technical level, an object type consists of akeyand aschemathat describes the attributes. The key is the name you want to use to identify the object type. You enter the key in the Object name field when creating an object type. Example: "rental_property".

You can define all kinds of attributes for a rental property. To keep the example simple, you decide to use the following attributes for a new custom object with a key called "rental_property":

This is your schema. Notice that the schema doesn't contain any information about any specific rental property. It just describes that information. To learn more, seeCreating a schema for a custom object．

To create an object type

1. InAdmin Center, clickObjects and rulesin the sidebar, then selectCustom objects > Objects．
2. ClickAdd object．
3. ForObject name, enter the object's key as "rental_property".

   

   Your key must meet the following requirements:

   • Be unique
   • Only contain alphanumeric characters (a-z, 0-9), underscores (_) and dashes (-)
   • Have a minimum of 2 characters and maximum of 32 characters
4. ClickAdd Propertyto define a new property.
5. Enter the following values in the Add Property form in the right panel:
   • Name- id
   • Type- string
   • Description- Unique identifier assigned by the business to the rental property
   • Required- checked

   

6. ClickAdd Propertyif you want to continue building your schema.
7. Enter the values of the second property in the Add property form.
8. Keep clickingAdd Propertyto add the other properties in the schema table.
9. ClickSave．

After re-opening it, the object type should look as follows:

Once you have saved your object, you can set role-based access permissions to define the permissions of agents and end users for object or relationship records. SeeSetting roles and permissions for objects．

Once you create the rental property object type in Admin Center, developers in your organization can use the Sunshine API tocreate an object recordfor each of the business's rental properties. They can also use the API to read, update, and delete the records. Object records are nothing more than database records with defined properties.

The data that a developer includes in the API request to create a rental property record is defined by the object type you defined, which for the "rental_property" type consists of attributes named "id", "bedrooms", "address", "country", "cleaning_service", and "cleaning_service_phone". Example:

{ "data": { "type": "rental_property", "attributes": { "id": "fr-021", "bedrooms": 2, "address": "11 rue Laurier, Saint-Tropez", "country": "France" "cleaning_service": "tropez-nettoyage" "cleaning_service_phone": "011.33.06.55.47.54.74 " } } }

If you want to retrieve the records later, a developer can use several different endpoints to retrieve them. SeeObject Recordsin the API docs.

If the business makes a change to a rental property such as hire a new cleaning service, a developer can use theUpdate Object Recordendpoint to update the object record for that rental property.

If the business sells the rental property, a developer can use the删除Object Recordendpoint.

If the business buys another rental property, a developer can use theCreate Object Recordendpoint.

To use the rental property data in more meaningful ways, you can establish a relationship between your "rental_property" type and other object types in Zendesk. For example, information about a particular rental property is not very useful to a property manager unless it's associated with tickets that guests have submitted about the property. Note that tickets are just another object type in Zendesk.

Custom objects support several relationships between object types:

• One-to-one- Both object types can have only one record on either side of the relationship. For example, a ticket would only be associated with one rental property, and a rental property would only be associated with one ticket. This isn't a viable option in the vacation rentals example. One rental property can have more than one ticket associated with it.

• One-to-many——每个对象的第一个对象类型有关none, one, or many objects of the second object type. For example, a rental property can be associated with none, one, or many tickets.

• Many-to-many——每个对象的第一个对象类型有关none, one, or many objects of the second object type, and each object of the second object type relates to none, one, or many objects of the first object type. You define a many-to-many relationship type with two one-to-many relationship types.

A relationship can be between:

• two custom object types (between the "rental_property" and a "guest_contract" object type, for example)
• one custom object type and any of the following Zendesk object types: tickets, users, articles, organizations, groups, or chats
• two Zendesk object types

Just as an object type is a blueprint for creating object records, a relationship type is a blueprint for creating relationship records between two specific object types. For the vacation rentals example, you want to define a "rental property has many tickets" relationship type between your custom "rental_property" object type and the native Zendesk ticket object type.

If you use Zendesk Sell you can also create a relationship between Zendesk Sell objects such as lead, deal, or contact.

Defining a relationship type doesn't create an association between two specific records. It just describes the relationship. After defining your relationship type, you can create a relationship record that associates a specific ticket to a specific rental property. As these relationship records accumulate, with each record associating one ticket to one rental property, you'll start to get a clearer picture of the problems at each rental property. Sunshine can group tickets by rental property based on the relationship type you defined: one rental property has many tickets.

To create a relationship type

1. InAdmin Center, clickObjects and rulesin the sidebar, then selectCustom objects > Relationships．
2. ClickAdd relationship type．
3. ForRelationship name, enter "rental_prop_has_many_tickets".

   Your key must meet the following requirements:

   • Be unique
   • Only contain alphanumeric characters (a-z, 0-9), underscores (_) and dashes (-)
   • Have a minimum of 2 characters and maximum of 32 characters
4. Select the following values from the menus:
   • Source- rental_property
   • Type- 1:Many
   • Target- zen:ticket

   The page should look as follows:

   

5. ClickSave．

Once you've defined a relationship type, you can start associating related records based on the relationship type.

You associate a record of one object type to a record of another object type by creating arelationship record(not to be confused with a relationship type). For your vacation rentals business, you can create a relationship record between a particular ticket and a particular rental property.

A relationship record consists of the ids of the two related object records and their relationship type. The relationship record doesn't contain any actual information about the renter's issue or the rental property. It just contains the id of the ticket record and the id of the rental property record. Sunshine uses these ids to retrieve the related records.

The relationship record is governed by a relationship type you created -- the one-to-many type named "rental_property_has_many_tickets" where each ticket can be associated with only one rental property, but each rental property can be associated with many tickets.

To create a relationship record, a developer on your team can make a POST request to theCreate Relationship Recordendpoint. The JSON object that the developer includes in the request must specify the relationship type as well as the ids of the "source" and "target" objects. Example:

{ "data": { "relationship_type": "rental_property_has_many_tickets", "source": "1c771ee0-2c3f-11e7-bf60-e5c3f630b5aa", "target": "zen:ticket:35437746" } }

A developer on your team can use theList Relationship Records by Object Recordendpoint to retrieve the relationship records. For example, the developer could get all the related tickets for the rental property with a record id of "5d0daa84-aec0-11e7-9a70-416881d66b6d".

Example response:

{ "data": [ { "id": "c5477230-2e98-11e7-acd9-9dbd5d6450d8", "target": "zen:ticket:35438118", "ref": "/api/v2/tickets/35438118" }, { "id": "5d3484b5-aec6-11e7-9a70-a12d6a7d800c", "target": "zen:ticket:35437746", "ref": "/api/v2/tickets/35437746" } ], "links": { "previous":null, "next":null } }

In the example, the rental property has two tickets, 35438118 and 35437746, associated with it. You can use the information to view the tickets.

You can use your custom objects and relationship records to solve real-world problems, to improve existing processes, or simply to get a better picture of your customers. For example, a developer on your team could use your rental property custom object to build a Zendesk app that shows details about a rental property to the agent working on a ticket.

The app could alsocreate a relationship recordbetween the ticket and a rental property when the agent changes the ticket status fromnewtoopen．You could then use the Sunshine API to generate reports listing all the tickets for each rental property and use the information to plan property improvements.

You can delete a custom object type or relationship type in Admin Center, but not a custom object record or relationship record. This section describes how to delete a custom object type or relationship type in Admin Center. You can not delete an object type/relationship if it has existing relationships or records associated with it. Todelete a custom object recordor adelete a relationship record, use the Sunshine API.

To delete a custom object type

1. InAdmin Center, clickObjects and rulesin the sidebar, then selectCustom objects > Objects．
2. Hover your mouse over the custom object type you want to delete, then click the trash can icon next to the type.

   

3. When a confirmation message appears, click删除to confirm the deletion.

To delete a relationship type

1. InAdmin Center, clickObjects and rulesin the sidebar, then selectCustom objects > Relationships．
2. Hover your mouse over the relationship type you want to delete, then click the trash can icon next to the type.

   

3. When a confirmation message appears, click删除to confirm the deletion.