Setup Guide

Set up HubSpot as a destination in RudderStack.

  •   4 minute read  

This guide will help you set up HubSpot as a destination in RudderStack.

Connection compatibility

Destination info
  • Status: Generally Available
  • Supported sources: Android, iOS , Web, Unity, AMP , Cloud, Warehouse, React Native , Flutter, Cordova, Shopify
  • Refer to it as HS in the Integrations object.

Connection modes
SourceCloud modeDevice modeHybrid mode
AMPsupportednot supportednot supported
Androidsupportednot supportednot supported
Cloudsupportednot supportednot supported
Cordovasupportednot supportednot supported
Fluttersupportednot supportednot supported
iOSsupportednot supportednot supported
React Nativesupportednot supportednot supported
Shopifysupportednot supportednot supported
Unitysupportednot supportednot supported
Warehousesupportednot supportednot supported
Websupportedsupportednot supported
Supported message types
SourceIdentifyPageTrackScreenGroupAliasRecord
Cloud mode
Supported sourcessupportednot supportedsupportednot supportednot supportednot supportednot supported
Device mode
Websupportedsupportedsupportednot supportednot supportednot supportednot supported
info

In the web device mode integration, that is, using JavaScript SDK as a source, RudderStack loads the HubSpot native SDK from the https://js.hs-scripts.com/ domain.

Based on your website’s content security policy, you might need to allowlist this domain to load the HubSpot SDK successfully.

Setup

In your RudderStack dashboard, add a source. Then, from the list of destinations, select HubSpot.

Connection settings

SettingDescription
NameAssign a name to uniquely identify the destination in your RudderStack dashboard.
API VersionSelect the HubSpot API version from the dropdown. RudderStack supports both the New API (v3) and Legacy API (v1) (deprecated soon).

Legacy API settings

danger
HubSpot will deprecate the legacy API (v1) on May 30, 2025. RudderStack recommends using the New API (v3) instead.
SettingDescription
Authorization TypeSelect the authorization mechanism from API Key (deprecating soon) or Private Apps.

  • If you select API Key, then specify your HubSpot API key by going to Settings > Integrations > API Key. Note that HubSpot has deprecated the API key authentication mechanism.
  • If you select Private Apps, then specify the HubSpot access token.

New API settings

SettingDescription
Authorization TypeSelect the authorization mechanism from API Key (deprecating soon) or Private Apps.

  • If you select API Key, then specify your HubSpot API key by going to Settings > Integrations > API Key. Note that HubSpot has deprecated the API key authentication mechanism.
  • If you select Private Apps, then specify the HubSpot access token.
HubSpot property to be used as lookup fieldEnter a unique property to be used as a lookup field for the HubSpot contacts, for example, hubspot_id. You must then pass this lookup field in the identify event’s traits object and RudderStack uses the field’s value to look up the contact.

See the identify section for more information.

Note: This setting is only available in the new HubSpot API. In the legacy API, RudderStack supports updating a contact only via email.
Create association between object recordsToggle on this setting to create associations between the object records while using a Reverse ETL source.

See Creating associations between object records section for more information.

Configuration settings

SettingDescription
Hub IDSpecify your HubSpot Hub ID.

See the HubSpot documentation for more information on obtaining this ID.
SettingDescription
Consent settingsConfigure the consent management settings for the specified sources by choosing the Consent management provider from the dropdown and entering the relevant consent category IDs.

See Consent Management in RudderStack for more information on this feature.

Web device mode settings

The below setting is applicable only if you want to send events to HubSpot in the web device mode:

SettingDescription
Client-side Events FilteringThis setting lets you specify which events should be blocked or allowed to flow through to HubSpot.

See Client-side Events Filtering for more information on this feature.

Event mapping settings

warning
These settings are applicable only for the New HubSpot API.

Click Set up mapping and map RudderStack events to your HubSpot custom behavioral events.

Although HubSpot provides some default properties with custom behavioral events, you can create additional custom properties and map them to specific RudderStack properties using these settings.

info
You can also specify multiple properties for a single event.

FAQ

Where can I find the HubSpot access token?

  1. Log in to your HubSpot account.
  2. Go to Integrations > Private Apps from the left sidebar.
  3. Click your app to get the access token:
warning

If you’re connecting a Reverse ETL source to HubSpot that uses private app access token for authentication, make sure your access token has the required scopes.

See the HubSpot documentation for more information on adding the above scopes.

Questions? Contact us by email or on Slack