HubSpot

This documentation describes the integration of MindsDB with HubSpot. The HubSpot handler for MindsDB provides interfaces to connect to HubSpot via APIs and pull store data into MindsDB. HubSpot is a comprehensive CRM platform providing marketing, sales, content management, and customer service tools. This integration exposes HubSpot CRM data through MindsDB’s SQL interface.

Prerequisites

Before proceeding, ensure the following prerequisites are met:

1. Install MindsDB locally via Docker or Docker Desktop.
2. To connect HubSpot to MindsDB, install the required dependencies following this instruction.

Authentication

The handler supports two authentication methods:

Personal Access Token Authentication

Recommended for server-to-server integrations and production environments.

Steps to obtain an access token:

1. Navigate to your HubSpot account settings
2. Go to Integrations -> Private Apps
3. Create a new private app or select an existing one
4. Configure required scopes for the tables you plan to access
5. Copy the generated access token

OAuth Authentication

Recommended for applications requiring user consent and dynamic scope management.

Required OAuth Parameters:

• client_id: Your app’s client identifier
• client_secret: Your app’s client secret (store securely)

OAuth token exchange and refresh are handled externally.

Supported Tables

Core CRM and Engagement Tables

These tables support SELECT, INSERT, UPDATE, and DELETE operations.

Table Name	Description	Reference
companies	Company records from HubSpot CRM	https://developers.hubspot.com/docs/api-reference/crm-companies-v3/guide
contacts	Contact records from HubSpot CRM	https://developers.hubspot.com/docs/api-reference/crm-contacts-v3/guide
deals	Deal records from HubSpot CRM	https://developers.hubspot.com/docs/api-reference/crm-deals-v3/guide
tickets	Support ticket records	https://developers.hubspot.com/docs/api-reference/crm-tickets-v3/guide
tasks	Task and follow-up records	https://developers.hubspot.com/docs/api-reference/crm-tasks-v3/guide
calls	Call log records	https://developers.hubspot.com/docs/api-reference/crm-calls-v3/guide
emails	Email log records	https://developers.hubspot.com/docs/api-reference/crm-emails-v3/guide
meetings	Meeting records	https://developers.hubspot.com/docs/api-reference/crm-meetings-v3/guide
notes	Timeline notes	https://developers.hubspot.com/docs/api-reference/crm-notes-v3/guide

Metadata Tables

These tables are read-only and support SELECT only.

Table Name	Description	Reference
owners	HubSpot owners with names and emails	https://developers.hubspot.com/docs/api-reference/crm-owners-v3/guide
pipelines	Deal pipelines with names and stages	https://developers.hubspot.com/docs/api-reference/crm-pipelines-v3/guide

Association Tables

Association tables are read-only and support SELECT only. They expose relationships between objects and include association_type and association_label columns.

Reference: https://developers.hubspot.com/docs/api-reference/crm-associations-v4/guide

Table Name	Description
company_contacts	Company to contact associations
company_deals	Company to deal associations
company_tickets	Company to ticket associations
contact_companies	Contact to company associations
contact_deals	Contact to deal associations
contact_tickets	Contact to ticket associations
deal_companies	Deal to company associations
deal_contacts	Deal to contact associations
ticket_companies	Ticket to company associations
ticket_contacts	Ticket to contact associations
ticket_deals	Ticket to deal associations

Connection

Using Access Token:

CREATE DATABASE hubspot_datasource
WITH ENGINE = 'hubspot',
PARAMETERS = {
  "access_token": "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
};

Using OAuth (Advanced):

CREATE DATABASE hubspot_datasource
WITH ENGINE = 'hubspot',
PARAMETERS = {
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
};

Usage

Basic Data Retrieval:

SELECT * FROM hubspot_datasource.companies LIMIT 10;
SELECT * FROM hubspot_datasource.contacts LIMIT 10;
SELECT * FROM hubspot_datasource.deals LIMIT 10;

Date Filters (Supported Functions):

SELECT * FROM hubspot_datasource.deals
WHERE closedate >= DATE_SUB(CURRENT_DATE, INTERVAL 2 YEAR);

Creating Records:

INSERT INTO hubspot_datasource.companies (name, domain, industry, city, state)
VALUES ('Acme Corp', 'acme.com', 'COMPUTER_SOFTWARE', 'New York', 'NY');

INSERT INTO hubspot_datasource.contacts (email, firstname, phone)
VALUES ('[e-mail]', 'John', '[phone]');

INSERT INTO hubspot_datasource.tasks (hs_task_subject, hs_task_status)
VALUES ('Follow up with Acme', 'WAITING');

Updating Records:

UPDATE hubspot_datasource.companies
SET industry = 'COMPUTER_SOFTWARE', city = 'Austin'
WHERE name = 'Acme Corp';

UPDATE hubspot_datasource.deals
SET dealstage = '110382973', amount = '75000'
WHERE dealname = 'New Deal';

Deleting Records:

DELETE FROM hubspot_datasource.deals
WHERE dealstage = 'closedlost'
  AND createdate < '2023-01-01';

Notes on Filters and Limits

• Supported filter operators include =, !=, <, <=, >, >=, IN, and NOT IN.
• Date helpers supported in filters include CURDATE()/CURRENT_DATE, NOW()/CURRENT_TIMESTAMP, DATE_SUB, and DATE_ADD.
• Updates and deletes evaluate conditions against a sample of up to 200 records before applying changes.
• Unsupported filters or order-by expressions are skipped rather than raising errors.