HubSpot Audience
Private Beta4 minute read
The HubSpot Audience destination is in Private Beta.
Reach out to Customer Success to enable it for your workspace.
HubSpot is a CRM and marketing platform. HubSpot Audience keeps a HubSpot static contact list in sync with a warehouse table, SQL model, Audience Builder audience, or Lookout audience. You can attach an existing list or create a new empty list during setup. Incremental syncs add contacts who entered the source and remove contacts who left it.
HubSpot Audience is separate from the Event Stream HubSpot destination.
- Use HubSpot to create and update contacts and send Event Stream traffic.
- Use HubSpot Audience only to change list membership. This sync does not create or update contacts.
Links
You can use the HubSpot Audience destination in these ways:
- Connect a Reverse ETL source to HubSpot Audience
- Sync from Audience Builder to HubSpot Audience
- Use it from Lookout
Syncing from Audience Builder to HubSpot Audience is possible only if Audience Builder is enabled for your workspace.
Prerequisites
Authenticate with a HubSpot Service Key. The key needs these scopes:
| Scope | Purpose |
|---|---|
crm.lists.read | List static contact lists and read the selected list. |
crm.lists.write | Create a new contact list during setup, and add and remove list members. |
crm.objects.contacts.read | Find contacts by email and check Record IDs. |
crm.objects.contacts.write | Required by HubSpot for list membership changes. This scope also allows contact edits, so use a dedicated Service Key limited to the scopes above. |
Note that:
- When you attach an existing list, setup confirms that the list exists and can be read. It does not prove that the key has membership-write or contact-read scopes.
- Creating a list during setup also requires
crm.lists.write. A missing membership or contact-read scope fails later, during sync. - An existing HubSpot private app token (
pat-…) with the same scopes also works for compatibility. Prefer a Service Key for new setups.
How membership is written to HubSpot
RudderStack supports only Mirror mode for this destination.
| Action | HubSpot operation |
|---|---|
| Insert or update | Add the resolved contact to the list. |
| Delete | Remove the resolved contact from the list. |
A full sync runs on the first run for a connection, after a data-mapping change, after a source schema change, and when you manually select Run full sync. A full sync adds current members but removes none. Members who left before a full sync can remain on the list after later incremental syncs. To remove them, remove the contacts in HubSpot or recreate the list and create a new RudderStack connection targeting it.
Row outcomes:
- An empty Record ID falls back to email when email is mapped. A well-formed Record ID that HubSpot does not know fails an add and counts as already gone on a delete.
- An email that does not resolve to a HubSpot contact fails on both add and delete.
- A failed delete can be retried on later runs when failed-record retry is enabled.
- Changing the mapped contact identity can leave the previously resolved contact on the list. Inspect and clean up surviving memberships in HubSpot if needed.
Membership requests send at most 1,000 contacts per request. Email lookup runs in groups of at most 100.
If a sync fails
Membership updates fail if the key lacks required write scopes, HubSpot rejects the key, or the selected list has been deleted.
- Missing write permissions: Restore the
crm.lists.writeandcrm.objects.contacts.writescopes on the key. - Rejected or revoked key: Update the connected HubSpot account with a valid Service Key that has the required scopes.
- Deleted list: Create a new RudderStack connection targeting an existing or newly created static contact list. The original connection stays fixed to the deleted list ID.
Stop a sync
Disabling or deleting the RudderStack connection, or deleting a Lookout activation, does not call HubSpot. The list and its members stay as they are, including lists created during setup. Remove members or delete the list in HubSpot if you no longer want them.
Use it from Lookout
The same HubSpot Audience destination is available when you activate an audience in Rudder Lookout:
- Select HubSpot Audience as the destination type.
- Choose a RudderStack account that uses a HubSpot Service Key. There is no ad-account step; the Service Key identifies the HubSpot portal.
- Choose Use existing list (default) or Create new list. Create new list prefills the Lookout audience name; you can edit it before submitting.
- Map identifiers using the same Record ID and email rules. See Map identifiers.
- Choose a sync schedule and enable the sync.
Important considerations
- Editing an activation keeps the HubSpot list fixed.
- Renaming the Lookout audience does not rename the HubSpot list.
