> ## 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 data source in Adriel.

## Introduction

HubSpot is an inbound marketing, sales, and customer-service platform organized around a central CRM. Contacts, companies, deals, tickets, marketing emails, and engagement records all live within a single portal, where lifecycle stages and properties describe how each record progresses.

The connector exposes CRM and marketing data — contacts, companies, deals, emails, marketing emails, and marketing-email statistics — for use in dashboards and widgets. For contacts, companies, and deals, only the properties selected during data source creation are available; for emails and marketing emails, all standard properties are exposed. Typical use cases include funnel reporting from lead to customer, marketing-email performance tracking, and cross-channel attribution between paid campaigns and CRM outcomes.

As a CRM connector, contact, deal, and pipeline breakdowns are standardized so widgets can aggregate alongside ad-platform sources without additional configuration.

Deal pipeline analytics — deal amount, MRR, and TCV broken down by pipeline stage — are served by a separate connector; see the [HubSpot Deals data reference](/data-sources/g-n/hubspot-deals/data-reference).

To connect this data source, see [How to connect HubSpot to Adriel](/data-sources/g-n/hubspot/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers object catalogs — pipelines, deal stages, lifecycle stages, owners, lists, and marketing-email metadata. It refreshes **once daily in UTC**. Newly created HubSpot objects and renamed pipeline stages become available on the next architecture refresh.

### Reports data

Reports include CRM and marketing records — contacts, companies, deals, emails, marketing emails, and marketing-email statistics.

**Not real-time.** HubSpot is a batch-synced connector. Records sync from the HubSpot API into a per-asset PostgreSQL cache table once daily at **04:00 UTC**, and all queries are served from that cache — there are no live API reads at query time.

**Refresh window.** Created and updated records are picked up on the next sync, so new contacts, deal-stage changes, and marketing-email events typically appear in dashboards within 24 hours of activity in HubSpot. Marketing-email statistics are fetched from two days before the last sync through yesterday; the initial sync backfills the last **90 days**.

## Architecture levels

Account / portal → Object type (Contact, Company, Deal, Ticket, Email, Marketing Email) → Record

* **Account / portal** — a single HubSpot portal (Hub ID) authorized through OAuth.
* **Object type** — Contact, Company, Deal, Ticket, Email, or Marketing Email.
* **Record** — an individual contact, company, deal, ticket, or email send, addressable by its HubSpot ID.

## 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 `sent` is the literal HubSpot field or cache column name. *Italic text* describes how a value is produced when it doesn't map cleanly to a single field.
</Note>

<Note>
  **Selected-properties model.** For contacts, companies, and deals, only the properties chosen during data source creation are exposed as metrics and breakdowns. Emails and marketing emails expose all standard properties. Beyond the fields below, the metrics available depend on that selection.
</Note>

### Contacts & audience

| Metric                     | Description                              | Data type | API Key                             |
| -------------------------- | ---------------------------------------- | --------- | ----------------------------------- |
| New contacts               | Contacts created in the selected period. | Number    | *Count of contacts by created date* |
| Total contacts             | Cumulative contacts in the portal.       | Number    | *Cumulative contact count*          |
| Contact created date       | Timestamp a contact was created.         | Date      | `createdate`                        |
| Contact last modified date | Timestamp a contact was last updated.    | Date      | `lastmodifieddate`                  |

### Companies

| Metric                     | Description                               | Data type | API Key                              |
| -------------------------- | ----------------------------------------- | --------- | ------------------------------------ |
| New companies              | Companies created in the selected period. | Number    | *Count of companies by created date* |
| Company created date       | Timestamp a company was created.          | Date      | `createdate`                         |
| Company last modified date | Timestamp a company was last updated.     | Date      | `hs_lastmodifieddate`                |

### Revenue (deals)

Deal properties selected at data source creation are exposed as metrics. Deal amount, MRR, and TCV broken down by pipeline stage — along with forecasted value that multiplies deal amount by each stage's configured probability — are provided by the separate [HubSpot Deals data reference](/data-sources/g-n/hubspot-deals/data-reference).

| Metric                  | Description                             | Data type | API Key                                |
| ----------------------- | --------------------------------------- | --------- | -------------------------------------- |
| New deals               | Deals created in the selected period.   | Number    | *Count of deals by created date*       |
| Deal amount             | Sum of deal amounts in portal currency. | Currency  | *Sum of the deal amount property*      |
| Closed-won deals        | Deals reaching a closed-won stage.      | Number    | *Count of deals in a closed-won stage* |
| Closed-won amount       | Revenue from deals reaching closed-won. | Currency  | *Sum of amount for closed-won deals*   |
| Deal created date       | Timestamp a deal was created.           | Date      | `createdate`                           |
| Deal last modified date | Timestamp a deal was last updated.      | Date      | `hs_lastmodifieddate`                  |

### Email engagement

<Note>
  Marketing-email engagement counters come from marketing-email statistics — a fixed set of per-day, per-marketing-email counters. These are always available regardless of the selected-properties model.
</Note>

| Metric        | Description                              | Data type | API Key        |
| ------------- | ---------------------------------------- | --------- | -------------- |
| Sent          | Marketing emails sent.                   | Number    | `sent`         |
| Delivered     | Marketing emails delivered.              | Number    | `delivered`    |
| Opens         | Marketing email opens.                   | Number    | `open`         |
| Clicks        | Marketing email clicks.                  | Number    | `click`        |
| Replies       | Replies to the marketing email.          | Number    | `reply`        |
| Bounces       | Total bounces.                           | Number    | `bounce`       |
| Hard bounces  | Hard bounces.                            | Number    | `hardbounced`  |
| Soft bounces  | Soft bounces.                            | Number    | `softbounced`  |
| Unsubscribed  | Recipients who unsubscribed.             | Number    | `unsubscribed` |
| Spam reports  | Recipients who marked the email as spam. | Number    | `spamreport`   |
| Dropped       | Sends dropped before delivery.           | Number    | `dropped`      |
| Suppressed    | Sends suppressed by HubSpot.             | Number    | `suppressed`   |
| Selected      | Recipients selected for the send.        | Number    | `selected`     |
| Pending       | Sends still pending.                     | Number    | `pending`      |
| Contacts lost | Contacts lost from the send.             | Number    | `contactslost` |
| Not sent      | Recipients not sent to.                  | Number    | `notsent`      |

**By device.** Opens and clicks are also split by device.

| Metric            | Description                       | Data type | API Key          |
| ----------------- | --------------------------------- | --------- | ---------------- |
| Opens (computer)  | Opens on desktop.                 | Number    | `open_computer`  |
| Opens (mobile)    | Opens on mobile.                  | Number    | `open_mobile`    |
| Opens (unknown)   | Opens on an unidentified device.  | Number    | `open_unknown`   |
| Clicks (computer) | Clicks on desktop.                | Number    | `click_computer` |
| Clicks (mobile)   | Clicks on mobile.                 | Number    | `click_mobile`   |
| Clicks (unknown)  | Clicks on an unidentified device. | Number    | `click_unknown`  |

### Activities

| Metric            | Description                                                  | Data type | API Key                             |
| ----------------- | ------------------------------------------------------------ | --------- | ----------------------------------- |
| Engagement events | Calls, emails, meetings, notes, and tasks logged on records. | Number    | *Count of logged engagement events* |

## Breakdowns

<Note>
  Breakdowns for contacts, companies, and deals come from the properties selected at data source creation. The categories below list the breakdowns most commonly used; the connector excludes internal columns (record ID, raw data, and sync-timestamp columns) from the breakdown list.
</Note>

### CRM hierarchy

| Breakdown       | Description                                                                  | API Key           |
| --------------- | ---------------------------------------------------------------------------- | ----------------- |
| Portal          | HubSpot portal (Hub).                                                        | `hub_id`          |
| Object type     | Contact, Company, Deal, Ticket, or Email.                                    | `object_type`     |
| Pipeline        | Deal pipeline name.                                                          | `pipeline`        |
| Deal stage      | Stage within a pipeline.                                                     | `deal_stage`      |
| Lifecycle stage | Subscriber / Lead / MQL / SQL / Opportunity / Customer / Evangelist / Other. | `lifecycle_stage` |
| Owner           | Contact, company, or deal owner.                                             | `owner`           |

### Time

| Breakdown    | Description                    | API Key      |
| ------------ | ------------------------------ | ------------ |
| Date         | Daily reporting date.          | `date`       |
| Created date | Record creation date.          | `createdate` |
| Closed date  | Deal close date (won or lost). | `closed_at`  |

### Source attribution

| Breakdown                  | Description                                   | API Key                        |
| -------------------------- | --------------------------------------------- | ------------------------------ |
| Original source            | HubSpot first-touch source.                   | `original_source`              |
| Original source drill-down | Secondary source detail (campaign, referrer). | `original_source_drill_down_1` |
| Email campaign             | Marketing-email campaign name.                | `campaignName`                 |

### UTM attribution

<Note>
  UTM values are parsed by Adriel from each contact's first- and last-touch analytics URLs, not returned as native HubSpot properties.
</Note>

| Breakdown                                                   | Description                                     |
| ----------------------------------------------------------- | ----------------------------------------------- |
| First-touch UTM source / medium / campaign / term / content | Group by the parsed first-touch UTM parameters. |
| Last-touch UTM source / medium / campaign / term / content  | Group by the parsed last-touch UTM parameters.  |

## Limitations

* **Selected-properties model** — for contacts, companies, and deals, only the properties chosen at data source creation are available. Adding a newly created custom property to existing widgets requires editing the data source. Emails and marketing emails are not restricted; all standard properties are available.
* **Not real-time** — data reflects the last nightly sync (04:00 UTC); changes in HubSpot appear in dashboards within roughly 24 hours.
* **10,000-row query cap** — a query returning more than 10,000 rows is truncated and flagged with a `TOO_MUCH_DATA_REQUESTED_INCOMPLETE` warning; rows beyond 10,000 are not returned.
* **Lifecycle stage is current-state** — the lifecycle-stage breakdown reflects each contact's present stage. Stage-change history is not retained, so funnel widgets show contacts by their current stage rather than a time series of transitions.
* **Deleted records** — data for records deleted on the HubSpot side becomes unavailable after deletion.
* **Separate OAuth app from HubSpot Deals** — the HubSpot and HubSpot Deals connectors register as different OAuth applications with separate client credentials and require independent authorization flows, even when both point at the same portal.

## API references

* [HubSpot CRM API — contacts](https://developers.hubspot.com/docs/api/crm/contacts)
* [HubSpot CRM API — companies](https://developers.hubspot.com/docs/api/crm/companies)
* [HubSpot CRM API — deals](https://developers.hubspot.com/docs/api/crm/deals)
* [HubSpot Marketing Email API](https://developers.hubspot.com/docs/api/marketing/marketing-emails)
* [HubSpot OAuth](https://developers.hubspot.com/docs/api/oauth-quickstart-guide)

## See also

* [How to connect HubSpot to Adriel](/data-sources/g-n/hubspot/how-to-connect) — paired how-to
* [HubSpot Deals data reference](/data-sources/g-n/hubspot-deals/data-reference) — for deal-pipeline analytics (amount, MRR, TCV by stage)
* [Salesforce Reporting data reference](/data-sources/o-z/salesforce-reporting/data-reference) — for CRM reporting from Salesforce