Comment on page


This page describes how to use Census with HubSpot.

🏃‍♀️ Getting Started

In this guide, we will show you how to connect HubSpot to Census.

Connecting HubSpot

  • Within Census, navigate to the Destinations page.
  • Click the New Destination button.
  • Select HubSpot from the menu and click Connect.
Follow the OAuth flow to connect HubSpot. Easy!

🗄 Supported Objects and Behaviors

Object Name
Sync Keys
Object ID, any Text/Number
Update Only, Update or Create, Mirror
Object ID, Email, any Text/Number
Update Only, Update or Create, Mirror
Contact & Static List
Update Only, Update or Create, Mirror
Object ID, any Text/Number
Update Only, Update or Create, Mirror
Object ID, any Text/Number
Update Only, Update or Create, Mirror
Line Item
Object ID, any Text/Number
Update Only, Update or Create, Mirror
Custom Object
Object ID, any searchableProperty
Update Only, Update or Create, Mirror
Subscription Preferences
Custom Behavioral Event
Unique Event ID
Record ID
​Contact us if you're looking for Census to support other HubSpot objects.

Custom Objects

Custom Objects are available to customers on HubSpot's Enterprise plans.
As of March 2021, only properties in the searchableProperties set are usable as sync keys in Census. This is a bit confusing as this label only appears in the HubSpot API. A searchable property can be added to a Custom Object via HubSpot's API. The calls to make this update can be found in HubSpot's Custom Objects API Docs > Object Schema Tab > searchableProperties.
Additionally, HubSpot has some apps available in their marketplace like Dotsquares that can assist with Custom Object management.
If you need a hand making one of your existing Custom Object fields searchable, please contact the Census support team and we can walk you through it.

Custom Behavioral Events

Custom Behavioral Events require a bit of prep work. You'll first need to go into HubSpot and create your event (see HubSpot's instructions for how to do that).
You'll need to both create the event AND add all of the custom properties beforehand. Once you've done so, copy and paste HubSpot's internal name for the object—you'll need to provide that to the Event Name property during the Census sync.
Note: The custom fields you've added will not show inside Census. You'll need to use the New Custom Field option to create the matching fields in Census. Make sure they're named exactly the same (names are case-sensitive).

Subscription Preferences

Subscription preferences allow you to manage which users are subscribed or unsubscribed from your existing marketing subscriptions (Currently, HubSpot does not allow external services to programmatically create new subscriptions).
HubSpot Subscription Preferences syncs require additional fields when using HubSpot's GDPR portal:
  • Legal Basis Explanation A more detailed explanation to go with the legal basis.
The same value provided for these fields will be used for both subscribing and unsubscribing a user.
Census can only remove contacts from subscriptions that were originally created by Census.

Managing Object Associations

HubSpot supports an advanced method of defining relationships between objects called Associations. Associations have a number of different properties:
  • They're supported between all HubSpot object pairs, including Custom Objects.
  • They can represent one-to-many and many-to-many relationships.
  • Associations can be labeled or unlabeled. HubSpot Professional and Enterprise plans also support custom labels.
Many-to-many associations can be updated in Census syncs on either side of the associations, while one-to-many associations can only be set on the child or "many" side.
Census Company/Contact Association

Labeled Associations

Labels in HubSpot can be complex. Census provides some advanced configurations to make updating and removing labels a bit more straightforward.
When creating a labeled association between two objects in HubSpot, HubSpot will also automatically create an unlabeled association. Additionally, when creating an association from a Contact to a Company, HubSpot will create another association labeled Primary. That means that adding a labeled association with a Census sync may actually create up to three associations.
Hubspot Labeled Association
Census Labeled Association Sync Mapping
Unfortunately, HubSpot does not offer a way to remove these default associations when they're no longer necessary after removing the labeled association Census created. These associations may have actually been created intentionally so Census also cannot delete them automatically.
To navigate this, Census provides an option to automatically clean up orphaned default associations when removing any associations.
When this behavior is enabled and a Census sync removes a labeled association, we'll also check to see if the remaining associations are only the unlabeled and Primary labeled associations. If so, we'll automatically remove those associations as well.
By default, this feature is not enabled to avoid accidentally deleting associations that were created outside the sync and should still exist.

Formatting Data for Hubspot Data Types

Object references (Associations): will be mapped to a Hubspot Array of Reference data type. The source data should be formatted in an array.
Example: ["RecordID_1", "RecordID_2"]
Multiple Checkboxes (Enumerated fields): will be mapped to a Hubspot Array of Enumeration. The source data should also be formatted as an array. Additionally, HubSpot expects the options provided to be the Internal Value as given by Hubspot's property settings page.
Example: ["InternalValue1", "InternalValue2", "InternalValue3"]

🏎 Sync Speed

Census uses a variety of APIs to achieve the highest possible speed. With the right sync configuration (see below), Census can update 10,000 contacts per second. Census connects to HubSpot via OAuth, which is subject to a limit of 100 requests every 10 seconds (except for the Search API). For more information, see the HubSpot documentation.
Your choice of sync key and behavior can have significant performance implications.
Using HubSpot Object IDs or Contact emails as identifiers in HubSpot is fast, but using all other fields as identifiers is very slow. That means any syncs that create new records in HubSpot (other than Contacts by email) will be slow. We're working with HubSpot to increase the speed of their APIs in order to improve sync speed.
Please be aware that Custom Objects require additional API calls and are even slower as a result (~1/3 the speed).

🔑 Required Permissions

Census requires that the connecting HubSpot user have Super Admin permissions in order to access all supported HubSpot objects. If you have limited permissions and still want to connect Census to HubSpot, contact the Census support team.

Disconnecting HubSpot

If you need to disconnect HubSpot from Census for any reason, you can delete your connection from the Destinations page in Census and/or uninstall the Census app from your HubSpot account by following these instructions. Note that you won't be able to sync new data from Census until the connection is restored, but no previously synced data in HubSpot will be impacted.

🚑 Need help connecting to HubSpot?

​Contact us via [email protected] or start a conversation with us via the in-app chat.