Skip to content
CRM Setup

Create a custom object (BETA)

Last updated: August 19, 2022

In Beta

Applies to:

Marketing Hub Enterprise
Sales Hub Enterprise
Service Hub Enterprise
Operations Hub Enterprise
CMS Hub Enterprise

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.

If you're a user with super admin permissions, opt your account into the Manage and Visualize Your Data Model beta to gain access to this functionality.

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

For more guidance about organizing your data and when to create a custom object, refer to this lesson in the HubSpot Academy. To discuss if a custom object is right for your account, you can also reach out to your Customer Success Manager.


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




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 notes and engagements related to each specific 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 all the cars they have in their inventory or have sold, and want to keep track of inquiries related to selling 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 the 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, their 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 could be both a parent and a teacher, which would result in overlapping data. 
      • The school would be unable to send bulk marketing emails to the parents and teachers because they are not contacts.
    • Instead, they can 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 engagements. It adds extra steps compared to tagging users, other record's activities wouldn't automatically associate to notes records, and they wouldn't be able to use pre-built activity reports.
      • Information about one improvement project may be stored in multiple places if users are updating both the note record and the associated contact record. This can lead to duplicate or conflicting data.
    • Instead, they can continue to create notes on standard CRM object records, associate them with other related records, and tag other HubSpot users on them. They can also use the pre-built activity reports to track their note activity.

Create a custom object

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

  • In your HubSpot account, click the settings settings icon in the main navigation bar.
  • In the left sidebar menu, navigate to Objects > Custom Objects.
  • Click the Create a custom object button. If you've previously created a custom object, the Create custom object button will appear 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).
    • 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.
      • 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.
    • To remove a secondary property, click the delete delete icon next to the property.


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

Next steps

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

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.