# Set up HubSpot Destination in RudderStack

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

## Connection compatibility

{{< destination-config >}}

{{< info >}}
In the web device mode integration, that is, using [JavaScript SDK]({{< ref "sources/event-streams/sdks/rudderstack-javascript-sdk/_index.md" >}}) 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]({{< ref "sources/event-streams/sdks/rudderstack-javascript-sdk/load-js-sdk.md#allowlist-destination-domain" >}}) to load the HubSpot SDK successfully.
{{< /info >}}

## Setup

1. In your [RudderStack dashboard](https://app.rudderstack.com/), set up a source.
2. Go to the **Overview** tab of your source and select **Add Destination** > **Create new destination**.

{{< image src="images/event-stream-destinations/add-new-destination.webp" alt="Add new destination in RudderStack dashboard" >}}

3. Select **HubSpot** from the list of destinations. Then, click **Continue**.

### Connection settings

| Setting | <div style="width: 350px;">Description</div> |
| :----| :-----|
| 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).  |

{{< danger >}}
HubSpot has deprecated the legacy API (v1). RudderStack recommends using the New API (v3) instead.
{{< /danger >}}

### Legacy API settings

| Setting | <div style="width: 350px;">Description</div> |
| :---| :----|
| Authorization Type | Select the authorization mechanism from **API Key** (deprecated) or **Private Apps**. |
| API Key | If you selected **API Key**, specify your HubSpot API key. You can find this by going to **Settings** > **Integrations** > **API Key** in your HubSpot account. <br /><br />{{< warning >}}HubSpot has [deprecated](https://developers.hubspot.com/docs/guides/apps/authentication/intro-to-auth) the API key authentication mechanism.{{< /warning >}} |
| Access Token | If you selected **Private Apps**, specify the [HubSpot access token](#where-can-i-find-the-hubspot-access-token). |

### New API settings

These settings are only applicable if you selected **New API (v3)** as the API version:

| Setting | <div style="width: 350px;">Description</div> |
| :---| :----|
| Authorization Type | Select the authorization mechanism from **API Key** (deprecated) or **Private Apps**. <br /><br /><ul><li>If you select **API Key**, then specify your HubSpot API key by going to **Settings** > **Integrations** > **API Key**. Note that HubSpot has [deprecated](https://developers.hubspot.com/docs/guides/apps/authentication/intro-to-auth) the API key authentication mechanism.</li><li>If you select **Private Apps**, then specify the [HubSpot access token](#where-do-i-get-the-access-token-for-hubspot).</li></ul> |
| HubSpot property to be used for upsert | Enter the contact property that RudderStack uses as a lookup field to [match contacts in HubSpot](https://developers.hubspot.com/docs/api/crm/contacts), for example, `uniqueId`. Make sure to then pass the same property in the `identify` event's `traits` object with the value to upsert. <br /><br />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. <br /><br />For more information, see HubSpot's [Create or update a batch of contacts](https://developers.hubspot.com/docs/api-reference/crm-contacts-v3/batch/post-crm-v3-objects-contacts-batch-upsert) API reference. <br /><br />{{< info >}}**This setting is available only when using the new HubSpot API**. <br /><br />In the legacy API, RudderStack supports updating a contact only via email.{{< /info >}} <br />See the [`identify`]({{< ref "destinations/streaming-destinations/hubspot/cloud-mode/new-api.md#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.<br /><br />See [Creating associations between object records]({{< ref "destinations/streaming-destinations/hubspot/connect-retl-source.md#create-association-between-object-records" >}}) section for more information. |

### Configuration settings

| Setting | <div style="width: 350px;">Description</div> |
| :---| :----|
| Hub ID | Specify your HubSpot Hub ID. <br /><br />See the [HubSpot documentation](https://knowledge.hubspot.com/account/manage-multiple-hubspot-accounts#identify-the-current-account-s-hub-id) for more information on obtaining this ID. |

### Consent settings

| Setting | <div style="width: 350px;">Description</div> |
| :---| :----|
| 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. <br /><br />See [Consent Management in RudderStack]({{< ref "data-governance/consent-management/overview.md" >}}) 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]({{< ref "destinations/rudderstack-connection-modes.md#device-mode" >}}):

| Setting | <div style="width: 350px;">Description</div> |
| :---| :----|
| Client-side Events Filtering | This setting lets you specify which events should be blocked or allowed to flow through to HubSpot. <br /><br />See [Client-side Events Filtering]({{< ref "sources/event-streams/sdks/event-filtering.md" >}}) for more information on this feature. |

### Event mapping settings

{{< warning >}}
These settings are applicable only for the New HubSpot API.
{{< /warning >}}

Click **Set up mapping** and map RudderStack events to your HubSpot [custom behavioral events]({{< ref "destinations/streaming-destinations/hubspot/cloud-mode/new-api.md#custom-behavioral-events" >}}).

Although HubSpot provides some [default properties]({{< ref "destinations/streaming-destinations/hubspot/cloud-mode/new-api.md#behavioral-events-property-mappings" >}}) 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?

1. Log in to your [HubSpot account](https://app.hubspot.com/login/).
2. Go to **Integrations** > **Private Apps** from the left sidebar.
3. Click your app to get the access token:

{{< image src="images/event-stream-destinations/Hubspot-access-token.webp"  >}}

{{< warning >}}
If you're connecting a [Reverse ETL]({{< ref "sources/reverse-etl/_index.md" >}}) source to HubSpot that uses [private app access token](https://developers.hubspot.com/docs/api/intro-to-auth#private-app-access-tokens) for authentication, make sure your access token has the [required scopes]({{< ref "destinations/streaming-destinations/hubspot/connect-retl-source.md#required-scopes" >}}).

See the [HubSpot documentation](https://developers.hubspot.com/docs/api/migrate-an-api-key-integration-to-a-private-app#create-a-new-private-app) for more information on adding the above scopes.
{{< /warning >}}