HubSpot

HubSpot brings in your CRM data — companies become Sonora customers, contacts populate People Graph, deals and engagements feed health scoring and renewal context. Like other CRM connectors, it’s the foundation for everything Sonora can say about an account.

The integration uses a HubSpot Private App access token. HubSpot retired its legacy API keys in 2022; private apps are the supported way to authorize CRM access.

What syncs

Object	Notes
Companies	Become Sonora customers
Contacts	Map into People Graph
Deals	Stage, amount, close date, owner
Owners	Sales reps and CSMs assigned to deals/companies
Notes and engagements	Calls, emails, meetings, tasks logged in HubSpot
Tickets	Optional; enable if you use HubSpot Service Hub
Custom properties	Pulled along with the parent object

The token is read-only — Sonora doesn’t write to your HubSpot portal.

Prerequisites

• HubSpot account admin (Super Admin recommended) so you can create private apps
• A HubSpot subscription that includes the CRM API (all paid tiers, plus most free tiers for the basic objects)

Setup

1. Create a HubSpot private app

1. In HubSpot: Settings → Integrations → Private Apps.
2. Click Create a private app. Name it “Sonora Integration” and add a description.
3. On the Scopes tab, add the read scopes Sonora needs:
   • crm.objects.contacts.read
   • crm.objects.companies.read
   • crm.objects.deals.read
   • crm.objects.owners.read
   • crm.schemas.contacts.read, crm.schemas.companies.read, crm.schemas.deals.read (for custom property metadata)
4. If you use Service Hub and want tickets: add the tickets scope.
5. Click Create app, confirm, and copy the Access token that HubSpot shows you. You can’t view this token again — store it in a password manager if you need it later.

2. Connect in Sonora

1. Settings → Integrations → HubSpot → Connect.
2. Paste the access token into the Private Access Token field.
3. Save. Sonora tests the credential, kicks off an initial import, and reports back when the connection is live.

Custom properties

Sonora discovers all custom properties on the Company, Contact, and Deal objects automatically. After the initial sync, open the HubSpot card to choose which custom properties to expose to chat and Canvas. Picking just the ones you actually use keeps prompts focused and answers cleaner.

Disconnect

From Settings → Integrations, click Disconnect on the HubSpot card. Sonora deletes the access token. You can also revoke the token in HubSpot: Settings → Integrations → Private Apps → Sonora → Deactivate.

Troubleshooting

“401 Unauthorized” right after connecting. The token was deactivated, the private app was deleted, or a scope was removed. Reissue the token in HubSpot and reconnect.

Records missing for some users. HubSpot teams and partition rules can scope CRM records to specific reps. The private app sees what its creator can see — to pull everything, create the app from a Super Admin account.

Custom properties not appearing in chat. Properties are loaded once per sync; after enabling a property in the HubSpot card configuration, kick off a re-sync from the same card.

Rate limiting during a large backfill. HubSpot enforces per-portal API limits; Sonora throttles automatically and resumes when the window resets. Initial imports for portals with hundreds of thousands of contacts can take several hours.