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.
Overview
Connector Details
Connector Category
Application
OvalEdge Release Supported
Release6.3.4 and later
Connectivity
[How the connection is established with HubSpot]
REST APIs over HTTPS using HubSpot CRM API v3 with Bearer token authentication.
Verified HubSpot Versions
HubSpot CRM API v3
Connector Features
Crawling
✅
Profiling
❌
Sample Profiling
✅
Query Sheet
❌
Data Preview
✅
Auto Lineage
❌
Manual Lineage
✅
Secure Authentication via Credential Manager
✅
Data Quality
❌
DAM (Data Access Management)
❌
Bridge
✅
Metadata Mapping
The following objects are crawled from HubSpot and mapped to the corresponding UI assets.
Schema
Schema name
Schema
Databases
Schema
Schema
Schema comment
Source Description
Databases
Schema
Table
CRM Object Name
Table
Tables
table
Table
objectTypeId
Table ID
Tables
table
Table
Table Comments
Source Description
Descriptions
Source Description
Columns
name
Column
Table Columns
-
Columns
label
Title
Table Columns
-
Columns
type
Column Type
Table Columns
-
Columns
description
Source Description
Table Columns
-
Columns
Column Position
Column Position
Table Columns
-
Columns
required
Nullable
Table Columns
-
Custom Objects
name
Table
Tables
table
Custom Objects
objectTypeId
Table ID
Tables
table
Custom Objects
properties
Columns
Table Columns
-
Set up a Connection
Prerequisites
The prerequisites to establish a connection:
Service Account User 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
Log in tointo OvalEdge, go to Administration > Connectors, click + (New Connector), search for HubSpot, and enter the required parameters.
Connector Type
By default, "HubSpot" is displayed as the selected connector type.
Credential Manager*
Select the desired credential manager from the drop-down list. Relevant parameters will be displayed based on the selection.
Supported Credential Managers:
OE Credential Manager
AWS Secrets Manager
HashiCorp
Azure Key Vault
For more details, click here.
Connector Name*
Enter a unique name for the HubSpot connection
(Example: "HubSpot_Prod").
Connector Environment
Select the environment (Example: PROD, STG) configured for the connector.
For more details, click here.
Connector Description
Enter the description related to the connector.
HubSpot API Key*
Enter the HubSpot Private App Access Token used to authenticate with the HubSpot CRM API.
Proxy Enabled*
Select Yes to route API calls through a proxy server. Select No to bypass the proxy and connect directly.
Plugin Server
Enter the server’s name when running as a plugin server.
Plugin Port
Enter the port number on which the plugin is running.
Default Governance Roles
Default Governance Roles*
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.
Admin Roles
Admin Roles*
Select one or more users from the drop-down list for Integration Admin and Security & Governance Admin. All users configured in OvalEdge Security are available for selection.
No of Archive Objects
No Of Archive Objects*
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.
Example: Setting it to 4 retrieves the last four changes, displayed in the 'Version' column of the 'Metadata Changes' module.
Bridge
Select Bridge*
If applicable, select the bridge from the drop-down list.
The drop-down list displays all active bridges configured in OvalEdge. These bridges enable communication between data sources and OvalEdge without altering firewall rules.
After entering all connection details, the following actions can be performed:
Click Validate to verify the connection.
Click Save to store the connection for future use.
Click Save & Configure to apply additional settings before saving.
The saved connection will appear on the Connectors home page.
Manage Connector Operations
Crawl/Profile
The Crawl/Profile button allows users to select one or more schemas for crawling and profiling.
Navigate to the Connectors page and click Crawl/Profile.
Select the schemas to crawl.
The Crawl option is selected by default. To perform both operations, select the Crawl & Profile radio button.
Click Run to collect metadata from the connected source and load it into the Data Catalog.
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.
Click the Schedule checkbox to enable the Select Period drop-down.
Select a time period for the operation from the drop-down menu.
Click Schedule to initiate metadata collection from the connected source.
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:
Connectors 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, including databases, tables, columns, and codes.
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.
Access Instructions: Add notes on how data can be accessed.
Business Glossary Settings: Manage term associations at the connector level.
Lineage: Configure Server Dialects for source code parsing and Connector Priority for table lineage connection. For more details, click here.
Others: Configure notification recipients for metadata changes.
Delete Connector: Remove a connector with confirmation.
For more details on connector settings, click here.
Limitations
The following limitations apply to HubSpot data types and profiling capabilities:
Enumeration
Profiling is not supported. Enumeration properties are excluded from sample profiling.
Phone Number
Profiling is partially supported. Minimum and maximum value profiling is not supported.
Boolean
Minimum and maximum value profiling is not supported.
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.
1
Error while validating connection: authentication failure
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. Resolution:
Confirm the access token has the scope for the contacts API, since this is the primary permission checked during validation.
Verify the token scopes using Postman or a curl command against the HubSpot API.
Review the JSON response returned by the HubSpot API, since it states the exact scope that is missing.
2
Error while validating connection: token expired
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. Resolution:
Confirm whether the token has expired by checking its status in the HubSpot account.
Create a new access token in HubSpot when the previous one has expired or was rotated.
Update the connector with the new token and revalidate the connection.
3
Connection timeout or proxy error
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. Resolution:
Confirm whether a proxy server is used in the environment.
Enable the proxy option in the connector settings and provide the proxy details when one is used.
Validate the connection again once the proxy option is enabled.
4
JSON response contains error from HubSpot API
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. Resolution:
Review the JSON response to identify the exact cause.
Verify that the access token includes the required scopes and that the requested object type is valid.
If a 429 (Rate Limit Exceeded) error occurs, wait before retrying the request or reduce the request frequency.
1
Failed to get remote tables or columns
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. Resolution: • Verify that the access token has read access to the required HubSpot CRM objects. • For custom objects, ensure the required custom schema scope is enabled. • Confirm that the required objects exist in the connected HubSpot account.
2
Preview error while viewing object data
The access token does not have read permission for the specific object being previewed. Resolution: • Confirm the access token includes read permission for the object being previewed. • Add the missing scope to the token in HubSpot if it is not present. • Retry the preview after updating the token.
3
Unsupported data type warning appears in the crawl log
Certain HubSpot data types have limited support for specific connector operations. The connector records a warning instead of stopping the crawl. Resolution: • Review the crawl log for the warning message and identify the property and data type involved. • Refer to the FAQs section for the supported data types and their profiling limitations. • Continue the crawl, since the warning does not stop cataloguing of the remaining supported properties.
FAQs
1
What is the HubSpot connector used for?
HubSpot is a platform that combines marketing, sales, customer service, and content management. The connector brings its CRM data into the application.
Only the CRM module is supported at present.
Contacts, companies, deals, tickets, products, projects, and line items are catalogued.
Other HubSpot modules, such as marketing and content, are planned for later releases.
2
How is HubSpot represented in the application?
HubSpot is treated as a relational database-style connector.
There is no schema or table concept in HubSpot itself, only objects and properties.
Each object, such as contacts or deals, is treated as a table.
Each property of an object is treated as a column.
3
What is needed to set up the connector?
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.
4
Why is a client secret not used?
A client secret does not enable the API calls required by this connector. The connector uses the access token mechanism for authentication.
5
What permission does the access token need at minimum?
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.
6
Does the access token expire?
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.
7
How are default objects different from custom objects?
HubSpot supports both default and user-created objects.
Default objects, such as contacts, companies, deals, and products, are catalogued under the default HubSpot schema.
Objects created by users are catalogued under a separate custom schema.
8
Which objects were recently added to the connector?
Support for projects and line items was added in addition to the original default objects.
9
Can data be stored in a credential manager?
Yes. Credential manager support is available for this connector.
10
Is proxy access supported?
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.
1
What connectivity method does the connector use?
The connector uses REST APIs to access HubSpot for crawling, sample profiling, and data preview operations.
2
Which features are supported by this connector?
The following features are supported:
Crawling
Sample profiling
Data preview
Manual lineage
Full profiling, Query Sheet, Auto Lineage, and Data Quality are not supported.
3
Why is only sample profiling supported instead of full profiling?
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.
4
How does profiling work for this connector?
Profiling is performed in memory rather than through aggregate functions.
Data available for an object is retrieved.
Supported profiling metrics are calculated from the retrieved data.
Aggregate functions are not used because the connector supports sample profiling.
5
Are there any data type profiling limitations?
Yes. The following data types have profiling limitations:
Enumeration: Profiling is not supported. Enumeration properties are excluded from sample profiling.
Phone Number: Profiling is partially supported. Minimum and maximum value profiling are not supported.
Boolean: Minimum and maximum value profiling are not supported.
6
Are unsupported data types reported during crawling?
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.
7
Why is Auto Lineage not supported?
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.
8
Why is Data Quality not supported?
Data Quality rules are not available for this connector at present. This applies to the connector as a whole and not to specific objects.
9
What does the Query Sheet limitation mean?
Query Sheet is not available for this connector because the connector relies on REST API calls rather than a queryable data source.
Copyright © 2026, OvalEdge LLC, Peachtree Corners GA USA
Last updated
Was this helpful?