Skip to main content

​
Introduction

HubSpot Deals is a CRM-attribution variant of the HubSpot integration, focused on deal and pipeline reporting. Rather than exposing raw CRM objects, it links deals back to the contacts that originated them and uses UTM parameters captured on each contact’s first or last tracked URL to attribute pipeline value to marketing campaigns. The primary use case is measuring which campaigns drove signed deals — it complements, rather than duplicates, the standard HubSpot connector. For each deal pipeline stage selected when the data source is created, four metrics become available: deal amount, deal monthly recurring revenue, deal total contract value, and deal count. Breakdowns cover pipeline, currency, and first-touch and last-touch UTM parameters. To report on raw contacts, companies, deals, and marketing emails, use the standard HubSpot connector. As a CRM connector, deal and pipeline values are standardized and converted to the workspace currency so widgets can aggregate alongside ad-platform sources without additional configuration. To connect this data source, see How to connect HubSpot Deals to Adriel.

​
Data refresh strategy

​
Architecture data

Pipelines, deal stages, and currency metadata refresh once daily in UTC. The set of stage labels selected when the data source is created determines which per-stage metrics are exposed; adding a new stage to a pipeline requires editing the data source so the new label is registered.

​
Reports data

Deals and contacts sync from the HubSpot API into per-asset PostgreSQL cache tables on a daily UTC cadence. This connector is not real-time: all queries — including UTM attribution joins — are served from the cache, and the HubSpot API is not called at query time. New deals and contact UTM updates typically appear in dashboards within 24 hours of the activity in HubSpot. Incremental syncs fetch only records modified since the previous day; the first sync after connection performs a full load of all deals and contacts.
The date field chosen when the data source is created — deal creation, deal modification, contact creation, or contact modification — determines which timestamp anchors the dashboard date range.

​
Architecture levels

  • Portal — a single HubSpot portal (Hub ID), authorized through OAuth.
  • Pipeline — a named sequence of deal stages inside the portal.
  • Stage — a step within a pipeline (for example, Appointment scheduled or Closed won).
  • Deal — a HubSpot deal record, associated with one or more contacts.
  • Contact — a CRM contact whose first and last tracked URLs supply the UTM values used for attribution.

​
Metrics

How to read the columns Data type uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean. API Key in code style like deal_amount is the connector’s field name. Italic text describes how a value is produced when it doesn’t map cleanly to a single field.The four deal metrics below are exposed per pipeline stage and are addressed as <metric> / <stage label> (for example, deal_amount / Closed Won). Only the stage labels selected at data source creation are available. contact_count is always available and is not stage-scoped.

​
Deals & value

Deal amounts, MRR, and TCV are converted from each deal’s original currency to the workspace currency at sync time. The original currency is preserved and available as the Currency breakdown. Missing amounts default to zero.

​
Contacts

​
Breakdowns

​
Pipeline & currency

​
Source attribution — first touch

UTM values are parsed by Adriel from the contact’s first tracked URL and joined to the associated deals for attribution.

​
Source attribution — last touch

UTM values are parsed by Adriel from the most recent contact URL whose query string contained UTM parameters, then joined to the associated deals.
Deal and UTM breakdowns cannot be combined Pipeline and currency are deal-side breakdowns; UTM breakdowns are contact-side and resolved through a contact-to-deal join. A query that includes both a deal breakdown and a UTM breakdown is rejected with INVALID_DIMENSIONS_METRICS_COMBINATION.

​
Limitations

  • Separate OAuth application from the standard HubSpot connector — HubSpot Deals authorizes as a distinct OAuth application. Connecting the same portal to both connectors requires two separate authorization steps.
  • Pipeline stages fixed at data source creation — metrics are surfaced per stage label, not per pipeline as a whole. Stages not selected during creation do not appear as metric suffixes; adding a new stage requires editing the data source.
  • Deal and UTM breakdowns are mutually exclusive in a single query (see the note above).
  • UTM breakdowns can inflate deal totals — because one deal can be associated with several contacts, UTM-broken-down queries may double-count and surface a duplicated-data warning. When multiple contacts match a deal, the contact with the earliest (smallest numeric) ID is used to assign the deal to a UTM group.
  • Partial and missing UTMs — when some UTM parameters are present but others are null, the null values are normalized to the string not set. Contacts with no UTM values at all are excluded from UTM-broken-down widgets.
  • 30-day modification window on incremental sync — HubSpot’s recently-modified endpoints return only records modified in the last 30 days, so incremental syncs capture only the last 30 days of changes (the initial full sync is unaffected) (HubSpot legacy CRM API — recently modified deals).
  • 100,000-row response limit — very large result sets are capped at 100,000 rows and return partial results with a warning.

​
API references

​
See also