CRM Objects in CMS Hub

Last updated:

Note: Some functionality on this page is currently in beta. By participating in this beta you agree to our Developer Beta Terms.

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 object types for all of these functions:

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

For security purposes, only instances of account-specific object types and the built-in product type 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

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 }}
Use this table to describe parameters / fields
Parameter Type Description Default
object type
Required
String

The custom object type name. To find the names of the account specific and integrator object types available in your account use the CRM Objects Schema API to get the type definitions and look for the name property. It contains the internal object type name that should be used in the function. The supported built-in object type names are: contact, product, company, deal, ticket, and quote. Object type names are case sensitive.

For integrator and account specific object types with the same name as the built-in objects use the objects fully qualified name (FQN).

null
query or object instance id
Required
String

The id of object instance to retrieve. Alternatively an HQL query with object type property expressions ANDed together using the & symbol. The supported expression operators are eq (default), neq, lt, lte, gt, gte, is_null and not_null. E.g. "email=contact@company.com"

null
properties
String

The list of property names that should be retrieved. If list is not provided then the properties defined as required are returned. if no required properties have been defined all the properties will be returned. The object instance id is always included in the returned object properties even if it is not explicitly added in the property list.

null
formatting
Boolean

Format values such as dates and currency according to this portal's settings. Pass false for raw strings.

true

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> 
Use this table to describe parameters / fields
Parameter Type Description Default
object type
Required
String

The custom object type name. To find the names of the account specific and integrator object types available in your account use the CRM Objects Schema API to get the type definitions and look for the name property. It contains the internal object type name that should be used in the function. The supported built-in object type names are: contact, product, company, deal, ticket, and quote. Object type names are case sensitive.

For integrator and account specific object types with the same name as the built-in objects use the objects fully qualified name (FQN).

null
query or list of object instance ids
String or list

The list of object instance ids to retrieve. Alternatively an HQL query with object type property expressions ANDed together using the & symbol. The supported expression operators are eq (default), neq, lt, lte, gt, gte, is_null and not_null. E.g. for an event "type=sports&date_gt=2020-06-01"

If neither a list of objects or a query is provided, the function will run the default query of offset=0&limit=10

offset=0&limit=10
properties
String

The list of property names that should be retrieved. If list is not provided then the properties defined as required are returned. if no required properties have been defined all the properties will be returned. The object instance id is always included in the returned object properties even if it is not explicitly added in the property list.

null
formatting
Boolean

Format values such as dates and currency according to this portal's settings. Pass false for raw strings.

true

 The total, offset and has_more properties work the same as with products and HubSpot built-in objects. See crm_objects for detail on them.

Display objects associated with your custom objects

Gets 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> 
Use this table to describe parameters / fields
Parameter Type Description
id
Required
id

The id of object instance to retrieve the associations from. The id can be found in the URL of the object or through the API that returns the object type. 

association category
Required
enumeration

The category of the association definition. Possible values are HUBSPOT_DEFINED, USER_DEFINED, and INTEGRATOR_DEFINED. This parameter can be omitted for hubspot defined built-in association types.

association definition id
Required
number

The id of the association definition to use. This association id can found at the CRM Objects Schema API.

query
String

HQL query to filter associated objects. The query can be formed with property expressions ANDed together using the & symbol. The supported expression operators are eq (default), neq, lt, lte, gt, gte, is_null and not_null. E.g. for an event type=sports&date_gt=2020-06-01

properties
String

The list of property names that should be retrieved. If list is not provided then the properties defined as required are returned and all the properties will be returned if required properties is not defined. The object instance id is always included in the returned object properties even if it is not explicitly added in the property list.

formatting
boolean

Default value is true.Format values such as dates and currency according to this portal's settings. Pass false for raw strings.

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

This functionality is currently in beta, may undergo changes. This feature is rolling out to beta participants slowly, and may not be available for you yet. Opting into the beta will be available soon.

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.

module.fieldname.id returns the object instance id.

module.fieldname.properties returns the properties fetched from this object instance.

CRM Object Fields are supported in Modules.

CRM Object Field
JSON
// fields.json
{
  "name" : "crmobject_field",
  "label" : "CRM object",
  "required" : false,
  "locked" : false,
  "object_type" : "CONTACT",
  "properties_to_fetch" : [ ],
  "type" : "crmobject",
  "default" : {
    "id" : 1
  }
}
CRM Object Field
Parameter Type Description Default
object_type
Required
StringType of CRM Object the user can pick from.
  • COMPANY
  • CONTACT
  • DEAL
  • PRODUCT
  • QUOTE
  • TICKET
  • Your custom or integrator object type
properties_to_fetch
array

Array of property names associated with the object type in string form. Ex: "date_of_birth" is a property associated with a contact. Use this to limit the information available to the page to just what you need.

default
object

Object with id of default selected object instance. Contact ID, Company ID etc.

null