CRM Objects in CMS Hub

Last updated:

CRM objects can be queried and rendered on HubSpot hosted content, allowing data to be shared between your business operations, website, and emails. Using the crm_object,  crm_objects and crm_associations HubL functions you can display and control logic based on your CRM object data.

Supported CRM object types

See Getting started with Custom Objects to learn more about creating and using them.

For security purposes, only instances of custom (account-specific) object types and the built-in product and marketing_event types can be retrieved on any public page. Any other built-in object types (except product) or integrator object types must be hosted on a page that is either password protected or requires CMS Membership login.

Custom Objects Real Estate Example

It may be easier to understand the possibilities of custom objects in the CMS by seeing real use-cases. One great use-case is a real estate listing. You can abstract this to imagine other possible use-cases.

To a real estate agent their primary goal is taking what your customers needs and wants are, and match current listings to their customers based on that. 

In our example we create a new custom object called a property listing.  Each real estate listing record can have it's own properties such as number of bedrooms, bathrooms, asking price, and other home features.

All of this data can be rendered in the HubSpot CMS. 

How does this differ from HubDB?

With CRM Objects your listing data is stored in the same place as your marketing and sales data. This means your real business data and your website database are the same thing. Additionally CRM objects can be associated to each other. In our example we associated each real estate agent to the properties they manage. On the website we can display the associated agent.

Because the data is stored within the CRM, naturally these objects integrate with many of the other HubSpot tools. Meaning tools like workflows, email, sales and service tools all can be used in tandem with the data.

See the Real Estate Custom Objects example

You can use this example as a way to test and explore what's possible with Custom Objects. An overview of this example was given during DevDay 2020, the event was recorded and is available to watch.

Displaying a single CRM object's properties using the crm_object function

The crm_object function gets a single object from the HubSpot CRM by query or by CRM object instance id. 

Object instances are returned as a dict of properties and values.

{# Render custom object by query #}
{% set event = crm_object("event", "name=Defensive Health") %}
{{ event.name }}

{# Render custom objects specifying the id of the object #}
{% set event = crm_object("event", 289236) %}
{{ event.name }}

If a query returns a collection of objects the function will return the first object in the collection.

Displaying the properties for multiple CRM objects using the crm_objects function

The crm_objects() function gets objects by object type from the HubSpot CRM by query or by instance id. Objects are returned as a dict of properties and values.

The object returned contains a results property that can be looped through to display the information in the object's items.

{# Render custom objects by query #}
{% set events = crm_objects("event", "limit=3&type=virtual") %}
<h3>{{events.total}} New Events:<h3>
<ul>
{% for event in events.results %}
	<li>Name: {{ event.name }}</li>
{% endfor %}
<ul> 

{# Render custom objects by ids #}
{% set events = crm_objects("event", [289236,289237,289238]) %}
<h3>{{events.total}} New Events:<h3>
<ul>
{% for event in events.results %}
	<li>Name: {{ event.name }}</li>
{% endfor %}
<ul> 

Display objects associated with your custom objects

Get a list of associated objects from the HubSpot CRM based on the given object id, association category, and association definition id using the crm_associations HubL function. 

Object instances are returned as a dict of properties and values.

{% set associated_objects = crm_associations(289236, "USER_DEFINED", 3) %}
<h3>Contacts Associated With Event</h3>
<ul>
{% for contact in associated_objects.results %}
	<li>Name: {{ contact.firstname }} {{ contact.lastname }}</li>
{% endfor %} 
</ul> 

Getting a custom object type's details

To get a custom object type's name, id, fullyQualifiedName, association ids, and other details you can make a GET request to the CRM Objects Schema API.

Since the FQN of portal specific type carries the HubSpot account id, It is advised to avoid using the FQN for HubSpot account specific types to make the code portable across HubSpot accounts.

CRM Object Module field

Provide a way for content editors to select an instance of a CRM object to display or execute logic based on it's value.

Ex: you may want to display  information on a specific product, contact, company, deal, quote, or ticket. You can use this with other custom objects.

CRM Object Fields are supported in Modules.