Getting Started with Custom Objects in HubSpot

To start using custom objects, you'll need a HubSpot account with at least one Enterprise Hub and a developer or technical resource who can help define your custom object using HubSpot’s APIs. If you need help, you can work with a HubSpot Solutions Partner or get in touch with HubSpot's Technical Consulting team.

Ready to get started?

View the Documentation

What Is an Object?

HubSpot is, at its core, a database with tools that help your team to get work done and grow your business. An object is a data structure within the database that we use to store information. In HubSpot, there are four standard objects: contacts, companies, deals, and tickets.

In HubSpot, contacts store information about an individual person. From marketing automation to smart site content, the lead-specific data found in contact records helps users leverage much of HubSpot's functionality. Learn more. 

In HubSpot, company records store information about an individual business or organization. Multiple contacts can be associated with a company to represent its organizational makeup. Learn more. 

In HubSpot, deals represent revenue opportunities with a contact or company. They’re tracked through pipeline stages, eventually resulting in the deal being won or lost. Learn more. 

In HubSpot, tickets represent customer requests for help or support. Learn more. 

There are also some additional objects that are used to store associated data to these standard objects:

  • Products: In HubSpot, products represent goods or services you sell. Building a product library allows you to quickly add products to deals, generate quotes, and report on product performance.
  • Tasks: In HubSpot, tasks represent an activity that you need to complete. Tasks can be created automatically via workflows or sequences and can be used to monitor rep productivity. 

What Is a Custom Object?

In some cases, you may want to store other types of data in HubSpot -- data that’s not exactly a fit for one of these standard objects. In this case, it may make sense to create a new custom object to store that data, and associate it with one of your standard objects. Creating a custom object gives you the power to store many types of data in HubSpot much like we store information about people, businesses, transactions, and tickets. There are an infinite number of use cases for custom objects, but to give you some simple examples, you can use custom objects in HubSpot to store data such as:

  • Shipment Information associated with Deals
  • Physical Assets or Properties associated with Contacts and Companies
  • Contracts or Licenses associated with Companies
  • App Usage Data associated with Companies

While some of these use cases can be solved by storing data on the standard objects as a custom property, it may not be the most appropriate solution. Custom objects give you the flexibility to architect your data on HubSpot exactly as it appears in the real world. 

Adding custom objects can unlock more value from your HubSpot portal, but it can also create more complexity. To help you make sure that custom objects are the best option, we’ve created a simple, 5-step framework.

Custom Objects 5-Step Framework

This 5-step framework will walk you through the options for architecting your business on HubSpot to ensure you’re designing your database in a way that makes the most sense for your business.

1. Design: Do I Need a Custom Object?

While adding a custom object to your portal might seem like the right next step, there are other customizations you can implement instead of, or alongside a custom object.  Depending on your use case, these other options may be a good fit as well:

Standard Objects - Whenever possible, represent a person, business, transaction or service request with a standard object already available in your HubSpot portal.

Features: Using Contacts, Companies, Deals, and Tickets will always provide the most relevant features. For example, HubSpot can only send emails to ‘Contacts.’

Limitations: A ‘Deal’ can only be associated with one ‘Company’, a ‘Contact’ can only be associated with one ‘Company’, and there are no formal roles or association types at this time.

Custom Properties - Store data directly on a Contact, Company, Deal or Ticket by creating custom properties that fit your business.

Features: Associated with an object in a 1:1 relationship, visible on the Records View, and can be used for segmentation, automation, and reporting.

Limitations: Not a fit for 1:Many relationships.

Custom CRM Cards - Allow your team to see external data in HubSpot using Custom CRM Cards.  This will allow your team to be able to access data stored in another system from within HubSpot.  This can help add context during a meeting or support request.

Features: Allows external data to be visible in HubSpot on the sidebar of an object record view, data is read-only within HubSpot.

Limitations: No list segmentation, automation, or reporting capabilities.  Data can only be updated in the source system.

Timeline API - Store date/time specific events to an object in a portal to use for timeline visibility, triggered events, and reporting using the Timeline API.

Features: Associate time-specific events to an object. View that data on the record view and, for data associated with a contact, use that data for segmentation and automation.
Limitations: Not a completely customizable object structure, and not a good fit for data that is non date-based.

