Skip to content
CRM Setup

Use custom objects

Last updated: November 10, 2021

Applies to:

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

In HubSpot, there are four standard CRM objects:  contacts, companies, deals, and tickets. There are also HubSpot-defined objects, such as products and calls.

When your business requires a different object, you can define a custom object (e.g., Pets as an object for a pet kennel). Once defined, you can create properties and customize the associations between custom objects and other objects.

The only way to define a custom object is via API. Learn more in our developer documentation.

Using your custom object, you and your users can also:

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.

Create custom object records

Once you've defined your custom object via API with the steps in our developer documentation, you can create new custom object records manually, with an import, or using workflows.

Manually create custom object records

  • Navigate to your records:
    • Contacts: In your HubSpot account, navigate to Contacts > Contacts.
    • Companies: In your HubSpot account, navigate to Contacts > Companies.
    • Deals: In your HubSpot account, navigate to Sales > Deals.
    • Tickets: In your HubSpot account, navigate to Service > Tickets.
  • In the upper left, click the name of the index page. In the dropdown menu, select your custom object. This will bring you to your custom objects index page.
  • Click Create [custom object] in the upper right.
  • In the right panel, enter property values for your new record, then click Create.

Import custom object records

Once you've set up your import file, you can import your custom object records:

Once defined, you can also sync custom object records from Salesforce. Learn how to set up and use the Salesforce custom object sync.

Create custom object records with workflows

Once you've defined your custom object, you can create records using workflows. You can also create workflows that are based on your custom object.

Please note: to create custom object records in workflows, the custom object must have a relationship with the workflow's object type. For example, if your custom object doesn't have a defined relationship with the contact object, you can't create custom object records in contact-based workflows.

To create custom object records with workflows:

  • In your HubSpot account, navigate to Automation > Workflows.
  • Click the name of a workflow, or create a new workflow.
  • In the workflow editor, click the plus icon + to add a workflow action.
  • In the right panel, select Create record.

    workflow-create-record
  • Click the Type of record to create dropdown menu, then select your custom object.
  • Set up the rest of the property details for your custom object records:
    • Enter a value for any required properties. 
    • To set additional properties for each created record, click Set another [object] property.
    • To copy a property value from enrolled records to your custom object records, click Copy a property to an [object] property.
  • Set up your custom object record associations:
    • By default, a custom object record created by a workflow will be associated with the record that was enrolled into the workflow.
    • To copy all timeline activity from the enrolled record to the custom object record, select the Add timeline activity from the enrolled [object] to the [custom object] checkbox.
    • Depending on the workflow type, other object association options may be available. Select the object association checkboxes to associate created records with these objects.
  • Click Save.

Manage custom object records

Users with Custom Objects Access permission can also view custom object records in a table and filter the records based on their property values.

Desktop

To access your custom object on desktop:

  • Navigate to your records:
    • Contacts: In your HubSpot account, navigate to Contacts > Contacts.
    • Companies: In your HubSpot account, navigate to Contacts > Companies.
    • Deals: In your HubSpot account, navigate to Sales > Deals.
    • Tickets: In your HubSpot account, navigate to Service > Tickets.
  • In the upper left, click the name of the index page. In the dropdown menu, select your custom object. This will bring you to your custom objects index page.
  • To filter your custom object records:
    • Click the default property dropdown menus and select the values that you want the displayed records to have. HubSpot will display at most 4 default properties which are chosen in the following order:
      • the object’s defined primary display property (typically the name of the object);
      • Object create date;
      • Object last modified date;
      • if they exist, a secondary property that you have set for your custom object;
      • if they exist, a search property you have defined for your custom object (this will only appear if there are no secondary properties);
      • if they exist, a required property you have defined for your custom object (this will only appear if there are no secondary or search properties).
    • If a property isn't visible, click More filters. In the right panel, select the property.
    • Specify your criteria.
    • Once you have specified your criteria, click Apply filter.
  • To view a custom object record, click its name. You'll be brought to its record view.

You can also bulk edit your custom object records.

Mobile

On the HubSpot mobile app, you can view custom object records that are already associated to existing standard object records:

  • On your device, tap the HubSpot mobile app.
  • In the bottom navigation menu, tap Contacts to access your contacts or companies, or Deals to access your deals.
  • Tap the contact, company or deal that you want to view.
  • To view the custom object associated with the record, tap the Associations tab.
  • Tap the custom object to view its property values. These values are read only.

Merge custom object records

If you've created duplicate custom object records, you can merge them.

  • Navigate to your records:
    • Contacts: In your HubSpot account, navigate to Contacts > Contacts.
    • Companies: In your HubSpot account, navigate to Contacts > Companies.
    • Deals: In your HubSpot account, navigate to Sales > Deals.
    • Tickets: In your HubSpot account, navigate to Service > Tickets.
  • In the upper left, click the name of the index page. In the dropdown menu, select your custom object. This will bring you to your custom objects index page.
  • Click the custom object name that will be the primary custom object record.
  • In the left panel, click the Actions dropdown menu and select Merge.
  • Search for the custom object record you want to merge into the primary record. Select your secondary custom object record, then click Merge.
  • You will be notified that the merge is in progress. It can take up to 30 minutes for all of the custom object activities to sync.

Once merged, any associated records will be associated with the resulting record. The original secondary record will be unenrolled from all workflows and the resulting record will not be enrolled in any new workflows, even if the property values match any enrollment triggers.

In general, the property values of the primary record are adopted by the resulting record. The exceptions are:

  • Create Date: the value for the older record is maintained.
  • Object ID: the resulting record will have a new value that is different from the primary and secondary custom object records.

Manage custom object properties

Create properties for your custom object

Once you've defined your custom object, you can create and edit properties for your custom object in HubSpot. Score and File property field types are not available for custom objects. You can also set up which fields appear and are mandatory when a user creates a new custom object record.

To access your custom object properties for editing:

  • 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 more than one custom object, in the top left, click the dropdown menu and select the name of the custom object you want to edit.
  • On the Setup tab, click Manage [custom object] properties to navigate to the property settings page for your custom object.

Customize the custom object section in associated records

When your custom object is associated to another record, it appears in the record's right panel. Learn how to customize the properties that appear in this section.

Enroll custom object records in workflows

You can create a workflow for your custom object records and enroll them to automate certain actions. 

  • In your HubSpot account, navigate to Automation > Workflows.
  • In the upper right, click Create workflow.
  • In the left panel, select the Start from scratch tab. Then, select [Custom object name]-based.

Personalize automated marketing emails with custom object properties

Once you've created your properties, you can personalize your automated marketing emails with your custom object property values. Once you've created an automated marketing email:

Please note: the web version of your email will not render personalization tokens that use a property value from a custom object.

Report on your custom objects

You can report on your custom object records based on their properties. To create a single object report for your custom object:

  • In your HubSpot account, navigate to Reports > Reports.
  • In the upper right, click Create custom report.
  • In the left panel, select Single object.
  • Select your custom object, then in the top right, click Next.