HubSpot Integration
Sync Fanflet engagement to HubSpot contacts. Auto-created custom properties, OAuth scopes, event subscriptions, and the test flow.
What this integration does
The HubSpot integration pushes Fanflet events into HubSpot as contacts. Subscriber signups, lead captures, and connection state changes flow one-way from Fanflet to HubSpot. Returning leads upsert by email. Fanflet creates a dedicated contact-property group on connect so every synced field lands in the right place.
Plan requirement
OAuth scopes Fanflet requests
During the authorization screen HubSpot lists the scopes Fanflet needs. The full set:
oauthbase scope for issuing access and refresh tokens.crm.objects.contacts.readcheck whether a contact exists before insert.crm.objects.contacts.writecreate and update contact records.crm.schemas.contacts.writeregister the Fanflet property group and contact properties on first connect.
Connect HubSpot
Open Integrations
In the sponsor dashboard sidebar, open Integrations. Find the HubSpot card.
Click Connect HubSpot
Fanflet redirects you to HubSpot's authorization screen. Pick the HubSpot account to connect and approve the requested scopes.
Wait for property setup
On the redirect back, Fanflet calls HubSpot to register the Fanflet contact-property group and seven contact properties. The call is idempotent. Existing properties are kept as-is.
Confirm the green badge
The HubSpot card shows a green Connected badge. Open the Event settings panel to choose which events sync.
Fanflet contact properties
On first connect Fanflet creates a contact-property group named Fanflet in your HubSpot portal. The seven properties below are created inside it. No manual setup needed.
| HubSpot property | Stores |
|---|---|
fanflet_source | Title of the fanflet page where the lead came in. |
fanflet_speaker | Speaker whose page captured the lead. |
fanflet_sponsor_id | Internal Fanflet sponsor identifier. |
fanflet_event_type | Event that produced the contact write (e.g. subscriber.added, lead.captured). |
fanflet_campaigns | Comma-separated names of active campaigns on the speaker or resource. |
fanflet_campaign_tags | Analytics tags for those campaigns. Falls back to the default campaign tag set in connection settings. |
fanflet_resource_name | Title of the resource the lead clicked or downloaded. |
Standard HubSpot fields are written too: email, firstname, lastname, and company when the payload includes one.
Duplicate handling
What triggers a sync
The Event settings panel on the HubSpot card has a checkbox for each event type. Uncheck any you do not want pushed to HubSpot. All six are on by default.
subscriber.addednew email signup on a sponsored fanflet.lead.capturedresource click or download with consent on a sponsored fanflet.connection.accepteda speaker accepted your connection request.connection.declineda speaker declined your connection request.connection.endeda connection ended (by either party).report.vieweda shared report link was opened.
Lead origin comes from Sponsor lead generation. The default campaign tag in connection settings fills fanflet_campaign_tags when no campaign is assigned to the speaker.
Send a test event
The Send test event button on the HubSpot card creates a synthetic contact in your HubSpot portal end-to-end. Use it right after connecting to confirm the OAuth token, property group, and write path all work.
Click Send test event
The button is in the connection footer.
Check HubSpot Contacts
Open Contacts in HubSpot and search for the test email. The Fanflet property group is populated.
Check the activity log
In Fanflet, scroll to Recent activity. Toggle Show test events on. Look for a row with status success.
Activity log
The Recent activity card below the integration cards lists every event Fanflet has tried to push. Filter by status (Success, Failed, Pending, Retrying) and toggle Show test events to include test traffic.
Failed rows have a Retry action. Click it to re-queue the event. Fanflet auto-retries up to three times on retryable errors (5xx, rate-limit, expired token). Permanent errors (validation, missing email) do not auto-retry.
Pause vs disconnect
Pause keeps the OAuth token and configuration in place but stops sending events to HubSpot. Resume to start syncing again. Good for short windows like a campaign freeze or a HubSpot portal migration.
Disconnect revokes the OAuth token at HubSpot via the uninstall endpoint and removes the connection from Fanflet. Reconnecting requires a fresh OAuth flow. Contacts already written to HubSpot stay where they are. Manage them in HubSpot if you need to delete or merge.
Troubleshooting
Connection shows Expired
HubSpot access tokens last 30 minutes. Fanflet refreshes them transparently using the long-lived refresh token, so you do not need to re-authorize on a schedule. An Expired badge means the refresh itself failed. The usual cause is the user revoking Fanflet from HubSpot's Connected Apps. Click Disconnect, then Connect HubSpot again.
Missing-scope errors
If property creation fails with a permission error, the OAuth consent did not include crm.schemas.contacts.write. Disconnect and reconnect, then approve all four scopes on the HubSpot screen.
Failed events in the log
Open Recent activity, set the status filter to Failed, and read the error column. Common causes: HubSpot rate limit (10 requests/second on Free tier), invalid email format, or the connected portal was deleted. Click Retry on a row to re-queue it.
Where to go next
- Sponsor lead generation covers where the leads in HubSpot come from and how to scope them per speaker.
- Zapier integration is the alternative for sponsors on a non-Studio plan or for routing the same events to other CRMs.