Skip to main content

HubSpot

The HubSpot integration pulls CRM data from your HubSpot account (deals, contacts, companies, and optionally leads) into Una so it can power your analytics — pipeline velocity, forecasting, account health, and any custom KPIs you configure.

The integration is read-only. Una never writes back to HubSpot.

What it does​

Three things happen across the integration's lifecycle:

  1. Connect — you authorise Una to read your HubSpot account via OAuth 2.0. Una stores an access token + refresh token + expiry against your tenant.
  2. Configure — you pick which HubSpot properties Una pulls, map your pipeline stages to Una model stages, and build (or pick) the analytical model.
  3. Sync and deploy — Una pulls the configured HubSpot data into a staging area and deploys it into your model so it's queryable through Una's matrices, dashboards, and report books.

Before you start​

You'll need:

  • Admin access to your HubSpot account (to grant OAuth scopes during the consent step).
  • Admin access in Una (you'll be configuring tenant-wide integration settings).
  • A few minutes for first-time setup. Subsequent reconnects are seconds.

Step 1 — Create the integration record​

  1. In Una, navigate to Settings → Integrations → CRM.
  2. Click New Integration (top right).
  3. Give it a name (e.g. HubSpot — Acme Sales Org) and pick HubSpot as the provider.
  4. Click Create. You land on the integration's General tab.

The integration record exists in Una now, but it isn't connected to HubSpot yet — it has no token.

Step 2 — Connect with HubSpot​

On the General tab, you'll see a red "Inactive" banner and a Connect with HubSpot button.

  1. Click Connect with HubSpot. A popup window opens at HubSpot's authorize page.
  2. If you're logged into multiple HubSpot accounts, HubSpot asks you to choose an account. Pick the one this Una integration should pull from.
  3. HubSpot shows the consent screen listing the scopes Una is requesting — read access to deals, contacts, companies, owners, and currency settings. Click Connect app.
  4. The first time you connect, HubSpot shows an "unverified app" warning. Type I accept the risk and click Connect.
  5. The popup closes itself; your Una tab refreshes and shows Active on the General tab, along with an "Expires at" date about an hour in the future.

You're connected. The token Una stored auto-refreshes silently when it nears expiry, so you don't need to reconnect every hour.

tip

If the popup didn't close on its own, or you saw a "This site can't be reached" error after authorising, see Troubleshooting below.

Step 3 — Choose the HubSpot data Una pulls (Data tab)​

Click the Data tab. You'll see a table per HubSpot object type, selected via the Property dropdown — Deal, Contact, Company, Lead. Una pre-populates a sensible default set of fields for each:

ObjectDefault fields pre-mapped
DealDeal Stage, Pipeline, Amount, Close Date, Deal Name, Deal Owner, Create Date, Last Modified Date
ContactEmail, First Name, Last Name, Create Date
CompanyName, Domain, Create Date
Lead(no defaults — lead pipelines require a HubSpot scope that not all accounts grant)

Each mapped row shows:

  • HubSpot Property — what the field is called in HubSpot (e.g. Close Date (closedate)).
  • Field Name — what Una stores it as. Defaults to hs_<object>_<property> (e.g. hs_deal_closedate). Editable for non-locked rows.
  • Track History — whether Una keeps a versioned history of value changes (useful for reporting on movement over time).

Locked fields​

Five Deal fields are required for Rev IQ to function and can't be unmapped:

  • dealstage — feeds the Stage dimension
  • pipeline — disambiguates multi-pipeline customers
  • amount — feeds the Volume KPI
  • closedate — feeds the Time dimension
  • dealname — anchors the deal in reports

These show as greyed-out inputs with locked Track History. If you try to save without them, Una rejects the request.

Adding more fields​

Above the table is an Add field… dropdown listing HubSpot properties not currently mapped. Pick one, click Add, and a new row appears with the default Una name pre-filled. You can edit the name before saving.

Resetting to defaults​

If you've over-customised and want to start over for one object type, click Reset to defaults (next to Save). A confirmation dialog warns you'll lose custom field names; click Reset → your mappings revert to the canonical default set for that object.

Click Save when done.

Step 4 — Map your pipeline stages (Pipelines tab)​

The Pipelines tab is how you tell Una what each HubSpot pipeline stage means in your business model. Una's analytical Rev IQ model has its own Stage dimension members (e.g. New, Qualified, Proposal, Closed Won, Closed Lost), and you decide which HubSpot stages map to which.

Layout:

  • The table is grouped by object type — Deal first, then Lead if your HubSpot account has lead pipelines.
  • Each row is a HubSpot pipeline stage. The stage column shows the stage name as primary text and the pipeline name below it in muted text — so if you have multiple pipelines, you can see which stage belongs to which.
  • The Model dropdown is where you pick the Una model stage to map to.
  • Is Closed Won is a checkbox HubSpot pre-fills from its own metadata; review and adjust if needed.

Pick a Model stage for every HubSpot stage you care about. Stages you don't map are still pulled but contribute nothing to Rev IQ analytics until they're mapped.

Click Save.

Step 5 — Refresh pipelines​

If you add a new pipeline or stage in HubSpot after connecting Una, the Pipelines tab won't show it until you refresh. Click Refresh Pipelines (top of the Pipelines tab). Una fetches the latest pipeline definitions from HubSpot and the table updates within a few seconds. A toast confirms when it finishes.

Step 6 — Build a Rev IQ model (if you don't have one yet)​

Rev IQ analytics require a Una model wired up with specific dimensions: Scenario, Time, Account (with Volume + Days KPI members), and Stage. The fastest way to get one is the wizard.

If your tenant has no Rev IQ model yet, on the integration page you'll see a Create Rev IQ Model button (under the no-model-configured callout). Click it.

The wizard asks you, for each dimension:

  • Create new — Una creates the dimension fresh with the canonical Rev IQ shape (default members, KPI tags, etc.).
  • Use existing — pick an existing dimension from your tenant's metadata.

For most customers, Create new for everything is correct. Click Create model and load data. Una builds the dimensions, processes metadata, creates the model, and auto-refreshes pipelines so you land on the Pipelines tab with a ready-to-map dropdown.

tip

The wizard creates one Rev IQ model per tenant. If you re-run it after a model exists, the button is hidden — you'll edit the existing model via Model Definitions instead.

Step 7 — Deploy and load data​

On the Deploy Model tab, pick the model you want this integration to feed (typically the one the wizard just created), confirm the dim mappings look right, and click Deploy. Una:

  1. Generates the fact and dimension tables for the model in your tenant database (if not already generated).
  2. Pulls the configured HubSpot data into staging tables.
  3. Promotes the staged data into the model's fact tables, joined to the right Account / Stage / Time dim members per your pipeline mappings.

When deploy finishes, the data is queryable via Una's matrices, dashboards, and report books.

Day-two operations​

  • Adding fields — Data tab → Add field → Save → Deploy (so the new column makes it into the fact tables).
  • Adding pipeline stages in HubSpot — Pipelines tab → Refresh Pipelines → map the new stages → Save.
  • Renaming fields — Data tab → edit the Field Name → Save → Deploy. Note: this is a schema change; older data under the old column name doesn't automatically migrate.
  • Disconnecting — On the General tab, the Update Credentials button is the closest thing to a force-disconnect. To revoke from HubSpot's side: HubSpot → Settings → Integrations → Connected Apps → Una → Disconnect.

Reconnecting after disconnect​

If your token is revoked (you uninstalled Una from HubSpot, the refresh token rotated and Una hasn't been used in a while, etc.), the General tab flips back to Inactive. Click Connect with HubSpot again — same flow as Step 2 — and you're back to Active.

Privacy and data sharing​

Una receives exactly the data the scopes in your consent grant — deal data, contact data, company data, owner info, currency settings. Una does not receive:

  • Marketing email content
  • Workflow definitions
  • File attachments
  • HubSpot account billing info

Within Una, data is stored per-tenant in your dedicated tenant database. Other tenants can't see your data.

Troubleshooting​

"Couldn't complete the connection: scopes are missing" or "scope mismatch"​

HubSpot's consent step rejected because Una's install URL doesn't line up with what your account can grant. Common causes:

  • Your HubSpot account lacks Multi-Currency (a paid Sales/Service Hub feature), but Una requests the settings.currencies.read scope. Either upgrade your HubSpot plan, or contact your Una implementation partner — there may be a way to make this scope optional for your account.
  • You selected the wrong HubSpot account. Log out of HubSpot first, then click Connect with HubSpot again to force the account chooser.

Una redirected you to a server URL that your browser can't resolve. This is a configuration issue on Una's side — contact your Una implementation team and reference the URL shown in your browser's address bar.

The connection still completed if you saw a success message in the popup. Close it manually and check your portal tab — if the General tab shows Active, you're connected.

Integration goes Inactive a few hours after connecting​

The token expired and the auto-refresh failed. Click Connect with HubSpot again to do a fresh round-trip. If that also fails, contact support.

Deploy succeeds but data is missing for some HubSpot stages​

Those stages weren't mapped on the Pipelines tab — the Model column shows "- Not set -". Set the Model dropdown for each missing stage, save, and re-deploy.

Account chooser not shown when reconnecting​

HubSpot remembers the most-recent account in your browser session. Log out of HubSpot first (or use HubSpot's own account switcher) to force the picker.

For deeper configuration patterns and implementation guidance — multi-pipeline setups, custom field naming, segment dimensions, stage-mapping playbook — see the Implementation Partner Guide (CX docs).