Set up HubSpot Destination in RudderStack
5 minute read
This guide will help you set up HubSpot as a destination in RudderStack.
Connection compatibility
| Destination Information | |||
|---|---|---|---|
| |||
| Connection Modes | ||||
|---|---|---|---|---|
| Source | Cloud mode | Device mode | Hybrid mode | Device Mode Transformations |
| AMP |  |  | | |
| Android (Java) | | | | |
| Android (Kotlin) | | | | |
| Cloud | | | | |
| Cordova | | | | |
| Flutter | | | | |
| iOS (Obj-C) | | | | |
| iOS (Swift) | | | | |
| React Native | | | | |
| Shopify | | | | |
| Unity | | | | |
| Warehouse | | | | |
| Web | | | | |
| Supported sources | | | | | | | | |
| Web | | | | | | | | |
Domain allowlisting for web device mode
In web device mode, RudderStack loads the HubSpot native SDK from https://js.hs-scripts.com. The script path contains your account ID (Hub ID). Depending on your Content Security Policy, allow these sources in script-src.
You can monitor vendor scripts with a report-only Content Security Policy.
Setup
- In your RudderStack dashboard, set up a source.
- Go to the Overview tab of your source and select Add Destination > Create new destination.
- Select HubSpot from the list of destinations. Then, click Continue.
Connection settings
| Setting | Description |
|---|---|
| Name | Assign a name to uniquely identify the destination in your RudderStack dashboard. |
| API Version | Select the HubSpot API version from the dropdown. RudderStack supports both the New API (v3) and Legacy API (v1) (deprecated). |
HubSpot has deprecated the legacy API (v1). RudderStack recommends using the New API (v3) instead.
Authentication settings
HubSpot API key authentication is no longer supported. Use either a HubSpot private app access token or a service key to authenticate your HubSpot destination. Both credential types work with the New API (v3) and Legacy API (v1).
HubSpot service keys are in public beta and are subject to the HubSpot Developer Terms and HubSpot Beta Terms.
| Setting | Description |
|---|---|
| Access Token | Specify a HubSpot private app access token or service key. This setting applies to both the New API (v3) and Legacy API (v1). |
Required scopes
Grant your private app access token or service key only the scopes required for the HubSpot features you use.
For Event Stream connections that send identify calls or update HubSpot contact properties, grant these CRM contact scopes:
crm.objects.contacts.read
crm.objects.contacts.write
crm.schemas.contacts.readIf you use the New API (v3) and send track calls as HubSpot custom behavioral events, including Reverse ETL events sent through the JSON Mapper, also grant this scope:
analytics.behavioral_events.sendNote that this scope does not apply to the Legacy API (v1), which sends track events to HubSpot’s tracking endpoint using the Hub ID rather than a scoped credential.
For Reverse ETL connections, object syncs, and association workflows, grant the following CRM object, list, and schema scopes:
crm.lists.read
crm.objects.contacts.read
crm.objects.contacts.write
crm.schemas.custom.read
crm.objects.custom.read
crm.objects.custom.write
crm.schemas.custom.write
crm.objects.companies.write
crm.schemas.contacts.read
crm.lists.write
crm.objects.companies.read
crm.objects.deals.read
crm.objects.deals.write
crm.schemas.companies.read
crm.schemas.companies.write
crm.schemas.contacts.write
crm.schemas.deals.read
crm.schemas.deals.write
crm.objects.owners.read
crm.objects.quotes.write
crm.objects.quotes.read
crm.schemas.quotes.read
crm.objects.line_items.read
crm.objects.line_items.write
crm.schemas.line_items.readFor instructions on assigning scopes, see the HubSpot documentation for private app access tokens and account service keys.
New API settings
These settings are only applicable if you selected New API (v3) as the API version:
| Setting | Description |
|---|---|
| HubSpot property to be used for upsert | Enter the contact property that RudderStack uses as a lookup field to match contacts in HubSpot, for example, uniqueId. Make sure to then pass the same property in the identify event’s traits object with the value to upsert.For best performance, use a property that is unique in HubSpot — unique properties enable batch upsert and higher throughput, whereas non-unique properties use a slower search-based flow. For more information, see HubSpot’s Create or update a batch of contacts API reference.
See the identify section for more information. |
| Create association between object records | Toggle 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
| Setting | Description |
|---|---|
| Hub ID | Specify your HubSpot Hub ID. See the HubSpot documentation for more information on obtaining this ID. |
Consent settings
| Setting | Description |
|---|---|
| Consent settings | Configure 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:
| Setting | Description |
|---|---|
| Client-side Events Filtering | This 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
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.
You can also specify multiple properties for a single event.
FAQ
Where can I find the HubSpot access token?
For new setups, create a service key:
You need to be a Super admin or have the Developer tools access permission in your HubSpot account to create and manage service keys.
- Log in to your HubSpot account.
- Go to Development > Keys > Service keys. You can also open service keys from Settings > Integrations > Service Keys.
- Create a service key, select the required scopes, and copy the key.
HubSpot recommends rotating service keys every six months. If you choose Rotate and expire later, the old key expires after a seven-day grace period. Update the destination’s Access Token during that period to avoid delivery failures.
Alternatively, if your account has an existing private app:
- Go to Integrations > Private Apps from the left sidebar.
- Select your app to get the access token:
HubSpot removed legacy private app creation for accounts created on or after September 28, 2026, and will remove it for existing accounts on October 26, 2026. Existing private app access tokens continue to work, but use a service key for new setups.
See the HubSpot changelog for details.
For more information, see the HubSpot documentation for private app access tokens and account service keys.
