> For the complete documentation index, see [llms.txt](https://docs.ovaledge.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ovaledge.com/release8.3/connectors/connector-repositories/application/hubspot.md).

# HubSpot

This article outlines the integration with the HubSpot connector, enabling metadata management through features such as crawling, sample profiling, data preview, and manual lineage. The connector crawls HubSpot CRM standard and custom objects, including schemas, tables, and columns, and maps the retrieved metadata to the corresponding OvalEdge assets.

This connector connects to HubSpot CRM using REST APIs over HTTPS through the HubSpot CRM API v3. It authenticates using a HubSpot Private App access token (Bearer token) with the required API scopes to access schemas, CRM objects, properties, and metadata required for crawling and data preview.

<img src="https://content.gitbook.com/content/8fgltewNgYZ8ucAp7Svt/blobs/CUTOIXgK1otpidaBOTMB/unknown.png" alt="" height="327" width="624">

## Overview

### Connector Details

<table data-header-hidden><thead><tr><th width="370.33331298828125"></th><th></th></tr></thead><tbody><tr><td>Connector Category</td><td>Application</td></tr><tr><td>OvalEdge Release Supported</td><td>Release6.3.4 and later</td></tr><tr><td><p>Connectivity</p><p>[How the connection is established with HubSpot]</p></td><td>REST APIs over HTTPS using HubSpot CRM API v3 with Bearer token authentication.</td></tr><tr><td>Verified HubSpot Versions</td><td>HubSpot CRM API v3</td></tr></tbody></table>

### Connector Features

<table data-search="false"><thead><tr><th>Feature</th><th align="center">Availability</th></tr></thead><tbody><tr><td>Crawling</td><td align="center">✅</td></tr><tr><td>Profiling</td><td align="center">❌</td></tr><tr><td>Sample Profiling</td><td align="center">✅</td></tr><tr><td>Query Sheet</td><td align="center">❌</td></tr><tr><td>Data Preview</td><td align="center">✅</td></tr><tr><td>Auto Lineage</td><td align="center">❌</td></tr><tr><td>Manual Lineage</td><td align="center">✅</td></tr><tr><td>Secure Authentication via Credential Manager</td><td align="center">✅</td></tr><tr><td>Data Quality</td><td align="center">❌</td></tr><tr><td>DAM (Data Access Management)</td><td align="center">❌</td></tr><tr><td>Bridge</td><td align="center">✅</td></tr></tbody></table>

### Metadata Mapping

The following objects are crawled from HubSpot and mapped to the corresponding UI assets.

<table data-search="false"><thead><tr><th>HubSpot Object</th><th>HubSpot Attribute</th><th>OvalEdge Attribute</th><th>OvalEdge Category</th><th>OvalEdge Type</th></tr></thead><tbody><tr><td>Schema</td><td>Schema name</td><td>Schema</td><td>Databases</td><td>Schema</td></tr><tr><td>Schema</td><td>Schema comment</td><td>Source Description</td><td>Databases</td><td>Schema</td></tr><tr><td>Table</td><td>CRM Object Name</td><td>Table</td><td>Tables</td><td>table</td></tr><tr><td>Table</td><td>objectTypeId</td><td>Table ID</td><td>Tables</td><td>table</td></tr><tr><td>Table</td><td>Table Comments</td><td>Source Description</td><td>Descriptions</td><td>Source Description</td></tr><tr><td>Columns</td><td>name</td><td>Column</td><td>Table Columns</td><td>-</td></tr><tr><td>Columns</td><td>label</td><td>Title</td><td>Table Columns</td><td>-</td></tr><tr><td>Columns</td><td>type</td><td>Column Type</td><td>Table Columns</td><td>-</td></tr><tr><td>Columns</td><td>description</td><td>Source Description</td><td>Table Columns</td><td>-</td></tr><tr><td>Columns</td><td>Column Position</td><td>Column Position</td><td>Table Columns</td><td>-</td></tr><tr><td>Columns</td><td>required</td><td>Nullable</td><td>Table Columns</td><td>-</td></tr><tr><td>Custom Objects</td><td>name</td><td>Table</td><td>Tables</td><td>table</td></tr><tr><td>Custom Objects</td><td>objectTypeId</td><td>Table ID</td><td>Tables</td><td>table</td></tr><tr><td>Custom Objects</td><td>properties</td><td>Columns</td><td>Table Columns</td><td>-</td></tr></tbody></table>

## Set up a Connection

### Prerequisites

The prerequisites to establish a connection:

#### **Service Account User Permissions**

{% hint style="warning" %}
It is recommended to use a dedicated service account to establish the connection to the data source, configured with the following minimum set of permissions.
{% endhint %}

{% hint style="info" %}
**👨‍💻 Who can provide these permissions?** The HubSpot administrator grants these permissions, since users may not have sufficient access to assign them.
{% endhint %}

| Operations | Objects       | Sys Tables                                | Access Permissions                                   |
| ---------- | ------------- | ----------------------------------------- | ---------------------------------------------------- |
| Crawling   | Schema        | GET /crm/v3/schemas                       | crm.schemas.custom.read                              |
| Crawling   | Schema        | GET /crm/v3/objects/{objectType}          | crm.schemas.custom.read                              |
| Crawling   | Table Columns | GET /crm/v3/properties/{objectType}       | crm.schemas.{objectType}.read                        |
| Crawling   | Table Columns | GET /crm/v3/schemas                       | crm.schemas.{objectType}.read                        |
| Profiling  | Data Preview  | GET /crm/v3/objects/{objectType}          | crm.objects.{objectType}.read                        |
| Profiling  | Data Preview  | GET /companies/v2/companies/{id}          | crm.objects.companies.read                           |
| Profiling  | Data Preview  | GET /contacts/v1/contact/vid/{id}/profile | crm.objects.contacts.read                            |
| Profiling  | Data Preview  | GET /deals/v1/deal/{id}                   | crm.objects.deals.read                               |
| Profiling  | Data Preview  | GET /crm-objects/v1/objects/{type}/{id}   | crm.objects.products.read / crm.objects.tickets.read |
| Profiling  | Data Preview  | GET /crm/v3/objects/{objectTypeId}        | crm.objects.custom.read                              |

### Connection Configuration Steps

{% hint style="warning" %}
Users must have the Connector Creator role to configure a new connection.
{% endhint %}

1. Log into **OvalEdge**, go to **Administration** > **Connectors**, click **+ (New Connector)**, search for **HubSpot**, and enter the required parameters.

{% hint style="info" %}
Fields marked with an asterisk (\*) are mandatory for establishing a connection.
{% endhint %}

<table data-search="false"><thead><tr><th width="219.66668701171875">Field Name</th><th>Description</th></tr></thead><tbody><tr><td>Connector Type</td><td>By default, "HubSpot" is displayed as the selected connector type.</td></tr><tr><td>Credential Manager*</td><td><p>Select the desired credentials manager from the drop-down list. Relevant parameters will be displayed based on the selection.</p><p>Supported Credential Managers:</p><ul><li>OE Credential Manager</li><li>AWS Secrets Manager</li><li>HashiCorp</li><li>Azure Key Vault</li></ul><p>For more details, click <a href="https://docs.ovaledge.com/connectors/additional-requirements/credential-manager-configuration">here</a>.</p></td></tr><tr><td>Connector Name*</td><td><p>Enter a unique name for the HubSpot connection              </p><p>(Example: "HubSpot_Prod").</p></td></tr><tr><td>Connector Environment</td><td><p>Select the environment (Example: PROD, STG) configured for the connector.</p><p>For more details, click <a href="https://docs.ovaledge.com/connectors/introduction-to-connectors/setup-and-connectivity/prerequisites#connector-environment">here</a>.</p></td></tr><tr><td>Connector Description</td><td>Enter the description related to the connector.</td></tr><tr><td>HubSpot API Key*</td><td>Enter the <strong>HubSpot Private App Access Token</strong> used to authenticate with the HubSpot CRM API.</td></tr><tr><td>Proxy Enabled*</td><td>Select <strong>Yes</strong> to route API calls through a proxy server. Select <strong>No</strong> to bypass the proxy and connect directly.</td></tr><tr><td>Plugin Server</td><td>Enter the server’s name when running as a plugin server.</td></tr><tr><td>Plugin Port</td><td>Enter the port number on which the plugin is running.</td></tr></tbody></table>

<table data-header-hidden data-search="false"><thead><tr><th width="220.3333740234375"></th><th></th></tr></thead><tbody><tr><td><strong>Default Governance Roles</strong></td><td></td></tr><tr><td>Default Governance Roles*</td><td>Select the appropriate users or teams for each governance role from the drop-down list. All users and teams configured in OvalEdge Security are displayed for selection.</td></tr><tr><td><strong>Admin Roles</strong></td><td></td></tr><tr><td>Admin Roles*</td><td>Select one or more users from the drop-down list for Integration Admin and Security &#x26; Governance Admin. All users configured in OvalEdge Security are available for selection.</td></tr><tr><td><strong>No of Archive Objects</strong></td><td></td></tr><tr><td>No Of Archive Objects*</td><td><p>This shows the number of recent metadata changes to a dataset at the source. By default, it is off. To enable it, toggle the Archive button and specify the number of objects to archive.</p><p>Example: Setting it to 4 retrieves the last four changes, displayed in the 'Version' column of the 'Metadata Changes' module.</p></td></tr><tr><td><strong>Bridge</strong></td><td></td></tr><tr><td>Select Bridge*</td><td><p>If applicable, select the bridge from the drop-down list.</p><p>The drop-down list displays all active bridges configured in OvalEdge. These bridges enable communication between data sources and OvalEdge without altering firewall rules.</p></td></tr></tbody></table>

2. After entering all connection details, the following actions can be performed:
   1. Click **Validate** to verify the connection.
   2. Click **Save** to store the connection for future use.
   3. Click **Save & Configure** to apply additional settings before saving.
3. The saved connection will appear on the Connectors home page.

## Manage Connector Operations

### Crawl/Profile

{% hint style="info" %}
To perform crawl and profile operations, users must be assigned the Integration Admin role.
{% endhint %}

The **Crawl/Profile** button allows users to select one or more schemas for crawling and profiling.

1. Navigate to the Connectors page and click **Crawl/Profile.**
2. Select the schemas to crawl.
3. The **Crawl** option is selected by default. To perform both operations, select the **Crawl & Profile** radio button.&#x20;
4. Click **Run** to collect metadata from the connected source and load it into the Data Catalog.
5. After a successful crawl, the information appears in the **Data Catalog** > **Databases** tab.

The Schedule checkbox allows automated crawling for a selected timeframe, from a minute to a year.

1. Click the **Schedule** checkbox to enable the Select Period drop-down.
2. Select a time period for the operation from the drop-down menu.
3. Click **Schedule** to initiate metadata collection from the connected source.
4. The system will automatically execute the selected operation (**Crawl** or **Crawl & Profile**) at the scheduled time.

#### Other Operations

The Connectors page provides a centralized view of all configured connectors and their health status.

**Managing connectors includes:**

* **Connector Health:** Displays the current status of each connector, with a green icon for active connections and a red icon for inactive connections, helping monitor connectivity to data sources.
* **Viewing**: Click the **Eye** icon next to the connector name to view connector details.

**Nine Dots Menu Options:**

To view, edit, validate, configure, or delete connectors, click on the Nine Dots menu.

* **Edit Connector**: Update and revalidate the data source.
* **Validate Connector**: Check the integrity of the connection.
* **Settings**: Modify connector settings.
  * **Crawler**: Configure data extraction.
  * **Profiler**: Customize data profiling rules and methods.&#x20;
  * **Access Instructions:** Add notes on how data can be accessed.
  * **Business Glossary Settings**: Manage term associations at the connector level.
  * **Lineage**: Select the parsing method (Regular or AI-Augmented) for generating lineage, and set a confidence threshold to control when AI-generated lineage is accepted or held for review. For more details, click [here](https://docs.ovaledge.com/release8.2/connectors/introduction-to-connectors/setup-and-connectivity/connector-settings#lineage-applicable-for-supported-connectors).
  * **Others**: Configure notification recipients for metadata changes.
* **Delete Connector:** Remove a connector with confirmation.

For more details on connector settings, click [here](https://docs.ovaledge.com/connectors/introduction-to-connectors/setup-and-connectivity/connector-settings).

## Limitations

The following limitations apply to HubSpot data types and profiling capabilities:

<table data-search="false"><thead><tr><th width="144.046875">Data Type</th><th width="621.9296875">Limitation</th></tr></thead><tbody><tr><td><strong>Enumeration</strong></td><td>Profiling is not supported. Enumeration properties are excluded from sample profiling.</td></tr><tr><td><strong>Phone Number</strong></td><td>Profiling is partially supported. Minimum and maximum value profiling is not supported.</td></tr><tr><td><strong>Boolean</strong></td><td>Minimum and maximum value profiling is not supported.</td></tr></tbody></table>

## Troubleshooting

If incorrect parameters are entered, error messages may appear. Ensure all inputs are accurate to resolve these issues. If issues persist, contact the assigned support team.

{% tabs %}
{% tab title="First Tab" %}

<table data-search="true"><thead><tr><th width="58.6328125">S. No</th><th width="191.3984375">Error Message</th><th>Error Description &#x26; Resolution</th></tr></thead><tbody><tr><td>1</td><td>Error while validating connection: authentication failure</td><td><p>The access token used for the connection does not carry the scope needed for the basic validation call, which checks access to the contacts API.<br><strong>Resolution:</strong></p><ul><li>Confirm the access token has the scope for the contacts API, since this is the primary permission checked during validation.</li><li>Verify the token scopes using Postman or a curl command against the HubSpot API.</li><li>Review the JSON response returned by the HubSpot API, since it states the exact scope that is missing.</li></ul></td></tr><tr><td>2</td><td>Error while validating connection: token expired</td><td><p>The HubSpot access token has a set validity period and stops working once that period ends. Token rotation and expiry are manual, so a new token does not get generated automatically.<br><strong>Resolution:</strong></p><ul><li>Confirm whether the token has expired by checking its status in the HubSpot account.</li><li>Create a new access token in HubSpot when the previous one has expired or was rotated.</li><li>Update the connector with the new token and revalidate the connection.</li></ul></td></tr><tr><td>3</td><td>Connection timeout or proxy error</td><td><p>The environment routes outbound traffic through a proxy server, but the proxy option in the connector settings is not enabled or configured, so the request does not reach the HubSpot server.<br><strong>Resolution:</strong></p><ul><li>Confirm whether a proxy server is used in the environment.</li><li>Enable the proxy option in the connector settings and provide the proxy details when one is used.</li><li>Validate the connection again once the proxy option is enabled.</li></ul></td></tr><tr><td>4</td><td>JSON response contains error from HubSpot API</td><td><p>The HubSpot API returned an error in the JSON response. This may occur due to insufficient permissions, API rate limits, or an invalid object request.<br><strong>Resolution:</strong></p><ul><li>Review the JSON response to identify the exact cause.</li><li>Verify that the access token includes the required scopes and that the requested object type is valid.</li><li>If a 429 (Rate Limit Exceeded) error occurs, wait before retrying the request or reduce the request frequency.</li></ul></td></tr></tbody></table>
{% endtab %}

{% tab title="Crawling and Profiling" %}

<table data-search="true"><thead><tr><th width="66.6328125">S. No</th><th width="190.03125">Error Message</th><th>Error Description &#x26; Resolution</th></tr></thead><tbody><tr><td>1</td><td>Failed to get remote tables or columns</td><td>The connector could not retrieve metadata because the access token does not have sufficient access to the required objects or the requested objects are unavailable.<br><br><strong>Resolution:</strong><br>• Verify that the access token has read access to the required HubSpot CRM objects.<br>• For custom objects, ensure the required custom schema scope is enabled.<br>• Confirm that the required objects exist in the connected HubSpot account.</td></tr><tr><td>2</td><td>Preview error while viewing object data</td><td>The access token does not have read permission for the specific object being previewed.<br><br><strong>Resolution:</strong><br>• Confirm the access token includes read permission for the object being previewed.<br>• Add the missing scope to the token in HubSpot if it is not present.<br>• Retry the preview after updating the token.</td></tr><tr><td>3</td><td>Unsupported data type warning appears in the crawl log</td><td>Certain HubSpot data types have limited support for specific connector operations. The connector records a warning instead of stopping the crawl.<br><br><strong>Resolution:</strong><br>• Review the crawl log for the warning message and identify the property and data type involved.<br>• Refer to the <strong>FAQs</strong> section for the supported data types and their profiling limitations.<br>• Continue the crawl, since the warning does not stop cataloguing of the remaining supported properties.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## FAQs

{% tabs %}
{% tab title="Connectivity" %}

<table data-search="true"><thead><tr><th width="58.5625">S. No</th><th width="199.9140625">Question</th><th>Answer</th></tr></thead><tbody><tr><td>1</td><td>What is the HubSpot connector used for?</td><td><p>HubSpot is a platform that combines marketing, sales, customer service, and content management. The connector brings its CRM data into the application.</p><ul><li>Only the CRM module is supported at present.</li><li>Contacts, companies, deals, tickets, products, projects, and line items are catalogued.</li><li>Other HubSpot modules, such as marketing and content, are planned for later releases.</li></ul></td></tr><tr><td>2</td><td>How is HubSpot represented in the application?</td><td><p>HubSpot is treated as a relational database-style connector.</p><ul><li>There is no schema or table concept in HubSpot itself, only objects and properties.</li><li>Each object, such as contacts or deals, is treated as a table.</li><li>Each property of an object is treated as a column.</li></ul></td></tr><tr><td>3</td><td>What is needed to set up the connector?</td><td>A HubSpot API key, provided as an access token, is the only credential required. This single token is used to validate the connection, crawl objects, and profile data.</td></tr><tr><td>4</td><td>Why is a client secret not used?</td><td>A client secret does not enable the API calls required by this connector. The connector uses the access token mechanism for authentication.</td></tr><tr><td>5</td><td>What permission does the access token need at minimum?</td><td>The token must include access to the contacts API. This is checked first and is treated as the basic permission required for connection validation. Additional scopes are required for other objects such as companies, deals, tickets, products, projects, and line items.</td></tr><tr><td>6</td><td>Does the access token expire?</td><td>Yes. The token can expire or be rotated. There is no automatic renewal, so a new token must be created manually in HubSpot and updated in the connector when required.</td></tr><tr><td>7</td><td>How are default objects different from custom objects?</td><td><p>HubSpot supports both default and user-created objects.</p><ul><li>Default objects, such as contacts, companies, deals, and products, are catalogued under the default HubSpot schema.</li><li>Objects created by users are catalogued under a separate custom schema.</li></ul></td></tr><tr><td>8</td><td>Which objects were recently added to the connector?</td><td>Support for projects and line items was added in addition to the original default objects.</td></tr><tr><td>9</td><td>Can data be stored in a credential manager?</td><td>Yes. Credential manager support is available for this connector.</td></tr><tr><td>10</td><td>Is proxy access supported?</td><td>Yes. When an environment routes traffic through a proxy server, the proxy option can be enabled in the connector settings with the required details. Requests are then routed through the proxy server before reaching HubSpot.</td></tr></tbody></table>
{% endtab %}

{% tab title="Crawling and Profiling" %}

<table data-search="true"><thead><tr><th width="59.27734375">S. No</th><th width="199.60546875">Question</th><th>Answer</th></tr></thead><tbody><tr><td>1</td><td>What connectivity method does the connector use?</td><td>The connector uses REST APIs to access HubSpot for crawling, sample profiling, and data preview operations.</td></tr><tr><td>2</td><td>Which features are supported by this connector?</td><td><p>The following features are supported:</p><ul><li>Crawling</li><li>Sample profiling</li><li>Data preview</li><li>Manual lineage</li></ul><p>Full profiling, Query Sheet, Auto Lineage, and Data Quality are not supported.</p></td></tr><tr><td>3</td><td>Why is only sample profiling supported instead of full profiling?</td><td>HubSpot objects can contain large volumes of data. Sample profiling limits the amount of data processed at a time. The sample size can be configured at the connector level.</td></tr><tr><td>4</td><td>How does profiling work for this connector?</td><td><p>Profiling is performed in memory rather than through aggregate functions.</p><ul><li>Data available for an object is retrieved.</li><li>Supported profiling metrics are calculated from the retrieved data.</li><li>Aggregate functions are not used because the connector supports sample profiling.</li></ul></td></tr><tr><td>5</td><td>Are there any data type profiling limitations?</td><td><p>Yes. The following data types have profiling limitations:</p><ul><li><strong>Enumeration:</strong> Profiling is not supported. Enumeration properties are excluded from sample profiling.</li><li><strong>Phone Number:</strong> Profiling is partially supported. Minimum and maximum value profiling are not supported.</li><li><strong>Boolean:</strong> Minimum and maximum value profiling are not supported.</li></ul></td></tr><tr><td>6</td><td>Are unsupported data types reported during crawling?</td><td>Yes. Unsupported data types or operations are reported as warnings in the crawl log rather than stopping the crawl. The remaining supported properties continue to be catalogued.</td></tr><tr><td>7</td><td>Why is Auto Lineage not supported?</td><td>HubSpot does not provide views or source code that can be parsed to determine data relationships. Therefore, automatic lineage cannot be generated. Manual lineage remains available.</td></tr><tr><td>8</td><td>Why is Data Quality not supported?</td><td>Data Quality rules are not available for this connector at present. This applies to the connector as a whole and not to specific objects.</td></tr><tr><td>9</td><td>What does the Query Sheet limitation mean?</td><td>Query Sheet is not available for this connector because the connector relies on REST API calls rather than a queryable data source.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

***

&#x20;Copyright © 2026, OvalEdge LLC, Peachtree Corners GA USA


---

# 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.ovaledge.com/release8.3/connectors/connector-repositories/application/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.