Hubspot setup for Data Activation

HubSpot is a customer relationship management (CRM) platform that companies use to organize their contacts and run marketing, sales, and service campaigns. The HubSpot destination connector lets you activate your audiences directly inside HubSpot by keeping a HubSpot Contact list in sync with a Data Activation audience or journey.

When you connect HubSpot to Data Activation, you can:

• Activate CRM audiences: Push the contacts in a Data Activation audience into a HubSpot Contact list so your teams can target them in HubSpot campaigns.

• Keep lists current automatically: As profiles enter or leave the connected audience or journey, the connector adds or removes the matching contacts in the HubSpot list for you.

• Target known customers: Match on the HubSpot Contact Record ID, a first-party CRM identifier, so no cookies or hashed personal data are needed.

How list membership works

The connector keeps a single HubSpot Contact list aligned with your audience. It sends two sets of HubSpot Contact Record IDs in one request:

• Contacts to add: Profiles that have newly entered the audience or journey.

• Contacts to remove: Profiles that left the audience or journey.

HubSpot returns which records were added, which were removed, and which could not be found. Because the connector matches on HubSpot's own Contact Record ID, the contacts must already exist in HubSpot.

Destination connector overview

Connector limitations and known issues

• Manually managed lists only: The connector adds and removes members on manually managed Contact lists. It does not manage HubSpot Active lists, which HubSpot automatically evaluates based on filters.

• Single identifier: Matching uses the HubSpot Contact Record ID only. Matching by email address or company is not supported.

• Add and remove only: The connector adds and removes list members. It does not update contact properties or other attributes in HubSpot.

Before you begin

Make sure you have the following in place before configuring the connector:

• A HubSpot account with admin access to authorize an app and manage Contact lists.

• A HubSpot app for OAuth that provides a client ID and client secret. During the setup, you authorize this app so Data Activation can obtain and refresh access tokens. See HubSpot OAuth quickstart for more information

• The required HubSpot scopes granted to the app: read and write access to contacts and to lists (crm.objects.contacts.read, crm.objects.contacts.write, crm.lists.read, and crm.lists.write).

• A target Contact list in HubSpot, or permission to create one. The connector works with manually managed Contact lists.

Instructions

Setting up HubSpot takes two steps. First, you configure the HubSpot destination, then you add it to an audience or journey.

Step 1: Configure HubSpot destination

1. On the Data Activation platform, select Connectors in the left-side navigation bar.

2. Select Server to Server and click New Connector.

3. Select HubSpot.

4. Authorize HubSpot. Sign in to your HubSpot account and grant the requested permissions so Data Activation can manage your Contact lists.

5. Select the target List, or create a new manually managed Contact list for this connector.

6. Click Save.

Step 2: Add the destination connector to an audience or journey

1. On the Data Activation platform, go to Orchestration.

2. Add the HubSpot destination connector.

3. Map the HubSpot Contact Record ID as the identifier sent to HubSpot.

4. Activate the audience or journey.

Now, whenever profiles enter or leave the connected audience or journey, the connector updates the HubSpot list automatically: new profiles are added as list members, and profiles that leave are removed.

Error handling

The connector handles HubSpot responses as follows. Recoverable errors are retried automatically, while terminal errors stop the request and need attention.

An error response from HubSpot looks like this:

{
  "status": "error",
  "message": "Invalid input",
  "correlationId": "a1b2c3d4-0000-0000-0000-000000000000",
  "category": "VALIDATION_ERROR"
}

The correlationId value is useful when you contact HubSpot support about a specific failed request. For the full list of error categories, see HubSpot's CRM Lists API documentation.

FAQs

Which HubSpot identifier does the connector use? The connector uses the HubSpot Contact Record ID, which is HubSpot's first-party identifier for Contact records. Contacts must already exist in HubSpot to be added to a list.

Does the connector create or update contact properties? No. The connector only adds contacts to and removes contacts from a HubSpot list. It does not create contacts or change their properties.

What kind of HubSpot list does the connector use? A manually managed Contact list. The connector does not manage HubSpot Active lists, which HubSpot builds and updates automatically from filter rules.

Do I need cookie sync for this connector? No. The connector matches on the HubSpot Contact Record ID, so no cookie sync or hashed personal data is required.

See HubSpot’s documentation for HubSpot API usage and rate limits