Create and edit custom objects

If your business requires a relationship or process beyond the standard CRM objects, you can create a custom object. Users with super admin permissions in Enterprise accounts can define a custom object in the custom object settings or via API.

Once defined, you can create properties, manage pipelines, and customize the associations between custom objects and other objects. You can also use custom objects in other HubSpot tools, such as marketing emails, workflows, and reports.

Please note: depending on your subscription, there are limits on the number of custom objects and properties you may have. Learn more about your limits in our HubSpot Products & Services catalog.

Before you get started

Before you define a custom object, it's important to evaluate whether it's the correct option for your business and the quality of your data in HubSpot.

Some questions to consider before you create your own object include:

• Can you use an existing CRM object and its properties to organize your data instead of a custom object?
• Could there be any overlapping or inconsistent data between your custom object and an existing object?
• Are there any features unique to existing objects that you want to use? For example, bulk marketing emails can only be sent to contacts, not other objects.
• Are there any pre-built reports connected to existing objects that you want to use? For example, deal attribution reports and sales forecasts are connected directly to deals, not other objects.

To understand your existing object relationships and data, you can view an overview of your account's data model by navigating to Reports > Data Management > Data Model. For further guidance about when to create a custom object, refer to this lesson in the HubSpot Academy or reach out to your Customer Success Manager.

Glossary

There are some terms and concepts that you should be familiar with prior to creating a custom object.

• Object name: the title of your custom object. You'll be asked to define a plural name and a singular name. For example, Companies is a plural object name, and Company is the object's singular name.

• Primary display property: the property used to name a record of your object. This is the main identifying property for your object. By default, it appears as the first column on the object index page and in the top left on each record. For example, Company name is the primary display property for companies.

• Label: a property name as it appears in your HubSpot CRM, such as on records or index pages. For example, the company property Company name is the label. Property labels are subject to change so should not be used by integrations or APIs.
• Internal name: the internal value of a property which is used by integrations or APIs. For example, the Company name property's internal value is name. Internal names cannot change, so should be used by integrations and APIs to refer to the property.

• Secondary properties: additional identifying properties for an object. These properties appear on the profile card on a record under the primary display property. For custom objects, they also appear as additional quick filters on the index page. For example, the secondary properties for Companies are Company domain name and Phone number, while a custom secondary property for Pets could be Type of pet.

Examples

The examples below are based on common use cases to help you understand how a custom object can affect an account's data, but they are not meant as advice for every scenario. To discuss if a custom object is right for your specific use case, reach out to your Customer Success Manager.

The following are good examples of a custom object:

• A pet kennel wants to keep track of the pets they board, associate each pet with their owners, and keep track of activities related to each pet. They create a Pets object with Pet name as the primary display property and Pet type as a secondary property. They view and search the pets they work with on an index page, save views based on the pet type, associate contacts with a pet, and manage activities and appointments within a pet's record.
• A car dealership wants to maintain a database of the cars currently in their inventory or that they've sold, and to keep track of sales inquiries related each car. They create a Cars object with Model as the primary display property. They create a custom object pipeline to track cars as they move from stages such as new to inventory, in the purchasing process, and sold. They view inquiry calls or emails logged to each car's record, and associate contacts and deals when the car is being sold.

The following are examples where it is not recommended to create a custom object:

• A school has a database of students, parents, and teachers. They want to create custom objects for Parents and Teachers to help differentiate between the contact types. This is not a good use case because a custom object shouldn't replicate an existing CRM object. A person can be both a parent and a teacher, which would result in overlapping data. Additionally, the school couldn't send bulk emails to the parents and teachers because they aren't contacts. Instead, they could include all contact types within the Contacts object, and create a custom Contact type property with the options Student, Parent, and Teacher.
• A home improvement company uses notes on HubSpot records to make internal requests to their contractors. They want to create a Notes object to keep track of all requests. This is not a good use case because custom objects shouldn't replace activities. This adds extra steps compared to tagging users, other records' activities couldn't automatically associate to the custom notes records, and they couldn't use pre-built activity reports. Additionally, information about one project could be stored in multiple places if users are updating both the custom note record and another associated record, potentially leading to duplicate or conflicting data. Instead, they could create notes on records, associate them with other records, tag HubSpot users on them, and use pre-built reports to track note activity.

Create a custom object

If you're a super admin, you can create a custom object in your HubSpot settings or via API. To create a custom object in HubSpot:

