HubSpot is a leading marketing and sales platform that helps you track leads as well as inbound marketing and sales.

RudderStack supports HubSpot as a destination where you can seamlessly send your event data.

Find the open source transformer code for this destination in the GitHub repository.

Getting started

Before configuring HubSpot as a destination in RudderStack, verify if the source platform is supported by HubSpot by referring to the table below:

Connection ModeWebMobileServer
Device mode---
Cloud modeSupportedSupportedSupported
To know more about the difference between cloud mode and device mode in RudderStack, refer to the RudderStack Connection Modes guide.

Once you have confirmed that the source platform supports sending events to HubSpot, follow these steps:

  1. From your RudderStack dashboard, add the source. Then, from the list of destinations, select HubSpot.
  2. Assign a name to the destination and click on Continue.

Connection settings

To successfully configure HubSpot as a destination using the new API, you can choose any of the two authorization types explained below:

Private Apps authorization type

The Private Apps authorization type enables you to use HubSpot's APIs to access specific data from your HubSpot account.

HubSpot connection settings
  • Access Token: Enter your HubSpot access token from the Private Apps section in the HubSpot dashboard.
Refer to the FAQ section for more information on getting the HubSpot access token.
  • API Version: Select New API (v3) from the dropdown.

API Key authorization type

The API Key (deprecating soon) authorization type lets you create custom applications using HubSpot's APIs.

This authorization type will be deprecated soon. Refer to HubSpot documentation for more information.
HubSpot connection settings
  • Hub ID: Enter your HubSpot Hub ID.
  • API Key: Enter your HubSpot API key. This field is mandatory to send data to HubSpot via the RudderStack cloud mode.
Refer to the FAQ section to know where to get the Hub ID and API Key.
  • API Version: Select New API (v3) from the dropdown.

Event and property names

HubSpot connection settings
  • HubSpot property name to be used as lookup field: Enter the unique HubSpot property to be used as a lookup field for HubSpot contacts.

The below settings are only applicable for the Private Apps authorization type:

  • RudderStack Event Name: Enter the RudderStack event name you want to map to the custom behavioral event created in HubSpot.
  • HubSpot Event Name: Enter the tracking ID of the HubSpot custom behavioral event you want to map to the above-mentioned RudderStack event.
  • Map your Event Property: Although HubSpot provides some default properties with custom behavioral events, you can create custom properties and map them to the RudderStack properties using this field. You can also specify multiple properties for a single event.
Refer to the Custom behavioral events section below for more information.

Client-side events filtering

HubSpot connection settings
These settings are applicable only if you're sending events to HubSpot via the web device mode. Refer to the Client-side Event Filtering guide for more information on this feature.

Identify

RudderStack sends the identify call to check if a contact exists, if it does, RudderStack updates the user with the new information. Otherwise, it creates a new user.

A sample identify call is as shown:

rudderanalytics.identify({
firstName: "Alex",
city: "New Orleans",
country: "USA",
phone: "+1-202-555-0146",
email: "alex@example.com",
custom_flavor: "chocolate",
custom_date: 1574769933368,
custom_date1: new Date("2019-10-14T11:15:53.296Z"),
})

Track

A track call lets you record various user actions and any properties associated with them.

To associate a track call with a user, you need to specify the user's email under context.traits.

RudderStack associates the track events with the same user after an identify request is successfully made. However, if you send a track call without making any identify call first, and there is no contact in HubSpot, there will be no association of events as there is no identifier.

A sample track event is as shown:

rudderanalytics.track(
"Order Completed", {
value: 30,
}, {
context: {
traits: {
firstname: "Alex",
city: "New Orleans",
country: "USA",
phone: "+1-202-555-0146",
email: "alex@example.com",
},
},
}
)

Property mappings

The following table lists the optional property mappings between RudderStack and HubSpot for the track call:

RudderStack propertyHubSpot property
traits.utk/context.traits.utk/properties.utkutk
emailemail
properties.occurred_at/originalTimestampoccurredAt
traits.objectId/context.traits.objectId/properties.objectIdobjectId

Custom behavioral events

The custom behavorial events can be used for both the authentication types. However, they must have the analytics.behavioral_events.send permission to be used for private apps.

Custom behavioral events are account-defined events in HubSpot that store event details in the event properties. You can create custom behavioral events and their associated properties in the RudderStack dashboard as explained in the event and property names section.

The following parameters are sent in the custom behavorial events:

  • Identifier: Either the contact ID, email, or utk (user token) of the contact associated with the event. The utk is the user token stored in the visitor's hubspotutk browser cookie.
  • Event name: The internal name of the event which can be found in HubSpot.
  • Properties object: When you create a custom behavioral event in HubSpot, some default properties are provided with those events, explained in the below section.

Property mappings

The following table lists the optional and default property mappings between RudderStack and HubSpot for custom behavioral events:

RudderStack propertyHubSpot property
properties.assetDescription/properties.hsAssetDescriptionhs_asset_description
properties.assetType/properties.hsAssetTypehs_asset_type
properties.campaignIdhs_campaign_id
traits.address.city/context.traits.address.city/properties.address.cityhs_city
traits.address.country/context.traits.address.country/properties.address.countryhs_country
context.device.namehs_device_name
properties.elementClass/properties.hsElementClasshs_element_class
properties.elementId/properties.hsElementIdhs_element_id

FAQ

Where do I get the API Key and Hub ID for HubSpot?

Refer to the following HubSpot guides to get the API Key and Hub ID:

Where do I get the Access Token for HubSpot?

To get the Access Token:

  1. Log into your HubSpot account.
  2. Go to Integrations > Private Apps from the left sidebar.
  3. Click on your app to see the below:
Hubspot access token

Contact us

For more information on the topics covered on this page, email us or start a conversation in our Slack community.

Contents