Now that you understand some of the other database customizations you can make, you can better decide how to architect your business on HubSpot. In many cases, you may leverage both custom objects and one of the items above, so it’s important to find the best solution for your use cases.

2. Define: How Do I Get Started Creating a Custom Object?

It's often helpful to draw out your database to clarify exactly how your object structure should be designed.  A common way to draw this out is by using an Entity Relationship Diagram, or ERD.

In an ERD, objects are drawn as boxes, which display the object's name and a few key properties. These boxes are connected to each other by lines to represent the relationships between the objects. To add even more detail, a standard system of symbols called "crow's foot notation" is used on each end of the connecting lines to show how many of each object can be associated to another object. There are three symbols in crow's foot notation: A circle (meaning "zero"), a line (meaning "one"), and a crow's foot (meaning "many"). If you look at the HubSpot ERD below, you can see these symbols in action:

If you look at the line connecting the contact box to the company box, you'll see two symbols at the end of each line. These represent the minimum and maximum of these associations. On the contact side of the line, you'll see a crow's foot (that's the three little lines at the very end of the line) and a circle. Remember, the circle means "zero" and the crow's foot means "many," so this means you can have zero contacts or several contacts associated with a single company. On the company end of the line, there's a circle (zero) and a line (one), meaning you can have one or zero companies associated with a contact, but you can't have more than one. We've left some space in the ERD for a custom object. You can use this as a jumping off point for a conversation with your team about how your custom object should connect to the other objects inside HubSpot.

Next, you’ll want to decide what data is being stored on the object, how the object data should be displayed in the portal, and how it relates to other objects your business uses.  This is a good conversation to have with your developer or technical resource and other data users at the company.

Some of these parameters are:

  • Name - A unique internal name for your object.
  • Labels - Singular and plural labels for an object type for display in the UI.
  • Primary Display Property - The name of the primary property visible in the UI.
  • Secondary Display Property - The name(s) of the secondary properties visible in the UI.
  • Associations - The other objects that your custom object can be associated with.  All associations to custom objects are many:many at this time.
  • Properties - Defined properties to store data on your custom object.  An object requires at least one property.  More information on property types can be found here.



In the above example, company name (HubSpot) is shown here as the Primary Display Property for this company record.



In the above example, the properties listed here are the Secondary Display Properties for this company record.

Currently, the only way to define a custom object is via API. HubSpot Enterprise customers and third-party developers can now use the public API to define custom objects, properties, and associations, and leverage HubSpot’s powerful CRM platform to grow their business.

Your developer can get started by creating a test portal and exploring our custom object API documentation.

3. Create: How Do I Add Data and Create Records on a Custom Object?

Now that your custom object is defined,  you’re ready to start adding new custom object records to HubSpot. Just like standard objects, you have three options to add data to your portal:

  1. Manually create records in your portal using the HubSpot UI.
  2. Import data via spreadsheet.
  3. Migrate data programmatically via HubSpot API.

If you need to migrate data programmatically, or you expect that you will need to keep your data in sync with another system, your developer team will want to explore some additional endpoints. If you’re looking for more hands-on support, reach out to a HubSpot Solutions Partner who can help you with your implementation. If your developer team needs additional guidance you can work with HubSpot's technical consultants.

4. Implement: What Can I Do With a Custom Object in HubSpot?

 Currently, custom objects can be used to... 

  • Store information, and associate it with other records in your portal.
  • Trigger automation in workflows.
  • Create single-object or cross-object reports.
  • Import data.
  • Personalize content.
  • Save table views
  • And more…

At this time, custom object data cannot be used with our native HubSpot-Salesforce Connector.

5. Maintain: Keeping Your Data up to Date

Similar to creating records in your portal, there are three ways you can keep data up to date in your portal:

  1. Manually update data in your portal using the HubSpot UI.
  2. Import data regularly via spreadsheet.
  3. Sync data programmatically with an integration using the HubSpot API.

Additional Resources

Learn To Map Your Data in HubSpot

Explore the HubSpot Knowledge Base

Review HubSpot’s API Docs

Get Support From a Certified HubSpot Solutions Partner

Get Help From a HubSpot Technical Consultant

Need to Upgrade Your Account to Enterprise?