• In your HubSpot account, click the settings settings icon in the top navigation bar.
• In the left sidebar menu, navigate to Objects > Custom Objects.
• If this is your first custom object, click Create a custom object in the center of the page. If you're creating an additional custom object, click Create custom object in the top right.
• In the right panel, set up your custom object:
  • To set your custom object's name:
    • Object Name (Singular): enter the singular title for your custom object (e.g., Pet).
    • Object Name (Plural): enter the plural title of your custom object (e.g., Pets).
  • Enter an optional object description that explains to your account's users what the object is and how it should be used.

• • To create the object's primary display property: 
    • Primary display property: enter a label for the property used to name a record of your object (e.g., Pet name for Pets). This property is required to create a custom object record.
    • Property type: select the type of your primary display property, either Single-line text or Number. 

• • • Click the edit pencil below the label to edit the property's internal name, then click Save to confirm. The internal name is used by integrations or APIs, and cannot be edited once the object is created.
    • Select the checkbox to require unique values for the primary display property. With this turned on, users will be unable to enter the same value for multiple records (e.g., for the object Orders, the primary property Order number should require unique values).

• • To create a secondary property for your custom object:
    • Secondary display property: enter a label for the property that is displayed below the primary property on a record (e.g, Type of pet and Owner phone number for Pets). Secondary properties are not required to create a custom object record, and can be added or removed later by editing the custom object.
    • Property type: the type of your secondary display property, either Single-line text or Number.
    • Click the edit pencil below the label to edit the property's internal name, then click Save to confirm. The internal name is used by integrations or APIs, and cannot be edited once the object is created.

• • To add an additional secondary display property, click + Add property. This will only appear once you've set a label and property type for your first secondary property.
  • To remove an existing secondary property, click the delete delete icon next to the property.

• Once you're done, click Create at the bottom of the panel.

Once you've defined a custom object, you can do the following in your custom object settings:

• Create and edit properties for your custom object, including setting which properties appear when manually creating new custom object records.
• Create association labels to define your custom object's associations with other objects.
• Create and manage custom object pipelines to use stages that track your custom object's processes.
• Create custom object records.
• Customize the properties that appear in your custom object records' sidebars, association cards, and board cards.
• View how your custom object fits into your account's data model by navigating to Reports > Data Management > Data Model.

Edit or delete a custom object

Once you've created a custom object, users with super admin permissions can edit its name and properties, or delete the object from the HubSpot account. You can edit and delete custom objects in your custom object settings or via API. To edit or delete in your settings: 

• In your HubSpot account, click the settings settings icon in the top navigation bar.
• In the left sidebar menu, navigate to Objects > Custom Objects.
• If you have multiple custom objects, select the object you want to edit or delete.
• On the Setup tab, click the Actions dropdown menu, then select from the following:

• • See where object is used: click to expand a tool group and view where in HubSpot the object is currently being used. Click the name of an asset to navigate to the tool.
  • Edit custom object: you can edit the object's singular name, plural name, and description, as well as add, edit, or remove display properties. You cannot edit the object or properties' internal names.
    • To edit the names of existing primary or secondary display properties, click Edit property label to navigate to your property settings.
    • To add an additional secondary property, click + Add property, then enter the property's name and select the property type.
    • To remove a secondary property, hover over the property and click the delete delete icon. If you remove a secondary property, it's still accessible on custom object records, but will no longer be displayed in the profile card or index page filters. If you want to delete the property, learn how to archive and delete properties in your property settings.
    • Click Save to confirm your changes.
  • Delete custom object: in the dialog box, select the checkbox to acknowledge you cannot restore a deleted custom object, then click Delete object to confirm. You cannot delete a custom object that is currently being used by other tools, so you'll need to remove references to the object from those tools prior to deleting.

Define custom object associations

Before you can add associations to custom object records, you need to create the associations in your settings. You can set up associations with contacts, companies, deals, and tickets, as well as with other custom objects and within the same custom object.

• In your HubSpot account, click the settings settings icon in the top navigation bar.
• In the left sidebar menu, navigate to Objects, then select Custom objects.
• If you have multiple custom objects, click the Select an object dropdown menu and select the custom object for which you want to define associations.
• Click the Associations tab.
• If you're adding the object's first association, click Create new association. To add an additional association, click the Select object associations dropdown menu, then select Create new association.
• In the dialog box, click the dropdown menu, then select the object with which you want to associate your custom object.

• Click Create.

You can now associate the records of the selected objects and create labels to describe the associations.