CRM Setup

Use custom objects

Last updated: February 16, 2021

Applies to:

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

In HubSpot, there are four standard object types (i.e., contacts, companies, deals, and tickets) and other object types such as marketing events

When your business requires a different object, you can consider defining a custom object. This includes creating its properties and customizing the associations between the custom object and other objects, such as HubSpot's standard objects.

Once a custom object is defined, you and your users can manage and use the object in HubSpot. For example, you will be able to:

Currently, the only way to define a custom object is via API. Check out our developer documentation.

Please note: depending on your subscription, you may have a limit on the number of custom objects and properties you may have. Learn more about your limits in our HubSpot Products & Services catalog. You may purchase additional capacity by reaching out to a member of our team.

View and create custom object records manually

Once you've defined your custom object via API as per our developer documentation, you can create new custom object records, view your custom object records in a table, and filter the records based on their property values. You need Custom Objects Access to do this.


To access this on desktop:

  • In the upper left, click the name of the home. In the dropdown menu, select your custom object. This will bring you to your custom objects home.
  • To create a new custom object record, click Create [custom object] in the upper right. In the right panel, enter its property values and click Create.
  • To filter your custom object records:
    • Click the dropdown menu with the property you want to filter by. If it isn't available, click More filters and in the right panel, select the property you want to use to filter your records.
    • Specify your criteria.
    • Once done, 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.


On mobile, 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 to the record, tap the Beta tab.
  • Tap the custom object to view its property values. These values are read only.

Import custom object records

Once you've defined your custom object, you can import its records to your HubSpot account. Once you've set up your import file, you can import your custom object records:

Please note: if you're importing values for your custom object's date properties, it must be formatted mm/dd/yyyy.

Customize your custom object

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. Property field types that are not available for custom objects are Score and File. 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 icon settings 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.

Merge custom object records

If you've created duplicate custom objects, you may want to merge them.

  • In the upper left, click the name of the home. In the dropdown menu, select your custom object. This will bring you to your custom objects home.
  • Click the ticket name that will be the primary ticket record.
  • In the left panel, click the Actions dropdown menu and select Merge.
  • Search for the ticket you want to merge into the primary ticket. Once you've selected your secondary ticket, click Merge.
  • You will be notified that the merge is in progress. It can take up to 30 minutes for all of the ticket 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 most recent value for each property is 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 tickets.

Make a call from a custom object

If you have registered your phone number with HubSpot, you can make a call from your custom object records. Keep in mind the following differences between making a call from a custom object instead of a standard HubSpot object:

  • You cannot make calls to a custom object using a third-party calling provider. To make a call using a third-party calling provider, navigate to a contact or company record.
  • When making a call, you can only choose from the associated records that are listed in the Call dropdown menu. You cannot search for another object record to call. If you want to make a call to another associated record that is not listed, you must navigate to that record in your account.

When viewing a custom object record, you can make a call by clicking the calling call icon in the left panel


Learn more about making calls with HubSpot in the articles below:

Automate custom object records with workflows

Create custom object records with workflows

Once you've created your custom object, you can create its 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.

  • In the Type of record to create dropdown menu, select your custom object.
  • Set up the rest of the property details for your custom object records:
    • 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 a [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].
    • 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.

Enroll custom object records in workflows

You can create a workflow for your custom object records and enroll them to automate certain actions. Because custom objects are still in beta, some workflow actions and enrollment triggers may not be available.

To create a custom object workflow:

  • 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:

  • In the toolbar, click Personalize.
  • In the Type dropdown menu, select your custom object and below, select your custom object property.
  • Enter a default value.
  • Click Insert to add it into the email. Continue with saving your automated marketing email.

Report on your custom objects

You can report on your custom object records based on their properties. Because custom objects are still in beta, some reporting functions and criteria may not be available.

Currently, only custom single object reports are available for custom objects. To create such a report:

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