HubSpot

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 Sync Behaviors

Object Name	Supported?	Sync Keys	Behaviors
Company	✅	Object ID, Domain, any custom single-line text or number	Update Only, Update or Create, Mirror
Contact	✅	Object ID, Email, any custom single-line text or number	Update Only, Update or Create, Mirror
Contact & Static List	✅	Email	Update Only, Update or Create, Mirror
Deal	✅	Object ID, any custom single-line text or number	Update Only, Update or Create, Mirror
Product	✅	Object ID, any custom single-line text or number	Update Only, Update or Create, Mirror
Line Item	✅	Object ID, any custom single-line text or number	Update Only, Update or Create, Mirror
Custom Object	✅	Object ID, any searchableProperty	Update Only, Update or Create, Mirror
Subscription Preferences	✅	Email	Mirror
Custom Behavioral Event	✅	Unique Event ID	Send
Email	✅	N/A	Send
Ticket	✅	Record ID	Send

Learn more about all of our sync behaviors in our Syncs documentation.

Contact us if you want Census to support more Hubspot objects and/or behaviors

Contact Emails

Please note that an email address already associated with a Contact cannot be used for another Contact. If you attempt to update a Contact record with an email address that is already in use, the field will not be updated.

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.

Hubspot also requires either the contact ID, email or utk of the contact associated with the event.

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 One of the following values: LEGITIMATE_INTEREST_PQL, LEGITIMATE_INTEREST_CLIENT, PERFORMANCE_OF_CONTRACT, CONSENT_WITH_NOTICE, NON_GDPR, PROCESS_AND_STORE, LEGITIMATE_INTEREST_OTHER.

• 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.

🆘 Common Errors

There's a few errors which frequently cause skipped records on when syncing data to Hubspot.

• TypeCastError: Empty input (after ) at line 1, column 1 [parse.c:1060] in 'InternalValue1;When syncing to a Multiple Checkbox (Enumerated) field, the source data should be formatted as an array instead of adding a semicolon between each value.

• Multiple Contacts found with ID 123456When syncing associations, the Lookup By field should be unique. For example, if we have a Company sync with a contact association in the field mapping and the Lookup By field is a non-unique ID field, we will reject the Company record if we find multiple Contacts with that ID.

🔌 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 [e-mail] or start a conversation with us via the in-app chat.