Getting Started with Custom Objects in HubSpot

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.

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.

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.