Creating custom objects to integrate with custom data

Verified AI summary ◀▼
Create custom objects to capture data that standard objects can't. Define schemas with custom fields, set permissions, and establish relationships with other objects. Use templates for common objects or create unique ones from scratch. Customize record naming with manual entry or autonumbering. Enhance workflows by integrating custom objects with triggers and analytics, and manage access for agents and customers.






Location: Admin Center > Objects and rules > Custom objects >
Objects


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 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.
This article contains the following topics:
Creating a custom object
Defining a custom object's schema with custom fields
Configuring how a custom object's records are named
Understanding permissions for custom object records
Adding object relationships


Related articles:
Managing custom objects
Adding custom object records to capture
custom data
Using custom objects in 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.
Admins can create custom objects based on templates, which include pre-defined names,
fields, and relationships to other Zendesk objects, or from scratch. Before you
start creating custom objects, we recommend planning your custom objects workflow and reviewing the
custom object templates.
The creation of custom objects is recorded in the audit log.


Creating templated custom objects

Templates are provided to assist admins in creating several of the most common
types of custom objects. Each template can be used once and includes a
pre-defined but editable schema of custom fields. For details, see the Custom object templates reference.

To create a templated custom object
In Admin Center, click
Objects and rules in the sidebar, then select Custom objects >
Templates.
Click the name of the template you want to use: Contracts,
Orders, Products, Projects, or
Subscriptions. Each template can be used once. After a
templated object is published, the list of templates is split into
Available and Published. Only available templates
can be selected.

In the template preview dialog, click Get started.
Confirm the automatically populated Name is the name you want to
give your object, or update it as needed. This will be visible to
agents.

Confirm the Fields are correct for your custom object. Click
the x next to any fields you don't want.

Click Next.
Confirm the Object relationship fields that are automatically
defined for the template.
Select the Ticket form you want to add a lookup field to that
points to this new custom object.
Click Publish. After the object is published, you can add and
edit fields and manage other details about the object, such as how
the object's records will be named, whether records can have icons
or attachments, and the object's permissions.






Creating unique custom objects

If the templates aren't a good fit for your custom objects, you can create custom
objects from scratch manually.

To manually 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.
(Optional) Add image icons for individual records: Allow
admins and agents with permission to add and manage icons for
this object's records. When deselected after being selected,
existing icons will remain visible unless removed, but no new
record icons can be added.
(Optional) Add attachments to individual records: Allow
admins and agents with permission to add and manage attachments
for this object's records. When deselected after being selected,
attachments become inaccessible, but are preserved in case the
setting is turned on again in the future.



Click Create object.
Open the custom object's Name field (field key
standard::name), and specify how you want the object's records to be
named:

Name records manually: By default, agents must manually
enter a name for each record they add. Optionally, you can
Require unique record name if you want to use record
names as unique identifiers.

Name records with autonumbering: Select autonumbering if
you want records to be named with unique,
automatically-generated values based on the structure you
configure.


Note: Record naming settings can't be changed if records exist for
the custom 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 permissions for object
records. On Team, Growth, and Professional plans, agent
permissions are predefined.






Configuring how a custom object's records are named

Custom objects always have two fields: Name and External ID. Typically,
the name field is a text field that agents use to manually enter values for each
record they create. However, even with excellent training, this can still lead to
inconsistencies in the data and formatting of record names.
Admins have two options to ensure record names are unique and identifiable: requiring
unique record names or autonumbering. Requiring uniqueness prevents agents from
adding records until they enter unique names for them, while autonumbering provides
automatically-generated unique record names.
When autonumbering is turned on, you configure a prefix and starting number to
establish the naming pattern for the object's records. The autonumber value
increments by one for each new record. If you create records in excess of the
numeric format you specify, autonumbering of your records continues with additional
digits as necessary.
Note: You can only modify record name settings when no records
exist for the custom object.


To configure record naming
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 edit.
Click the Fields tab.
Click the display name for the field with a field key of
standard::name. By default, the display name is Name,
but it's possible to change this value. The field key can't be changed,
so it's a reliable identifier.

Under Record name type, configure how you'd like the object's records
to be named:

Name records manually: Requires agents to manually enter a
name.
If you want to enforce uniqueness, select Require unique
record name.



Name records with autonumbering: Automatically generate
unique record names. Specify the following details for the structure
of the auto-generated name:
Enter a Prefix of 1–30 characters that will be used
at the beginning of each record's name. The prefix
defaults to the first two letters of the custom object's
name.

Enter a Starting number for the initial record,
including leading zeros to define the total number of digits
used for autonumbering the initial records. Maximum of 9
digits. The starting number defaults to 0001.

Use the Preview pane on the right to review your
autonumbering format.




Click Save.





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.

To add custom fields to a custom object
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.
(Optional) If applicable, select Required to add or update custom object
records.
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.
Note: The first three custom fields in this
list are displayed as columns in the Custom object records list.


To reorder a custom object's fields
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 permissions for 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.
You can add relationships for custom objects to:
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.




//
const fast_path_style = document.createElement('style');
fast_path_style.innerHTML = `#article-body .fastpath{font-size:.9em;background-color:#f3f3f3;border:1px solid #d3d3d3;padding:10px 10px 8px;margin-bottom:16px}#article-body .fastpath::before{content:none!important}`;
document.head.appendChild(fast_path_style);
//

//
const ai_summary_style = document.createElement('style');
ai_summary_style.innerHTML = `#styled-article-body{padding:0 0 0}#article-body #docs-ai-summary{background-color:#f3f3f3;border:1px solid #d3d3d3;padding:10px 10px 6px;margin-bottom:16px}#article-body #docs-ai-summary #docs-ai-summary-toggle{font-size:.9em;font-weight:700;margin-bottom:4px;cursor:pointer;display:flex;justify-content:space-between;align-items:center}#article-body #docs-ai-summary #docs-ai-summary-toggle #up-triangle{margin-left:auto;padding-right:10px;display:none}#article-body #docs-ai-summary #docs-ai-summary-toggle #down-triangle{margin-left:auto;padding-right:10px}#article-body #docs-ai-summary #docs-ai-summary-content{font-size:.9em;padding-left:25px;padding-right:25px;margin-bottom:12px}`;
document.head.appendChild(ai_summary_style);

const toggleAISummary = () => {
const summary = document.getElementById("docs-ai-summary-content");
const upTriangle = document.getElementById("up-triangle");
const downTriangle = document.getElementById("down-triangle");
if (summary.style.display === "none") {
summary.style.display = "block";
upTriangle.style.display = "none";
downTriangle.style.display = "inline";
} else {
summary.style.display = "none";
upTriangle.style.display = "inline";
downTriangle.style.display = "none";
}
};

document.getElementById("docs-ai-summary-toggle").addEventListener("click", toggleAISummary);
//