What's my plan?

Available on all Suite plansAvailable on Support Enterprise plans

Quick Look: 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 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.

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. 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

  1. In Admin Center, click Objects and rules in the sidebar, then select Custom objects > Objects.
  2. Click Create object.
  3. 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.

  4. Click Create object.
  5. 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.
  6. Click the Fields tab to add custom fields to the object. These create the schema or properties of the object.
  7. 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.
  8. (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.
  9. 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
  1. In Admin Center, click Objects and rules in the sidebar, then select Custom objects > Objects.
  2. Click the name of the custom object you want to edit.
  3. Click the Fields tab.
  4. 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.

  5. 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.

  6. 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
  1. In Admin Center, click Objects and rules in the sidebar, then select Custom objects > Objects.
  2. Click the name of the custom object you want to add a field to.
  3. Click the Fields tab, and then click Add field.

  4. Select the field type and enter a Display name.
  5. 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.

  6. Set other properties for your field. Options vary depending on the type of field you're adding.
  7. Click Save or Save and add another.
  8. 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.

To reorder a custom object's fields
  1. In Admin Center, click Objects and rules in the sidebar, then select Custom objects > Objects.
  2. Click the name of the custom object you want to add a field to.
  3. Click the Fields tab, and then click Edit order.
  4. Drag and drop the fields into the order you want them to appear.
  5. 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

  1. In Admin Center, click Objects and rules in the sidebar, then select Custom objects > Objects.
  2. Hover over the custom object you want to add a field to, then click the option menu icon () and select Edit.
  3. Click the Fields tab, and then click Add field.
  4. Set the Display name, Field key, and Description.
  5. 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.

  6. 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.

  7. Click Save or Save and add another.
Powered by Zendesk