Introducing Custom Objects for HubSpot

HubSpot is a powerful platform for executing your marketing, sales, and support goals. You can keep track of almost every facet of your business with our core products and can extend functionality even further with apps from the marketplace. But what if you need to describe a specific “thing” that isn’t represented in HubSpot’s collection of standard objects? Well, with our newly released custom objects for Enterprise accounts, you’re free to customize your account to fit the needs of your specific business.

What are custom objects all about?

In HubSpot, standard objects represent different types of predefined data such as Contacts, Companies, Deals, and Tickets. Each object has unique properties that you can use to collect information about a specific record of that type. For example, the Contact object has a "first name" and "last name" property that you can fill in for each contact record added to the CRM. But sometimes, these standard objects are not enough, and that is where custom objects come into play.

We designed custom objects to run on the same internal infrastructure that powers our standard CRM objects, ensuring they interact predictably and reliably with the rest of the HubSpot platform. At the moment, you can define custom objects via our CRM API, and then interact with them within your account in the same way you would with standard objects like Contacts and Companies. They can even have associations with other HubSpot objects.

Once defined, your custom objects have the same CRUD operations available via the API as standard objects. For example, a car dealership could create a "Vehicle" custom object and associate it with Contacts to keep track of vehicle sales and customers. Once defined, individual vehicle records can be created and updated right in the GUI. You can also use the API to sync these records with an external database.

Ready for an example?

Let's go through a use case for custom objects to demonstrate the flexibility they offer and the power of associating them with other objects. For this example, we'll pretend we're setting up a new HubSpot account for a training company that features a selection of learning courses customers can select. These courses are presented to groups of registered students as part of a training session.

We'll model the training sessions and learning courses with two new custom objects, each with properties to help collect additional details. We'll then build associations between these objects to define how multiple learning courses make up a single Training object. Finally, we'll create an association so that we can add several contacts to training sessions as well. Is your head spinning? It will get clearer as we go. Let's get started!

Creating a Learning Course custom object

Let’s start by defining our Learning Course custom object. We’ll want to add a few properties to help us understand what this course is all about:

• Title
• Description
• Duration

Here’s an HTTP POST that will build this new custom object and properties in your account. Note that we’re using the demo API key. You can replace this with your own API key if you wish to follow along.

After sending this request, you’ll get a response similar to the following:

Awesome, we’ve created our Learning Course custom object, and it should now appear in the HubSpot UI. Let’s create a few course records to use for our example. Just like you would add new contact records to the CRM, you can now navigate to “Learning Courses” in your account’s UI and add as many courses as you would like.

After selecting “Learning Courses” in the menu illustrated above,  you’ll come to a screen which will show an empty list of Learning Courses. Click “Create Record” and fill out the resulting form to create a new course. Notice that the properties available for this object match what we defined via the API in the previous step. Repeat this a few times to get some courses into the CRM. The specific contents of each course aren’t important for our purposes, but you’re free to use these suggestions:

Now that we’ve used the UI to create a few courses, let’s use the custom object API to create one more. (This is just to show that records can be created via the UI or by API depending on your preference):

You should get back a response similar to this:

Now that we’ve got our learning courses entered and ready, let’s create the Training Sessions custom object.

Create a Training Session custom object

A training session should consist of one or more of the courses we created above. It will be presented on a certain date at a specific location, so we'll need the following properties on our new object:

• Location
• Date
• List of courses to be presented

To make sure the "list of courses" property can be populated with the course records we created before, we'll need to include an association to our Learning Course object.

Use the following POST command to create the Learning Session custom object:

Note specifically the associatedObjecs array at the bottom of the JSON request body. This is what we’re using to create the association, and the single value in the array in this case is the objectTypeId of the Learning Course custom object returned in the first schema call above.

The above POST command yields a response similar to the following:

Now we can create new training sessions and define where, when, and what we’ll teach. But what about the “who”? We need to include information about participants in these training sessions. To do that, let’s use the Custom Object Schema associations endpoint and associate our Training Sessions object with the Contact object.

You can see that the endpoint URL path includes the fullyQualifiedName of the Training Session object we created above. Also, the value we’ve used for the fromObjectTypeId is the objectTypeId of the Learning Session custom object we just created. The toObjectTypeId is the standard “contact” type.

Now we’ve got the who, what, where, and when, so we’re ready to try adding a few training sessions. Let’s use the UI first. Navigate to the Training Sessions object page, just as you navigated to the Learning Course page above. There, click “Create Record” and populate the Location and Date fields. Then, below, you can choose one or more Learning Courses, and one or more Contacts to associate with this training.

Let’s add one more session using the API. The POST below will create a new training session record. We’ll create the associations to specific courses and contacts with separate calls.

Note the use of the fullyQualifiedName of a training session in the url again. This call will return a response similar to the following:

Next we’ll add some learning courses using the associations endpoints.

Here we’ve got the fullyQualifiedName for training sessions first in the url, then the same for learning courses. In the body, we specify the id of the training session we created above for the from.id for each association, and the id of a learning course for each of the to.id values. This yields a response similar to the following:

And finally, we’ll add some contact attendees for our class:

All that hard work results in a new, fully detailed training session. Mission accomplished!

We’ve only scratched the surface of what is possible

We’ve built a pretty robust set of objects to handle a full training program, including courses and participants. We associated custom objects with both standard and custom objects. And we did this all inside of HubSpot. We’re excited about the flexibility and power custom objects provide to help our customers grow better.

We build custom objects for one reason - we know that data is the engine of every business. A CRM that can’t accurately represent all kinds of business data won’t hold up as a CRM for long. No two businesses are alike though, especially as your business grows and complexity increases to meet the needs of customers. For those businesses who have grown to that level of complexity, many of them with HubSpot as their primary source of data, they need a customizable solution. So, we built custom objects to be that solution.

- Dylan Sellberg, PM for custom objects

You can even use custom objects with HubSpot's CMS. We've got HubL markup that enables you to pull information from custom objects to display on web pages. This means the same information can be used in your business processes, site pages, emails, and beyond. The possibilities are pretty extensive.

A few important notes

You may have noticed that we used API key authentication to define and update custom object schema throughout this post. This is because API keys are the only authentication mechanism we support by default for modifying custom object schema.

Because we want to ensure custom objects are created in customer accounts thoughtfully and predictably, OAuth-based apps will not have access to this functionality unless reviewed and approved by our team. You can request access for your app by clicking on the "Create Request" button in the yellow box at the top of the custom object documentation page.

Note that we'll require your app to follow specific guidelines to ensure consistent behavior of custom objects in customers' accounts. Applying for access for your app to use custom objects does not guarantee that your app will be approved.

That said, we understand that many apps out there would benefit from using objects beyond the standard HubSpot objects. So we're working on something called app objects.

One more thing: app objects

App objects will include dozens of predefined objects available for apps to use that won't be included in regular HubSpot accounts by default. When customers install apps, any requited app objects would be installed at the same time.

For example, instead of two apps installing two custom "widget" objects that are slightly different, there might be a single "widget" app object that both apps would use, ensuring consistency and predictability in customer accounts.

We aren't able to share a timeline for the launch of app objects yet, but we will make an announcement on our changelog as soon as we know more.

Thanks for learning more about custom objects. We're looking forward to hearing how you use these powerful new tools to help your organization grow better with HubSpot.