HubSpot

This page describes how to use Activations with HubSpot.

Getting Started

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

Connecting HubSpot

• Within Activations, 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

Contact Support if you want Activations to support more Hubspot objects and/or behaviors. Additionally, you can make generic HTTP requests to endpoints of your choice, as outlined below.

Generic HTTP Requests

If you wish to send data to a HubSpot API endpoint that is currently not supported via our existing connector, you can manually configure a generic HTTP request of your choosing.

• Select HTTP Request in the object selector

• Put in your URL. Your endpoints must be part of api.hubapi.com, if you wish to send data to a different endpoint, please reach out to the Support team.

• Configure the rest of the sync as you would for a general HTTP Request destination, and we'll use your existing HubSpot credentials under the hood.

Qualified Custom Properties for Sync Keys

In order to use a Custom Property as a Sync Key in Activations, it must be one of the following types:

• Single-line Text
• Number

Additionally, we strongly recommend this field be marked as Unique. Using a non-unique custom property will significantly degrade your sync speed.

Unfortunately, this can only be done when the property is created in HubSpot. Depending on the volume and frequency of your HubSpot syncs, it may be worth re-creating the property in HubSpot to add the unique rule.

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.

To ensure a Hubspot Custom Object property can be used as a Sync Key within Activations the object must be updated to include the property as a searchableProperties.

Hubspot currently restricts users to updating this property via the Hubspot API.

The calls to make this update can be found in HubSpot's Custom Objects API Docs > Object Schema Tab > searchableProperties.

HubSpot offers some third party apps, available in their marketplace that can also assist with Custom Object management.

API How To

• Retrieve (or create) a private app access token to make API calls to Hubspot.
• Perform a GET request to the /crm/v3/schemas endpoint. Then, search the response to identify the objectTypeId of the custom object you wish to update, as well as the name of the field you want to modify.

Here is an example request:

curl --location "https://api.hubapi.com/crm/v3/schemas" \
--header 'Authorization: Bearer {YourPrivateToken}' \
--header 'Content-Type: application/json' \

The values will look something like this:

"objectTypeId": "2-41250440",
"name": "property_name_example",

• Complete a PATCH request to the /crm/v3/schemas/{objectTypeId} endpoint. Ensure you use the objectTypeId you identified in the previous step and include the following request body:

{
  "searchableProperties": [
    "property_name_example"
  ]
}

Here is an example request with the objectTypeId as 2-41250440:

curl --location --request PATCH "https://api.hubapi.com/crm/v3/schemas/2-41250440"
--header 'Content-Type: application/json'
--header 'Authorization: Bearer {YourPrivateToken}'
--data '{ "searchableProperties": [ "property_name_example" ] }'

• Refresh the Object within a Activations Sync, it should now display the new field in the Sync Key options.

For additional support, please contact the Activations 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 Activations 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 Activations. You'll need to use the New Custom Field option to create the matching fields in Activations. 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.

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 Activations syncs on either side of the associations, while one-to-many associations can only be set on the child or "many" side.

Labeled Associations

Labels in HubSpot can be complex. Activations 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 Activations sync may actually create up to three associations.

Unfortunately, HubSpot does not offer a way to remove these default associations when they're no longer necessary after removing the labeled association Activations created. These associations may have actually been created intentionally so Activations also cannot delete them automatically.

To navigate this, Activations provides an option to automatically clean up orphaned default associations when removing any associations.

When this behavior is enabled and a Activations 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"]

Delete Behavior

In Mirror syncs, Activations will perform a "soft delete" and archive records instead of permanently deleting them.

We also support HubSpot's "GDPR Delete", which is a permanent deletion. This sync behavior is available on the Contact object: set the GDPR Delete endpoint toggle to TRUE.

Sync Speed

Activations uses a variety of APIs to achieve the highest possible speed. With the right sync configuration (see below), Activations can update 10,000 contacts per second. Activations 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.

Please be aware that Custom Objects require additional API calls and are even slower as a result (~1/3 the speed).

🔑 Required Permissions

Activations 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 Activations for any reason, you can delete your connection from the Destinations page in Activations and/or uninstall the Activations app from your HubSpot account by following these instructions. Note that you won't be able to sync new data from Activations until the connection is restored, but no previously synced data in HubSpot will be impacted.

Need help connecting to HubSpot?

Contact Support.