CRM Setup

Use custom objects (BETA)

Last updated: May 28, 2020

In Beta

In HubSpot, there are four standard objects: contacts, companies, deals, and tickets.

When your business requires a different object, you should define a custom object, including creating its properties and customizing the associations between the custom objects and HubSpot's standard objects. Once a custom object is defined, you and your users can manage and use the object in HubSpot.

Currently, the only way to define a custom object is via API. Only HubSpot accounts that are enrolled in the private beta can define custom objects via API and have access to the API documentation.

View and create custom object records

Once you've defined your custom object, you can create new custom object records, view your custom object records in a table and filter the records based on their property values.


To access this on your desktop:

  • Click the name of the home and in the dropdown menu, select your custom object.
  • To create new custom object records, 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 Advanced.
    • 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 like other types of records.


On mobile, you can view custom object records that are associated to existing standard objects:

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

  • In your HubSpot account, navigate to your contacts, companies, deals, or tickets homes.
  • In the upper right, click Import.
  • Select File from computer, then click Next.
  • Select One file, then click Next.
  • Select One object or Multiple objects depending on your file. Click Next.
  • Select your custom object type. If you've selected Multiple objects, select the other object types included in your import file. Click Next.
  • Continue with the import steps.

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.

  • In your HubSpot account, click the settings icon settings in the main navigation bar.
  • In the left sidebar menu, click Properties.
  • Click the Contact properties dropdown menu and select [Custom object name] properties

  • Here, you can manage your custom object properties, including clicking Create property in the upper right to create a new property and hovering over existing properties and clicking Edit to update them.

Customize the custom object section in associated records

When your custom object is associated to another record, it appears in the right panel of that record's view.

You can customize the properties that show in this section.

  • In your HubSpot account, click the settings icon settings in the main navigation bar.
  • In the left sidebar menu, navigate to Properties.
  • Click the Records customization tab.
  • Locate and click your custom object name.
  • In the right panel, under the Secondary properties section, click the dropdown menus and select the properties you want displayed.
  • Click Save. These properties will be displayed in the custom object record section in associated records.

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.

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.