Note: This is not a product announcement. This article discusses existing objects in HubSpot (including contacts, companies, deals, tickets, products, line items, and engagements) while describing ways of working with data that looks a little different. 

“Can we build a custom object in our HubSpot instance, similar to certain other enterprise CRMs?” 

“Can we go beyond deals, contacts, companies, tickets, etc.?”

“We’re a university. Can we call our contacts ‘students’ instead of ‘contacts’?”

These questions aren’t new to you if you’ve done any kind of enterprise implementation before, or even if you’re migrating from another system into HubSpot. This short blog post aims to answer all partner FAQs surrounding building custom objects in HubSpot. 

Let’s start with the elephant in the room: Is it possible to build custom objects in HubSpot?

Yes and no. Depending on how complex your custom object needs are, it’s possible that you won’t be able to. However, when most companies ask this question, they’re not always looking to build a highly complex object. More often than not, they’re looking for simpler custom objects such as contracts from an external ERP system, business intelligence from a third party tool, or prospect data they can easily access on the contact or company record in HubSpot, without having to toggle between systems. 

If any of the examples above sound like what you’re looking for, you’re in luck. According to Mike Hodsdon, a solution architect at HubSpot, HubSpot’s API is armed with six powerful ways to scale this wall: 

  • Timeline API
  • Analytics events
  • Leveraging deal/ticket objects
  • CRM extensions
  • "Flattening" the data by using custom properties in HubSpot
  • Combining more than one method

Here’s a helpful chart outlining the benefits and drawbacks of each approach: 

Screen Shot 2019-08-28 at 3.30.16 PM


Armed with these powerful options, your developers/admins will be able to find a useful solution for your custom object conundrum without losing too much sleep. 

Let’s dive into each one of them. 


Timeline API

Let’s say you want to update HubSpot records with data on a new webinar registration, exam submission, invoice completion, or any other kind of custom event. Rather than having to recreate a more complex object in HubSpot to match your external system exactly (which isn’t possible to do yet), you can simply use the Timeline API to create a custom timeline event that’ll show up on HubSpot contacts, companies, or deals, depending on your needs. The full documentation for using this method is available here: Timeline API overview

In a nutshell, you could use the Timeline API if your custom object is tracking a contact action that could occur multiple times per contact/company/deal and you just need to know that “this happened.” However, while you will be able to segment on the contact/company/deal record for the custom object, you won’t be able to report on them using this method without additional dev work. 

For example, many HubSpot customers integrate their external billing system into HubSpot using this method. Typically, they would want to see invoice-related updates and notifications in HubSpot on particular contact and company records. Using the Timeline API, they would build a bridge between their external billing system and HubSpot, so that every time a certain action takes place (for example, when a customer submits an invoice), a timeline event appears on the company record for the associated account. In many of these scenarios, customers often work with a partner to build out the API-based solution to their business needs. 


Events API

This is similar in some ways to the Timeline API approach, since events will show up on the contact, company, or deal timeline in a comparable way. If your custom object is tracking the date of an action that can happen multiple times, they just need to know that “this happened,” and it has a 1:many relationship from contact/company/deal to the event, you could use the Events API. However, the process for setting up events is different (see here), and unlike the previous approach, events can be reported on using event funnels (see “Events Funnel” on this page).  Setting events up also does not require OAuth and app installation, which can make this a bit quicker and easier in certain cases. 

Here’s what an event funnel report looks like (Note: this functionality is Enterprise only)


Leveraging existing HubSpot objects (Deals or Tickets)

Let’s say you want to be able to track all of your customers’ invoicing activity, report on it by region and product category, and also be able to accommodate multiple invoices per customer at any given time. In this scenario, you could potentially create a separate deal pipeline for invoices and then track each stage of the invoicing process using deal stages. You could trigger deal auto-creation via workflows once you’ve found a way to get the triggering data into a HubSpot property, presumably using the Contact Properties or Company Properties API. You would be able to build complex reports in HubSpot for this “deal” pipeline. You can also rename the pipeline to whatever you want, such as "students" or "doctors." 

Simply put, anytime you need to report in detail on a custom object, the easiest solution is to repurpose an existing HubSpot object to accomplish your goals. There’s no OAuth or app installation involved, you can have multiple instances of the “custom object” per contact/company, and you can easily segment using saved filters and lists. 


CRM Extensions API

Let’s say you want to see all the contracts a company has signed in one place on their company record. You could use the CRM Extensions API to surface each of those contracts in a special “contracts card” in the sidebar of the company record in HubSpot (it can also be used for contacts, deals, and tickets). This approach is especially useful for users in the CRM who need to see the contracts (or similar object) in one fixed place on the contact/company/deal record. 

According to HubSpot Developer Support Specialist Isaac Takushi, partners should note that because the data in the CRM extensions card does not live in HubSpot, HubSpot customers cannot report on it in HubSpot or segment using HubSpot’s lists/filters. However, you can give the card a custom object name, such as “Contracts.” You can also have a number of properties show up on the card for each contract object. When a contact/company/deal record is loaded (depending on where you choose to place the contracts card), HubSpot makes a request to the integrator and displays the data from the outside system corresponding to the contact/company/deal you’re looking at. You can have a modal window pop up upon clicking into the card. 

A number of prominent HubSpot integrations, including PandaDoc, are built using CRM extensions. In their own words, the experience “feels like the other software is just built into the HubSpot CRM.” 

Here’s what it looks like: 

Gif Window in action.gif


"Flattening" the data by using custom properties in HubSpot

This is probably the best known method for working with custom data in HubSpot. For instance, let's say your client is a school and they have contacts who are either students or parents. Rather than creating custom objects to address this need to distinguish between contact types, you're better off creating a custom property for "contact type" that includes options such as "parent" and "student." Even with the solutions described above, it makes sense to avoid creating unnecessary clutter with too many objects by simply creating the right custom properties. 

However, because properties can only hold one value at a time, they're not ideal for a number of custom object use cases described elsewhere in this article. They can work very well in conjunction with the other methods described here. 

Access Your Properties in HubSpot


Combining more than one method

Going back to the example of PandaDoc, they made their solution even more effective by combining the CRM Extensions API with the Timeline API. This way, users can see important updates in one place and also see them as they stream in on the contact/company/deal timeline.

You can use this same approach to build out your own solution to the custom object question. If you have questions about this, feel free to post them in the HubSpot Developer Community Forum

I interviewed Solution Architect Mike Hodsdon on this topic and each of the methods above, and you can listen to this entire podcast on "Custom Objects in HubSpot" by clicking below:

New call-to-action


And that’s it! Now you know how to work with certain kinds of custom objects in HubSpot. The methods described in this article should help you address many of your clients’ needs. Feel free to leave comments below or reach out directly to me ( with questions, comments, or any other feedback. 

Want to connect with others on HubSpot tips, tricks, and updates? Head over to the HubSpot Community to join a conversation or start one of your own.

Sign up for your free HubSpot Academy account.

Originally published Sep 26, 2019 11:00:00 AM, updated April 10 2020