> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data reference

> Metrics, breakdowns, refresh cadence, and limits for the HubSpot Deals data source in Adriel.

## 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-sources/g-n/hubspot-deals/how-to-connect).

## 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.

<Note>
  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.
</Note>

## 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

<Note>
  **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.
</Note>

### Deals & value

| Metric      | Description                                                                             | Data type | API Key       |
| ----------- | --------------------------------------------------------------------------------------- | --------- | ------------- |
| Deal count  | Number of deals in the stage during the selected period.                                | Number    | `deal_count`  |
| Deal amount | Sum of deal amounts in the stage, converted to the workspace currency.                  | Currency  | `deal_amount` |
| Deal MRR    | Monthly recurring revenue from deals in the stage, converted to the workspace currency. | Currency  | `deal_mrr`    |
| Deal TCV    | Total contract value of deals in the stage, converted to the workspace currency.        | Currency  | `deal_tcv`    |

<Note>
  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.
</Note>

### Contacts

| Metric        | Description                                                             | Data type | API Key         |
| ------------- | ----------------------------------------------------------------------- | --------- | --------------- |
| Contact count | Number of contacts associated with the matched deals. Not stage-scoped. | Number    | `contact_count` |

## Breakdowns

### Pipeline & currency

| Breakdown | Description                             | API Key         |
| --------- | --------------------------------------- | --------------- |
| Pipeline  | Group by deal pipeline.                 | `deal_pipeline` |
| Currency  | Group by each deal's original currency. | `deal_currency` |

### Source attribution — first touch

<Note>
  UTM values are parsed by Adriel from the contact's first tracked URL and joined to the associated deals for attribution.
</Note>

| Breakdown                  | Description                                                   |
| -------------------------- | ------------------------------------------------------------- |
| UTM source (first touch)   | Group by `utm_source` from the contact's first tracked URL.   |
| UTM medium (first touch)   | Group by `utm_medium` from the contact's first tracked URL.   |
| UTM campaign (first touch) | Group by `utm_campaign` from the contact's first tracked URL. |
| UTM content (first touch)  | Group by `utm_content` from the contact's first tracked URL.  |
| UTM term (first touch)     | Group by `utm_term` from the contact's first tracked URL.     |

### Source attribution — last touch

<Note>
  UTM values are parsed by Adriel from the most recent contact URL whose query string contained UTM parameters, then joined to the associated deals.
</Note>

| Breakdown                 | Description                                                      |
| ------------------------- | ---------------------------------------------------------------- |
| UTM source (last touch)   | Group by `utm_source` from the contact's last UTM-bearing URL.   |
| UTM medium (last touch)   | Group by `utm_medium` from the contact's last UTM-bearing URL.   |
| UTM campaign (last touch) | Group by `utm_campaign` from the contact's last UTM-bearing URL. |
| UTM content (last touch)  | Group by `utm_content` from the contact's last UTM-bearing URL.  |
| UTM term (last touch)     | Group by `utm_term` from the contact's last UTM-bearing URL.     |

<Note>
  **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`.
</Note>

## 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](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/deals/v1/get-deals-v1-deal-recent-modified)).
* **100,000-row response limit** — very large result sets are capped at 100,000 rows and return partial results with a warning.

## API references

* [HubSpot CRM Deals API](https://developers.hubspot.com/docs/api/crm/deals)
* [HubSpot CRM Contacts API](https://developers.hubspot.com/docs/api/crm/contacts)
* [HubSpot CRM Pipelines API](https://developers.hubspot.com/docs/api/crm/pipelines)
* [HubSpot OAuth 2.0](https://developers.hubspot.com/docs/api/oauth-quickstart-guide)

## See also

* [How to connect HubSpot Deals to Adriel](/data-sources/g-n/hubspot-deals/how-to-connect) (paired how-to)
* [HubSpot data reference](/data-sources/g-n/hubspot/data-reference) — for raw contacts, companies, deals, and marketing emails