> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/crm/hubspot.md).

# HubSpot

Connect HubSpot deals, contacts, and companies to Google Sheets or BI tools via Coupler.io. Automate CRM exports without manual work.

HubSpot is a leading CRM platform that helps teams manage deals, contacts, companies, and the full customer lifecycle. With Coupler.io, you can export your HubSpot data to spreadsheets, BI tools, databases, or AI assistants — automatically and on a schedule.

## Why connect HubSpot to Coupler.io?

* **Build custom sales dashboards** using Deals, Contacts, and Companies data without manual exports
* **Combine multiple HubSpot entities** in one data flow using Join or Append transformations — for example, join Deals with Contacts to see which reps own which opportunities
* **Send CRM data to AI tools** like ChatGPT, Claude, or Gemini to generate summaries, forecasts, or pipeline analysis
* **Sync to any destination** — Google Sheets, Excel, BigQuery, Looker Studio, and more

## Prerequisites

* A HubSpot account (any plan)
* Access to the HubSpot portal you want to connect — you must be able to authorize the OAuth connection
* Coupler.io account (free plan works)

## Quick start

{% hint style="success" %}
Start with the **Deals** entity if you're building a sales pipeline report. It's the most commonly used entity and gives you the clearest picture of revenue performance.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Create a new data flow.** In Coupler.io, click **Add data flow** and search for HubSpot as your source.
{% endstep %}

{% step %}
**Authorize your HubSpot account.** Click **Sign in with HubSpot** and complete the OAuth flow. Select the HubSpot portal you want to connect, then grant the requested permissions.
{% endstep %}

{% step %}
**Choose an entity.** Select the data you want to pull — for example, Deals, Contacts, or Companies. You can add more sources to the same data flow later.
{% endstep %}

