In the event that your business requires a relationship or process that is not included in the standard CRM objects, you can create a custom object. Enterprise accounts with super admin permissions can define custom objects via custom object settings or API.
It is possible to create properties, manage pipelines, and customize the associations between custom objects and other objects once they are defined. You can also use custom objects in other HubSpot tools, such as marketing emails, workflows, and reports.
Note: There are limits on the number of custom objects and properties you can have based on your subscription. Explore HubSpot Products & Services to find out what your limits are.
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.
Here are some questions to consider before you create your own object:
- Is it possible to organize your data using an existing CRM object and its properties rather than creating 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? Bulk marketing emails, for example, can only be sent to contacts.
- 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 gain a better understanding of your existing object relationships and data, navigate to Reports > Data Management > Data Model.
Glossary
Before creating a custom object, you should be familiar with a few terms and concepts.
- Object name: the title of your custom object. You'll be asked to define a plural name and a singular name. Companies, for instance, is the plural name of an object, and Company is its singular name.
- Primary display property: the property used to name a record of your object. This is the main identifying property for your object. Object index pages and records display it as the first column by default. A company's name, for example, is its primary display property.
- Label: a property name as it appears in your HubSpot CRM, such as on records or index pages. The label for the company property Company name, for example, is the name of the company. The labels of properties are subject to change, so integrations and APIs should not use them.
- Internal name: the internal value of a property which is used by integrations or APIs. Company name, for example, has an internal value of name. Integrations and APIs should refer to properties by their internal names, since they cannot be changed.
- Secondary properties: additional identifying properties for an object. Under the primary display property, these properties appear on the profile card. These quick filters appear on the index page for custom objects as well. The secondary properties for Companies are the domain name and phone number, while the secondary properties for Pets are the type of pet.
Examples
Listed below are examples of common use cases that illustrate how a custom object can affect an account's data, but they are not meant to be advice for every situation. Contact your Customer Success Manager to discuss whether a custom object is right for your specific use case.
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 the secondary display property. The user can view and search the pets they work with on an index page, save views based on pet type, associate contacts with pets, and manage activities and appointments within the 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 to each car. They create a Cars object with Model as its primary display property. To track cars as they move between stages such as new to inventory, in the purchase process, and sold, they create a custom object pipeline. When a car is sold, they view inquiry calls or emails logged to the record, and associate contacts and deals.
The following are examples where it is not recommended to create a custom object:
- A school has a database of students, parents, and teachers. To differentiate between parent and teacher contacts, they want to create custom objects. This is not a good use case because a custom object shouldn't replicate an existing CRM object. It is possible for a person to be both a parent and a teacher, resulting in overlapping data. Furthermore, the school couldn't send bulk emails to parents and teachers since they aren't contacts. They could instead include all contact types within the Contacts object and create a custom Contact type property with the options Student, Parent, and Teacher.
- Home improvement companies use HubSpot records to make internal requests to contractors. To keep track of all requests, they want to create a Notes object. This is not a good use case because custom objects shouldn't replace activities. There are more steps involved than tagging users, other records' activities cannot be automatically associated with the custom notes records, and they cannot use pre-built activity reports. In addition, if users update both the custom note record and another associated record, information about one project could be stored in multiple places. Rather than creating notes on records, they could associate them with other records, tag HubSpot users on them, and track note activity with pre-built reports.
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:
- Click the settings icon in the main navigation bar of your HubSpot account.
- Select Objects > Custom Objects from the left sidebar menu.
- Click Create a custom object in the center of the page if this is your first custom object. If you're creating an additional custom object, click Create custom object in the top right.
- Your custom object can be set up in the right panel as follows:
- 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).
- 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). Custom object records require this property.
- Property type: select the type of your primary display property, either Single-line text or Number.
- You can edit the property's internal name by clicking the edit pencil below the label, then click Save. Integrations or APIs use the internal name, which cannot be changed once the object is created.
- Select the checkbox to require unique values for the primary display property. If this option is enabled, users will not be able to enter the same value for multiple records (for example, for 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.
- 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. Once the object is created, the internal name cannot be changed. It is used by integrations and APIs.
- Click + Add property to add a secondary display property. Once you've set your first secondary property's label and type, this will appear.
- Click the delete delete icon next to a secondary property to remove it.
- Once you're done, click Create at the bottom of the panel.
Having defined a custom object, you can modify its settings as follows:
- When creating new custom object records manually, you can create and edit properties for your custom object.
- To define how your custom object is associated with other objects, create association labels.
- Utilize stages to track your custom object's processes by creating and managing custom object pipelines.
- Create custom object records.
- Your custom object records' sidebars, association cards, and board cards can be customized.
- Navigate to Reports > Data Management > Data Model to see how your custom object fits into your account's data model.
Edit or delete a custom object
Super admin users can edit a custom object's name and properties, or delete it from the HubSpot account once it has been created. 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 main 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. Navigate to a tool by clicking the name of an asset.
- Edit custom object: edit the object's singular and plural name. Click Save to confirm your changes. The internal name of the object cannot be edited. To edit the primary or secondary display properties, click Edit property label to navigate to your property settings.
- 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. It is not possible to delete a custom object that is currently being used by another tool, so you will need to remove references to the object from those tools before you can delete it.