This blog post is part of our 5-part series about HubSpot API Features. In case you missed Part 1, check it out here!
You may already be aware of this next platform-extending feature, but it’s so important that it still warrants a deep dive. Out of the box, HubSpot allows you to store Contact, Company, Deal (with product and line item), and Ticket data in a relational manner. In other words, your object data can relate in a many-to-many fashion, enabling cross-object reporting, contact segmentation, and visual representations of your data.
However, you may find that you have the need to track additional data in a way that exceeds the bounds of the default system. This is where Custom Objects come into play.
HubSpot Custom Objects
As its name suggests, a Custom Object is a set of custom records, fields, and relationships outside the default Contact, Company, Deal, Ticket, Product, and Line Item object model. For example, you may need to create a many-to-many relationship with one of the default objects for extended data functionality, reporting, etc.
Let’s look at some real-life examples of custom objects we see our clients leverage on a day-to-day basis:
Events – Say you want to track all of your events a given contact has attended and need key data points like event date, location, venue, or type indications. Since one contact can attend many events, and you don’t just want the most recent attended event to overwrite previous data, a custom Event object related to the Contact object will do the trick.
Projects – Oftentimes, we see our clients track separate deals that relate to a higher-level initiative of some kind. Maybe they have different project phases (like us!) with unique pricing and other data. Maybe they offer add-on services but want to house everything together under an umbrella initiative or project. A custom object related to deals would work great here.
Tags – Unlike many other systems, HubSpot doesn’t have built-in “tagging” capabilities to designate common keywords/phrases across records and objects for segmentation and reporting. An easy workaround here would be to create a custom Tag object associated with Contacts, Companies, and any other default or custom object that would need tagging. Each record in this object would represent a tag and custom reports can be built to visualize tag frequency and usage.
How to Code Custom Objects in HubSpot
Now that we understand how custom objects work from a front-end modeling perspective, let’s take a look at how to create and define custom objects. As of now, this can only be done via the API.
We’ll take our events example and create a custom object called Events. Then, we’ll associate it to the contact and company objects so we can track which events our contacts and their related companies have attended.
Let’s also assume we have an internal naming convention for event codes and that they’re unique. We’ll create a field called Event Code and set it as a unique property to ensure that the code can’t be used across multiple event records.
With that in mind, here’s what a cURL request might look like:
curl --location --request POST 'https://api.hubapi.com/crm/v3/schemas?hapikey=YOURHUBSPOTAPIKEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "event",
"labels": {
"singular": "Event",
"plural": "Events"
},
"primaryDisplayProperty": "name",
"requiredProperties": [
"name",
"event_code"
],
"properties": [
{
"name": "event_code",
"label": "Event Code",
"isPrimaryDisplayLabel": false,
"isSecondaryDisplayLabel": true,
"hasUniqueValue": true
},
{
"name": "name",
"label": "Event Name",
"isPrimaryDisplayLabel": true,
"hasUniqueValue": false
}
],
"associatedObjects": [
"CONTACT", "COMPANY"
],
"metaType": "PORTAL_SPECIFIC"
}'
We’ve also set Event Name as the primary display name on the object and have required it along with Event Code to be entered for every record.
Now that the object is created, we can add some records and see how it interacts with contacts and companies.
Event records:
And we can see who attended each event by clicking into an event record and locating the association cards on the right-hand side:
Final Thoughts
While creating a custom object is pretty simple and can be done in just a few lines of code, it can really add complexity and robustness to your data model, allowing your teams to track data with greater depth.
To recap, custom objects:
- Extends data storage capabilities by creating many-to-many associations with custom definitions
- Currently, can only be created via the API
- Can be associated to both default and other custom objects
- Only available on Enterprise plans
- Limit of 10 custom objects and 500k records across the objects (additional storage can be purchased in packs of 10 custom objects and 500k records)
Interested in joining the obo team?
