Zendesk provides many types of native data objects for storing and managing your customer data, including tickets, users, organizations, and more. We call these standard objects. However, standard objects can't provide every possible type of data object that your organization might want. With custom objects, admins can create custom objects to capture data that doesn't fit into those standard objects. Extending the Zendesk data model with custom objects enables you to seamlessly integrate your custom data with tickets, triggers, and Explore analytics.
Creating a custom object involves creating the actual object, defining the schema with custom fields, connecting the object to related objects, and granting agents access to the custom object's records. For your workflows, you may also want to reference custom objects in your triggers.
Creating a custom object
At a technical level, a custom object consists of a name, a key, and fields. The name and key are used to identify the object, and the fields create the schema of attributes for the object. Note that the schema doesn't contain any information about a specific instance of the object; it describes the information you can collect for this type of object. The creation of custom objects is recorded in the audit log.
Before you start creating custom objects, we recommend planning your custom objects workflow.
To create a custom object
- In Admin Center, click
Objects and rules in the sidebar, then select Custom objects > Objects. - Click Create object.
- Enter the following information:
- Name: The name of the object, as it will appear to agents.
- Plural display name: The plural version of the object name for use in navigation and lists.
- Object key: A unique identifier for this object.
- (Optional) Description: A description to help other admins understand the purpose of the object. If you exceed 92 characters, the description is truncated in the Objects page list.
- Click Create object.
- Click the Fields tab to add custom fields to the object. These create the schema or properties of the object.
-
Connect the custom object to related objects. Think of this as your data model, defining how this object is related to other objects and data within Zendesk.
Note: Not all relationships to a custom object should be defined on the object's side. You might need to create custom ticket fields, user fields, organization fields, or lookup fields on other custom objects. See Defining relationships.
- (Optional) Click Edit order to drag and drop the fields into the order you want them displayed to agents in the record preview, then click Save when you're done.
- Click the Permissions tab to review agent permissions to access the object's records. On Enterprise plans, you can configure agent access to object records. On Team, Growth, and Professional plans, agent permissions are predefined.
Defining a custom object's schema with custom fields
Before you can use a custom object you've created, you must add custom fields to it. These fields define the properties or schema of the custom object and will be used by agents when they create records. The list of fields is ordered alphabetically by name.
- In Admin Center, click Objects and rules in the sidebar, then select Custom objects > Objects.
- Click the name of the custom object you want to add a field to.
- Click the Fields tab, and then click Add field.
- Select the field type and enter a Display name.
- Verify that the Field key is the value you want it to be.
A field key enables the custom field to be referenced in the API. When you enter a name for the field, the field key is automatically populated. If you want the name and key to be different, you must edit the field key. You can't change the field key after you create the custom object field.
- Set other properties for your field. Options vary depending on the type of field you're adding.
- Click Save or Save and add another.
- Repeat steps 4–7 as needed.
Ordering an object's fields for the agent experience
While working tickets, agents can preview details about custom object records that are related to the ticket. All of an object's fields will be displayed in the record preview panel, but you might want to put the most important fields at the top for your agent's convenience.
- In Admin Center, click Objects and rules in the sidebar, then select Custom objects > Objects.
- Click the name of the custom object you want to add a field to.
- Click the Fields tab, and then click Edit order.
- Drag and drop the fields into the order you want them to appear.
- Click Save.
Understanding access to custom object records
When creating custom objects, you also need to understand how agents and customers can access the object and its records. For agents, there are two levels of access: visibility in the Custom object records page in the Agent Workspace and how an agent can interact with a custom object's records. Customers (also called end users) can also be granted permission to view, edit, add, and delete a custom object's records.
Agent permissions:
On all plans, you can determine whether an object will be visible on the Custom object records page for all agents and admins or only admins.
Then, you can use role-based permissions to determine the degree to which agents can interact with an object's records. On all plans, the ability to interact with custom object records is pre-defined for each system agent role. On Enterprise plans, you can use the Roles page in Admin Center to configure every custom role's access to each object. To view a summary of agent access to a specific object's records, use the Permissions tab within the custom object.
Customer permissions (EAP)
Customers (also called end users) can be granted permission to view, add, edit, and delete a custom object's records. Granting customers permission to view or otherwise interact with a custom object's records makes it possible for them to reference relevant custom object records directly when submitting a ticket rather than providing details in a comment and leaving it up to the agents to identify and select the relevant custom object record. Within the Zendesk user interface, it's possible to apply filters to lookup relationship fields to restrict the records displayed to only those relevant to the current user. However, because permissions are granted at the object level, technically customers are granted access to all of an object's records, not just those related to themselves.
For more information, see Configuring access to custom object records.
Adding object relationships
After you create the custom object and define its schema of custom fields, it's important to connect it to other standard or custom objects. Lookup relationship fields provide a way to define how the custom object relates to standard Zendesk objects (users, organizations, and tickets) and other custom objects. A lookup relationship can be described as source object → related object. The source object is the Zendesk object that contains the lookup relationship field (among other fields). The related object is the object specified by the lookup relationship field.
Adding related objects doesn't automatically create an association between two specific records. Instead, it describes the relationship and enables agents to associate records this way.
- another custom object
- a standard object
If you want the custom object to contain the lookup relationship field, use the following instructions. Alternatively, if you'd like a different object to include the custom object as a lookup relationship field, see Adding custom fields to your tickets, Adding custom fields to users, or Adding custom fields to organizations.
To add a relationship to a custom object
- In Admin Center, click Objects and rules in the sidebar, then select Custom objects > Objects.
- Hover over the custom object you want to add a field to, then click the option menu icon (
) and select Edit. - Click the Fields tab, and then click Add field.
- Set the Display name, Field key, and Description.
- Select a related object to list in the lookup relationship field.
This can be another custom object (
), a ticket (
), a user (
), or an organization (
). For example, if you select user as the related object, the lookup relationship field will display a list of Zendesk users. - Click Add filter to define one or more filters to reduce the number of options that the field can display.
You can filter objects by any number of tags or custom fields. For more information, see Filtering the fields options.
- Click Save or Save and add another.