# Connect Reverse ETL Source to HubSpot Audience

The HubSpot Audience destination is in Private Beta.

Reach out to Customer Success to enable it for your workspace.

This guide takes you through the steps to connect a Reverse ETL source to your HubSpot Audience destination.

Before you start, make sure to complete the prerequisites — authenticate with a HubSpot Service Key that has the required scopes.

Start the connection from a warehouse table, SQL model, or existing audience source. HubSpot Audience accepts warehouse sources only.

Setup

Set up and configure your Reverse ETL source.
On the source Overview tab, click Add destination > Create new destination, or select an existing HubSpot Audience destination.
Select HubSpot Audience and click Continue.
Enter a unique destination name.
In the HubSpot account section, select an existing account or add a new one with an account name and Service Key:

Setting	Description
Account name	Enter an account name.
Service Key	Enter a HubSpot Service Key with the scopes in Prerequisites.

Configure the list and identifier mappings described below.

Mapping settings

This section lists the settings to correctly map data from your Reverse ETL source to the HubSpot Audience destination.

Choose a list

Choose how the connection targets a HubSpot static contact list. Use existing list is the default.

Use existing list: Select a static contact list. Active lists do not appear in the picker.
Create new list: Enter a list name. RudderStack creates an empty HubSpot static contact list when you finish setup, then saves the generated list ID on the connection.

HubSpot requires a unique list name in the portal. If HubSpot rejects the name (for example, because it is already in use) or the Service Key lacks crm.lists.write, fix the name or permissions and try again. RudderStack does not rename HubSpot lists after the connection is created.

If setup creates the HubSpot list but saving the RudderStack connection fails, select that list with Use existing list and continue. Do not create another list for the same connection.

If RudderStack cannot confirm whether HubSpot created the list, check HubSpot for an empty list with that name before creating again. Recovery prompts in the UI do not survive a page reload.

The connection stays locked to the selected list. Editing a connection keeps that list fixed. To sync a different list, create a new connection. The previous list and its memberships stay unchanged. Lists created during setup are not deleted automatically when you disconnect.

Sync mode

RudderStack supports only Mirror mode for this destination.

Map identifiers

Map warehouse columns to HubSpot contact identifiers. At least one complete identifier mapping is required.

Identifier	Behavior
HubSpot Record ID (used first)	Used first when the mapped value is present.
Email (used when Record ID is empty)	Used only when the Record ID is empty.

A bad Record ID does not fall back to email.

Note that:

Deduplicate the source first. Within a connection, each resolved HubSpot contact must correspond to one warehouse row. If two keys resolve to the same contact and only one leaves, that delete can remove the contact while the other row does not re-add it.
Preview shows warehouse rows only. It does not confirm which HubSpot contacts will match.
Mirror mode only removes contacts represented by this source. Other existing list members stay unchanged.

Sync settings

RudderStack determines how and when to run a sync based on the sync schedule you set for your Reverse ETL connection.

Schedule type	Description
Basic	Run syncs at a set interval, optionally starting from a specified time (UTC). If a start time is set, syncs run from that time until the end of that day.
CRON	Run syncs based on a specified CRON expression (in UTC).
Manual	Run syncs manually.

Sync observability settings

Setting

Description

Retain sync logs

This setting is toggled on by default and instructs RudderStack to store the sync logs in your warehouse. You can also configure the below settings:

Setting	Description
Sync log retention	Specify the retention period of the sync logs in your warehouse. If you set it to 1, then RudderStack deletes any sync log older than a day (in UTC time).
Snapshot table retention	Specify the number of snapshot tables to retain.

Retry failed records

This setting is toggled on by default and causes RudderStack to continually retry sending the failed records.

Retain and show failures

This setting is toggled off by default. Turn it on to have RudderStack write the error recorded for every failed record to a failed records table in your warehouse and show it in the sync’s failed records view. It applies from the next sync and can take up to a minute to reach your data plane.

Setting	Description
Failure retention	Number of days RudderStack keeps each sync’s failed records in your warehouse. The default is 30 and the minimum is 7.

Storing sync logs, snapshot tables, and failed records may incur additional warehouse costs.

Setup

Mapping settings

Choose a list

Sync mode

Map identifiers

Sync settings

Sync observability settings

See also