{% step %}
**Specify columns to export.** Limit exported data to [needed columns only](https://docs.coupler.io/sources/category/crm/hubspot/how-to-specify-hubspot-columns-to-export.md). It is optional step.
{% endstep %}

{% step %}
**Choose a destination.** Select where you want your data to land — Google Sheets, BigQuery, Looker Studio, Excel, or an AI destination like ChatGPT or Claude.
{% endstep %}

{% step %}
**Run your data flow.** Click **Run** to execute a manual run and confirm everything loads correctly.
{% endstep %}
{% endstepper %}

## Available entities

| Entity                     | Group           | Description                                              |
| -------------------------- | --------------- | -------------------------------------------------------- |
| Deals                      | Frequently used | Pipeline deals with stage, amount, close date, and owner |
| Contacts                   | Frequently used | People in your CRM with properties and lifecycle stage   |
| Companies                  | Frequently used | Company records with firmographic data                   |
| Communications             | Miscellaneous   | Communication records logged in HubSpot                  |
| Feedback submissions       | Miscellaneous   | NPS and survey responses                                 |
| Products                   | Miscellaneous   | Product catalog items                                    |
| Taxes                      | Miscellaneous   | Tax records                                              |
| Quotes                     | Miscellaneous   | Sales quotes sent to prospects                           |
| Line items                 | Miscellaneous   | Individual line items linked to deals or quotes          |
| Tickets                    | Miscellaneous   | Support tickets from the Service Hub                     |
| Goals                      | Miscellaneous   | Sales and activity goal tracking                         |
| Owners                     | Miscellaneous   | HubSpot users assigned as record owners                  |
| Calls                      | Miscellaneous   | Logged call records                                      |
| Emails                     | Miscellaneous   | One-to-one emails logged in CRM                          |
| Meetings                   | Miscellaneous   | Scheduled and completed meetings                         |
| Notes                      | Miscellaneous   | Notes attached to CRM records                            |
| Tasks                      | Miscellaneous   | To-do tasks assigned to reps                             |
| Leads                      | Miscellaneous   | Prospecting leads (Sales Hub)                            |
| Marketing emails           | Miscellaneous   | Marketing email campaign records                         |
| Workflows                  | Miscellaneous   | Automation workflow metadata                             |
| Broadcast messages         | Miscellaneous   | Social broadcast message records                         |
| Email statistics by period | Reports         | Aggregated email performance metrics over time           |
| Performance report         | Reports         | Website and traffic performance analytics                |

## HubSpot data overview

HubSpot exposes a wide range of CRM, sales, marketing, and service data through Coupler.io. You can pull individual entity records, activity logs, and aggregated reports — all in one place.

## Entities and report types

| Entity                                | Type           | Key use case                                |
| ------------------------------------- | -------------- | ------------------------------------------- |
| Deals                                 | CRM records    | Pipeline tracking, revenue forecasting      |
| Contacts                              | CRM records    | Lead management, lifecycle analysis         |
| Companies                             | CRM records    | Account-based reporting                     |
| Tickets                               | CRM records    | Support volume and resolution tracking      |
| Calls, Emails, Meetings, Notes, Tasks | Activity logs  | Rep activity and engagement reporting       |
| Quotes, Line items, Products          | Sales objects  | Quote-to-close and product revenue analysis |
| Leads                                 | Sales Hub      | Prospecting pipeline                        |
| Owners                                | Reference data | User-to-record mapping                      |
| Marketing emails                      | Marketing      | Campaign performance                        |
| Email statistics by period            | Reports        | Aggregated email metrics over time          |
| Performance report                    | Reports        | Website traffic and UTM attribution         |
| Workflows                             | Automation     | Workflow audit and metadata                 |
| Feedback submissions                  | Service        | NPS and CSAT trends                         |

## Available fields by entity

#### Deals

| Field              | Description                              |
| ------------------ | ---------------------------------------- |
| Deal name          | The name of the deal                     |
| Pipeline           | The pipeline the deal belongs to         |
| Deal stage         | Current stage in the pipeline            |
| Amount             | Deal value                               |
| Close date         | Expected or actual close date            |
| Owner              | Assigned HubSpot user                    |
| Create date        | When the deal was created                |
| Last modified date | When the deal was last updated           |
| Deal type          | Type classification (e.g., New Business) |

#### Contacts

| Field                  | Description                       |
| ---------------------- | --------------------------------- |
| First name / Last name | Contact's name                    |
| Email                  | Primary email address             |
| Phone                  | Phone number                      |
| Lifecycle stage        | Lead, MQL, SQL, Customer, etc.    |
| Lead status            | Contact qualification status      |
| Owner                  | Assigned HubSpot user             |
| Create date            | When the contact was created      |
| Last modified date     | When the contact was last updated |
| Company                | Associated company name           |

#### Companies

| Field               | Description                 |
| ------------------- | --------------------------- |
| Company name        | Name of the company         |
| Domain              | Website domain              |
| Industry            | Industry classification     |
| Number of employees | Company size                |
| Annual revenue      | Reported revenue            |
| City / Country      | Location data               |
| Owner               | Assigned HubSpot user       |
| Create date         | When the record was created |

#### Email statistics by period

| Field        | Description                   |
| ------------ | ----------------------------- |
| Period       | Date or period bucket         |
| Sent         | Emails sent in the period     |
| Delivered    | Successfully delivered emails |
| Opens        | Total opens                   |
| Clicks       | Total link clicks             |
| Unsubscribes | Unsubscribe events            |
| Bounces      | Bounce events                 |

#### Performance report

| Field               | Description                                |
| ------------------- | ------------------------------------------ |
| Period              | Date or period bucket                      |
| Sessions            | Website sessions                           |
| Page views          | Total page views                           |
| Contacts (new)      | New contacts generated                     |
| Bounce rate         | Session bounce rate                        |
| Breakdown dimension | Source, UTM, page, form, geolocation, etc. |

## Common field combinations

* **Deals + Owners** — Join these two entities to map deal owner names and emails onto deal records for rep-level reporting
* **Deals + Contacts** — Join to see contact details alongside open opportunities
* **Contacts + Companies** — Join to build account-level contact lists
* **Calls + Deals** — Append activity data to deals to measure engagement by pipeline stage
* **Email statistics by period** — Use the Split data by period option to compare weekly or monthly email performance trends

## Use cases by role

{% tabs %}
{% tab title="Sales ops" %}

* Export Deals to Google Sheets or BigQuery to build pipeline dashboards outside HubSpot
* Join Deals with Owners to create per-rep performance reports with close rates and average deal size
* Use the Aggregate transformation on Deals to calculate total pipeline value by stage or territory
* Pull Goals alongside Deals to track quota attainment automatically
  {% endtab %}

{% tab title="Marketers" %}

* Use Email statistics by period to track open rates, clicks, and unsubscribes over time in Looker Studio
* Pull the Performance report with UTM breakdowns to attribute website traffic to campaigns
* Export Marketing emails metadata to audit campaign cadence and segmentation
* Send data to ChatGPT or Gemini to generate campaign performance summaries
  {% endtab %}

{% tab title="Customer success" %}

* Export Tickets to monitor support volume, resolution time, and ticket status trends
* Pull Feedback submissions to track NPS scores over time and identify at-risk accounts
* Join Contacts with Tickets to see which customers raise the most issues
* Use Meetings and Calls data to measure touchpoint frequency per account
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* HubSpot's API allows **up to 2 filters at a time**. If you use date filters, that counts as one or two of your available filters — plan your advanced filters accordingly.
* Field names in Coupler.io use **internal HubSpot API names**, which may differ from the labels shown in the HubSpot UI. For example, `firstname` instead of "First name".
* The **Owners** and **Workflows** entities do not support date filtering.
* Custom properties are supported — leave the custom fields input empty to import all custom fields, or list specific internal names to limit the pull.
* The **Performance report** supports breakdown dimensions including UTM parameters, sources, pages, forms, and geolocation.

## HubSpot common issues

### Connection issues

<details>

<summary>OAuth authorization fails or shows a blank screen</summary>

This usually happens when third-party cookies are blocked in your browser. Try connecting in a different browser or disable cookie-blocking extensions temporarily. Make sure you're logged into the correct HubSpot portal before starting the OAuth flow.

</details>

<details>

<summary>Connected to the wrong HubSpot portal</summary>

During the OAuth flow, HubSpot asks you to select a portal. If you have access to multiple portals, it's easy to pick the wrong one. Delete the credential in Coupler.io and reconnect, selecting the correct portal this time.

</details>

### Missing data

<details>

<summary>Some records are missing from the export</summary>

Check whether you have active date filters set. If your "Created after" or "Updated after" date is too recent, older records will be excluded. Also confirm that the HubSpot user who authorized the connection has access to those records — private records or team-restricted data won't appear if the authorizing user doesn't have permission.

</details>

<details>

<summary>Custom fields are not appearing in the output</summary>

If you specified custom field names manually, make sure you're using the **internal HubSpot API field name**, not the display label. For example, use `top_marketing_challenge` not "Top Marketing Challenge". Leave the custom fields input blank to import all custom fields and identify the correct internal names from the output.

</details>

<details>

<summary>Owners or Workflows data is empty</summary>

These entities don't support date filtering and the data is returned as-is from HubSpot. If the output is empty, confirm the authorizing user has Super Admin or the appropriate permissions to view users and workflows in that portal.

</details>

### Permission errors

<details>

<summary>"Insufficient permissions" error when running the data flow</summary>

The HubSpot user who authorized the OAuth connection needs access to the objects you're trying to export. For example, exporting Tickets requires Service Hub access, and exporting Marketing emails requires Marketing Hub access. Reconnect using an account with the appropriate permissions, or ask a Super Admin to authorize the connection.

</details>

### Data discrepancies

<details>

<summary>Numbers in Coupler.io don't match HubSpot reports</summary>

HubSpot's native reports often apply additional filters, time zones, or attribution logic that isn't reflected in raw API data. Coupler.io pulls unprocessed record data. Check whether the HubSpot report uses a specific pipeline filter, owner filter, or date range that you haven't replicated in your data flow settings.

</details>

<details>

<summary>Field values show IDs instead of readable labels</summary>

This is controlled by the **Return IDs for lookups instead of labels** option in your data flow settings. If this is enabled, lookup fields like deal stage or lifecycle stage will show internal IDs. Disable this option to get human-readable labels instead.

</details>

### Rate limits

<details>

<summary>Data flow fails with a rate limit error</summary>

HubSpot enforces API rate limits based on your plan. Free and Starter portals have lower limits. If you're pulling large entities like Contacts or Deals with many records, try narrowing the date range using the date filters to reduce the number of records per run. Avoid running multiple HubSpot data flows simultaneously.

</details>

{% hint style="warning" %}
HubSpot's API only supports **up to 2 active filters at a time**. Using both a date filter and an advanced filter counts as 2 filters — adding a third will cause an error.
{% endhint %}

## HubSpot FAQ

<details>

<summary>Which HubSpot plan do I need to use Coupler.io?</summary>

Coupler.io connects to HubSpot via OAuth and works with any HubSpot plan including Free. However, some entities require specific Hubs — for example, Tickets require Service Hub, Marketing emails require Marketing Hub, and Leads require Sales Hub. If an entity returns no data, check that your HubSpot plan includes access to that feature.

</details>

<details>

<summary>Can I pull data from multiple HubSpot portals into one destination?</summary>

Yes. Add each portal as a separate source in the same data flow by authorizing a different HubSpot credential for each. Then use the **Append** transformation to stack all records into a single dataset. This is useful for agencies or multi-brand organizations managing separate portals.

</details>

<details>

<summary>How do I find the internal field names for custom HubSpot properties?</summary>

Internal field names are different from the display labels in HubSpot. The easiest way to find them is to run a data flow with the columns input left blank - Coupler.io will import all columns (HubSpot and custom) and the headers in your destination will show the internal names. You can also look them up in HubSpot under Settings > Properties. Review [detailed guide](https://docs.coupler.io/sources/category/crm/hubspot/how-to-find-hubspot-columns-names.md) for more details.

</details>

<details>

<summary>Why are some deal stage or lifecycle stage fields showing as IDs instead of names?</summary>

This is controlled by the **Return IDs for lookups instead of labels** toggle in your data flow source settings. When enabled, lookup fields return raw IDs. Disable this option to get readable values like "Proposal Sent" or "Marketing Qualified Lead".

</details>

<details>

<summary>Can I filter Deals by pipeline or stage?</summary>

Yes, using the [**Advanced filters** section](https://docs.coupler.io/sources/category/crm/hubspot/how-to-use-hubspot-advanced-filters.md). Set the property to `pipeline` or `dealstage` and enter the corresponding value. Keep in mind that HubSpot allows a maximum of 2 filters at once — if you're already using a date filter, the advanced filter will be your second and final filter slot.

</details>

<details>

<summary>Can I export HubSpot data to an AI tool like ChatGPT or Claude?</summary>

Yes. Coupler.io supports AI destinations including ChatGPT, Claude, Gemini, Cursor, Perplexity, and OpenClaw. You can send your HubSpot CRM data directly to these tools for pipeline summaries, contact enrichment prompts, or automated reporting narratives.

</details>

<details>

<summary>How often can I schedule a HubSpot data flow to run?</summary>

Schedule frequency depends on your Coupler.io plan. Before scheduling, you must complete at least one successful manual run. Once confirmed, you can set the data flow to refresh automatically — hourly, daily, or at a custom interval based on your plan.

</details>

<details>

<summary>Why does my Contacts data flow take a long time to run?</summary>

Large contact databases with many custom properties can take time to process. Use the **Updated after date** filter to pull only recently modified contacts instead of the full database on every run. Also limit the columns to only the fields you need — pulling all properties on a large table significantly increases run time.

</details>

{% hint style="info" %}
For details on available fields and metrics for each entity, see the [Data Overview](#hubspot-data-overview) article. For connection problems or unexpected results, check [Common Issues](#hubspot-common-issues). For tips on structuring your data flow efficiently, see [Best Practices](https://docs.coupler.io/sources/category/crm/hubspot/best-practices.md).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/crm/hubspot.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
