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.

Choose OAuth to sign in to HubSpot and approve Sonora. If you need to use your own HubSpot private app, choose Manual and enter its access token. The Connection panel shows one method at a time.

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

Sonora reads data from your HubSpot portal.

Prerequisites

• A HubSpot user who can approve Sonora for the account, or an account admin who can create a private app for a manual connection
• A HubSpot subscription that includes the CRM API (all paid tiers, plus most free tiers for the basic objects)
• Permission to manage integrations in Sonora

Connect with OAuth

1. In Sonora, open Settings → Integrations → HubSpot.
2. Under Connection, keep OAuth selected and click Connect HubSpot.
3. Sign in to HubSpot, choose the account to connect, and approve the requested access.
4. HubSpot returns you to Sonora with the connection saved. Review your company filters and field mappings, then choose Save only or Save & sync.

To authorize again, select OAuth and click Reconnect HubSpot. Your saved filters and mappings are kept.

Manual connection

Select Manual if you have a HubSpot private app token. You don’t need to complete the OAuth steps for this method.

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. In Sonora, open Settings → Integrations → HubSpot.
2. Under Connection, select Manual.
3. Paste the access token into Private app token.
4. Review your company filters and field mappings, then choose Save only or Save & sync.

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 the ones you use keeps prompts focused and answers cleaner.

Disconnect

From Settings → Integrations, open the HubSpot card and disconnect the integration to remove its saved credentials. For a manual connection, 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.