HubSpot Integration

Fluentos connects to HubSpot using OAuth for secure, token-based authentication. No API keys are required from your side — simply click Authenticate with HubSpot and authorize the connection.

How it works

When you connect HubSpot, Fluentos requests the following permissions on your HubSpot account:

Permission	Purpose
crm.objects.contacts.read	Read visitor contacts for audience targeting and personalization
crm.objects.contacts.write	Create or update contacts from form submissions
crm.lists.read	Fetch available lists for audience targeting and mapping
crm.lists.write	Add submitted contacts to selected lists
communication_preferences.read	Fetch available HubSpot subscription types for consent mapping
communication_preferences.write	Update contact email subscription consent status

Setup

1. Navigate to Integrations in your Fluentos workspace.
2. Click Add Integration.
3. Select HubSpot from the provider list.
4. Give the integration a name (e.g. “HubSpot Production”).
5. Click Authenticate with HubSpot.
6. A popup opens — log in to your HubSpot account if needed and grant permissions.
7. The popup closes and the integration shows as Connected.
8. Optionally enable Audience Targeting to personalize campaigns based on HubSpot list membership.
9. Click Save.

Audience Targeting

When enabled, Fluentos identifies visitors arriving from HubSpot links (via the _hbs_contact_id URL parameter or cookie) and checks which HubSpot lists they belong to. This allows you to:

• Show or hide campaigns based on list membership.
• Personalize campaign content using visitor contact data (email, first name) stored in DataHub.

Required for HubSpot email audience targeting: your HubSpot link must include the contact ID merge token in the URL, for example:

?_hbs_contact_id={{contact.hs_object_id}}

Configuration

• URL Parameter (default: _hbs_contact_id) — the query parameter used to pass the HubSpot contact ID from email links or landing pages (for example ?_hbs_contact_id={{contact.hs_object_id}}).
• Cookie Name (default: _hbs_contact_id) — stores the visitor contact ID for return visits.

DataHub fields

Selected contact fields from HubSpot are stored in Fluentos DataHub for use in campaign personalization:

Field	DataHub key	Description
Contact ID	{{dataHub:hubspot-contactId}}	Always stored. Required for visitor identification.
Email	{{dataHub:hubspot-email}}	Optional. Visitor’s email address.
First Name	{{dataHub:hubspot-firstName}}	Optional. Visitor’s first name.

HubSpot lists and segments

HubSpot uses lists as the underlying object for both static audiences and dynamic segments. In the Fluentos integration, lists are used in two different ways depending on the feature:

Audience targeting

For audience targeting, Fluentos uses all list types — including dynamic (active) lists and manual lists. This is because list membership in HubSpot acts as the equivalent of a Klaviyo segment: it tells Fluentos whether a visitor belongs to a defined audience.

When a visitor is identified, Fluentos queries HubSpot for the contact’s list memberships and matches them against the list you selected in the campaign targeting rule.

Fluentos uses POST /crm/lists/2026-03/search with objectTypeId: 0-1 (contacts) and processingTypes: ['DYNAMIC', 'MANUAL', 'SNAPSHOT'] to populate the audience targeting dropdown.

Form submission mapping

For form submissions, Fluentos only allows MANUAL or SNAPSHOT lists. HubSpot only lets you add or remove contacts from lists that are not actively managed by dynamic rules. When you map a form submission to a HubSpot list, the dropdown only shows lists with processingType: MANUAL or SNAPSHOT.

List type in HubSpot	processingType	Used for audience targeting	Used for form submission mapping
Static list	MANUAL	Yes	Yes
Snapshot list	SNAPSHOT	Yes	Yes
Active (dynamic) list	DYNAMIC	Yes	No

Consent sync (optional)

If enabled in the HubSpot integration mapping screen, Fluentos can update HubSpot email consent status after a successful contact create/update.

What you can configure

• Enable consent sync: turns consent updates on/off.
• Subscription type: choose the HubSpot subscription type to update.
• Consent status: SUBSCRIBED, UNSUBSCRIBED, or NOT_SPECIFIED.
• Legal basis: legal basis used for the consent update. Default: CONSENT_WITH_NOTICE.
• Legal basis explanation: additional context for audit/compliance needs. Default: Contact submitted a Fluentos form.

On GDPR-enabled HubSpot portals, legal basis and explanation are required for subscribe actions. Fluentos sends defaults if you leave them empty.

How it works

1. Fluentos upserts the contact in HubSpot.
2. Fluentos optionally adds the contact to the mapped list.
3. If consent sync is enabled and an email is present, Fluentos updates communication preferences for the selected subscription type.

Fluentos fetches available consent/subscription types from HubSpot communication preferences definitions, then updates status per contact email.

Choosing the right consent approach

You have two common ways to manage customer consent in HubSpot:

1. HubSpot workflow (recommended for double opt-in flows)

   • Keep Fluentos consent sync disabled.
   • Add contacts to a HubSpot list from Fluentos form submissions.
   • In HubSpot, build a workflow triggered by list membership to send your own double opt-in email and complete subscription only after confirmation.
   • Best when you want full control over confirmation messaging and compliance logic.

2. Fluentos consent sync (faster setup)

   • Enable consent sync in Fluentos mapping.
   • Choose the HubSpot subscription type and status to update.
   • Fluentos updates the subscription preference directly after contact submission.
   • Best when you want immediate subscription updates without an additional workflow layer.

Practical recommendation

• Use workflow-based double opt-in for markets or brands with strict consent verification requirements.
• Use Fluentos consent sync when your legal process allows immediate subscription updates at form submit time.
• You can combine both approaches by syncing to a dedicated subscription type and still using workflows for downstream communication control.

Disconnect

To disconnect the HubSpot integration:

1. Open the integration in edit mode.
2. Click the Disconnect button.
3. This removes all access tokens and the connection on the Fluentos side. You can also remove the app from your HubSpot account manually if needed.

You can re-authenticate at any time by clicking Authenticate with HubSpot again.

Troubleshooting

Issue	Solution
Authentication popup doesn’t open	Check if your browser is blocking popups for the Fluentos dashboard.
”Integration not valid” error	The OAuth session may have expired. Click Authenticate with HubSpot to reconnect.
Audience targeting not working	Ensure your HubSpot email links or landing pages include the _hbs_contact_id parameter and that your campaigns are published.
Audience targeting not matching from email clicks	Ensure HubSpot links include ?_hbs_contact_id={{contact.hs_object_id}} so Fluentos can resolve the visitor contact for list-based targeting.
No lists appear in the audience targeting dropdown	Verify that the connected HubSpot account has at least one list (static or dynamic). Active lists may take a moment to finish processing.
No lists appear in the form submission mapping	Only MANUAL and SNAPSHOT lists can receive form submissions. Dynamic (active) lists are not available in the dropdown.
Failed submissions	Check the error count in integration settings. Click Process failing entries to retry. Also verify that the selected list still exists and is not locked.