HubSpot

The HubSpot connection links FunnelStory to your HubSpot portal via OAuth so you can build data models on companies, deals, contacts, engagements, and behavioral events. It also powers CRM sync and supports AI-assisted configuration through the MCP server.

What FunnelStory syncs from HubSpot

When you connect HubSpot and configure models, FunnelStory automatically syncs the following data into its integration tables:

What	How	Used for
Companies	Paginated list API	Account and user model resolution
Deals	Paginated list API	Account model (deals-based accounts)
Contacts	v3 search API scoped to deal companies	User model, email engagement resolution
Email engagements	v3 CRM search API scoped to deal companies	Email conversation model, or automatic import with Sync Emails
Behavioral events (page views, form submissions, marketing email opens and clicks, link clicks, CTA clicks)	Contact events API	Non-product activity models

Scoped syncs

Engagements and contacts are synced only for companies that already have deals in HubSpot. This keeps sync fast and focused on accounts you actively manage.

HubSpot notes, calls, and meetings aren't imported, so build notes and meetings from FunnelStory or another source instead.

How HubSpot emails are threaded

With Sync Emails on, logged HubSpot emails are grouped into threads using HubSpot's own email thread ID. The earliest message in a thread becomes the thread's first conversation, and later replies appear under it, even when they sync in a different run or out of order. Emails that HubSpot holds no mail headers for have no thread ID, so each one stays a standalone conversation.

Before you connect

• Use a HubSpot user with access to the objects and properties you plan to query or sync.
• In HubSpot Settings → Integrations → Private Apps (or OAuth apps), ensure the scopes FunnelStory requests are approved — your onboarding or support team can confirm the exact scope list for your workspace.

Add the connection in FunnelStory

1. Open Configuration → Connections → Add connection, then choose HubSpot under application integrations.

2. Complete the fields in the connection form:

Field	Description
Connection name	Label in FunnelStory (for example HubSpot Production).
Sync Visibility	When enabled, each connection Sync also refreshes HubSpot account visibility for workspace users. See CRM visibility.
Sync Emails	When enabled, FunnelStory imports logged HubSpot emails as conversations automatically and threads them (see below), with no email conversation model needed. Don't also configure an email conversation model, or every email is imported twice.

3. Click Connect to start OAuth.

4. Approve access on HubSpot's consent screen.

Configure models

After connecting, configure models in this order. Each model depends on the previous one:

1. Accounts model — built from deals + companies.
2. Users model — built from contacts matched to deal companies by email domain.
3. Engagement models — Conversations (skip if Sync Emails is on) and Non-product activity — require contacts to be synced first.

Configure in order

Always configure the accounts model before users, and users before conversation or activity models. Contacts are synced only for companies with deals, so the accounts model must have refreshed first. Without contacts, engagement queries cannot resolve which account an email or event belongs to.

Using Claude to configure models

The fastest way to configure HubSpot models is through the MCP server with Claude. Claude can read your HubSpot schema, preview queries, and create all required models in the correct order with one conversation.

See Configure HubSpot models with Claude for a step-by-step walkthrough.

Manual configuration

You can also configure models manually from Configuration → Data models → Add model. Use the HubSpot connection and write SQL-style queries using the virtual tables described below.

HubSpot virtual tables

When you query a HubSpot connection, FunnelStory exposes the following virtual tables:

Table	Contents
companies	HubSpot companies with id, domain, properties
deals	HubSpot deals with id, data
deal_companies	Mapping of deal IDs to company IDs
contacts_v2	Contacts with id, email, properties (includes associatedcompanyid)
engagements	Emails with id, type, timestamp, data
engagement_companies	Maps engagement IDs to company IDs
engagement_contacts	Maps engagement IDs to contact IDs
page_views	Behavioral events (page views, form submissions, etc.) with id, email, account_id, event_type, timestamp, properties

Behavioral event types

The page_views table surfaces six HubSpot contact event types via the event_type column:

event_type	HubSpot event
e_visited_page	Website page view
e_submitted_form	Form submission
e_opened_email	Marketing email opened
e_clicked_email	Marketing email clicked
e_clicked_link	Link clicked
e_clicked_cta	CTA clicked

Each event type can be configured as a separate Non-product activity model to track different types of marketing engagement on the account timeline.

Related links

• Configure HubSpot models with Claude — AI-assisted configuration walkthrough
• CRM visibility
• Salesforce
• Attio
• Data connections overview