HubSpot Connector

Connect to HubSpot to index contacts, companies, deals, tickets, and engagement history for AI-powered search across your CRM data.

Overview

The HubSpot connector allows you to:

• Index CRM records (contacts, companies, deals, tickets)
• Access engagement history (emails, calls, notes)
• Sync relationships between records (associations)
• Enable permission-aware search based on record ownership
• Perform incremental sync based on modification dates

Prerequisites

• HubSpot account (any tier — Free, Starter, Professional, or Enterprise)
• API access enabled
• OAuth authorization or Private App token

Authentication

OAuth 2.0 (Recommended)

OAuth provides the simplest setup and automatic token refresh:

1. Click Connect with HubSpot in the ZenSearch connector setup
2. Authorize ZenSearch to access your HubSpot account
3. Select the account if you have multiple HubSpot portals

Private App Token

For organizations that prefer API key-based authentication:

1. Go to HubSpot Settings → Integrations → Private Apps
2. Create a new Private App
3. Grant the required scopes:
   • crm.objects.contacts.read
   • crm.objects.companies.read
   • crm.objects.deals.read
   • tickets
   • e-commerce (if syncing products)
4. Copy the generated access token
5. Enter it in the Access Token field in ZenSearch

Configuration Reference

Setting	Type	Required	Description
Access Token	string	Yes*	Private App token (*or OAuth credentials)
Object Types	array	No	CRM objects to sync: contacts, companies, deals, tickets (default: all)
Modified After	string	No	ISO 8601 datetime — only sync records modified after this date
Include Associations	boolean	No	Fetch relationships between records (e.g., contacts linked to deals)
Include Permissions	boolean	No	Sync owner/team permissions for permission-aware search
Page Size	integer	No	Records per API page (default: 100, max: 100)
Max Records	integer	No	Maximum records per object type (default: 10,000; 0 = unlimited)

OAuth Configuration

Setting	Type	Required	Description
Refresh Token	string	Yes	OAuth refresh token (obtained during authorization)
Client ID	string	Yes	OAuth client ID
Client Secret	string	Yes	OAuth client secret

Setup Steps

1. Add Connector: Navigate to Knowledge → Add Data Source → HubSpot
2. Authorize: Connect via OAuth or enter a Private App token
3. Select Objects: Choose which CRM objects to index
4. Configure Options: Set date filters, associations, and permissions
5. Test & Create: Verify the connection and save

Objects Indexed

Object	Content Indexed	Key Properties
Contacts	People records with contact details	Name, email, phone, company, lifecycle stage, owner
Companies	Organization data	Name, domain, industry, revenue, employee count, owner
Deals	Sales pipeline opportunities	Name, amount, stage, close date, pipeline, owner
Tickets	Support requests	Subject, description, priority, status, pipeline, owner
Notes	Activity notes attached to records	Body text, associated records, created date
Calls	Call recordings and notes	Duration, outcome, notes, associated records
Emails	Email communication history	Subject, body, sender, recipients, associated records

Associations

When Include Associations is enabled, ZenSearch fetches relationships between objects. For example:

• A Deal associated with a Company and multiple Contacts
• A Ticket linked to the Contact who submitted it
• Notes and Emails attached to specific records

Associations provide richer context for AI-generated answers, allowing questions like "What emails have we exchanged with Acme Corp about their enterprise deal?"

Permissions

When Include Permissions is enabled, ZenSearch syncs record ownership and team assignments from HubSpot. This enables permission-aware search — users only see CRM records they have access to based on HubSpot's visibility settings.

Rate Limits

HubSpot enforces API rate limits based on your account tier:

Tier	Rate Limit
Free / Starter	100 calls per 10 seconds
Professional	150 calls per 10 seconds
Enterprise	200 calls per 10 seconds

ZenSearch respects these limits automatically (default: 10 requests/second for search, 5 for regular API calls). If you experience rate limiting, reduce the page_size or schedule syncs during off-peak hours.

Best Practices

1. Focus on active records — Use modified_after to filter out stale data and reduce sync time
2. Enable associations — Associations significantly improve AI answer quality by providing relationship context
3. Include engagement history — Notes, emails, and calls provide valuable context for sales and support queries
4. Use permissions for sales teams — Enable include_permissions so sales reps only see their own pipeline data
5. Set reasonable max records — For large CRM databases, use max_records to limit initial sync volume

Troubleshooting

Authorization failed

• Re-authenticate through the OAuth flow
• For Private Apps, verify the token hasn't been revoked
• Check that the required scopes are granted

Missing data

• Verify your HubSpot account has the required access level for the selected objects
• Check that the Private App has the necessary scopes
• Ensure records exist within the modified_after date filter

Rate limit errors

• HubSpot enforces per-account rate limits; reduce sync frequency
• Check if other integrations are consuming your rate limit quota
• Consider upgrading your HubSpot plan for higher limits

Slow sync performance

• Use modified_after for incremental sync instead of full re-sync
• Reduce max_records to limit the scope
• Disable include_associations if relationship data is not needed

Related

• Salesforce
• SAP S/4HANA