Guides
Connect HubSpot
HubSpot is VocxAI's revenue source: it supplies the companies and closed-won deals behind every ARR figure you see, and lets signals from every other connector be matched to the right customer.
Step 1: Create a Service Key in HubSpot
In the HubSpot account you want to connect, open Settings → Integrations → Service Keys, click Create a service key, and name it VocxAI so its purpose is clear later.
You need HubSpot Super Admin or Developer Tools access to create and manage Service Keys.
Step 2: Grant read-only CRM access
Add exactly these two scopes to the Service Key:
| Scope | Why VocxAI needs it |
|---|---|
crm.objects.companies.read |
Reads company names, domains and websites so signals can be matched to the correct customer. |
crm.objects.deals.read |
Reads deal value, stage, pipeline, type and close date so closed-won revenue can be calculated and used for ARR scoring. |
These are read-only scopes. VocxAI never changes Companies or Deals in HubSpot, so do not add either write scope. Create the key, copy its value, and keep it private - treat it like a password.
Step 3: Add the key to VocxAI
In VocxAI, go to Settings → Connectors, click Connect on the HubSpot card, and paste the key into HubSpot Service Key. If your account is still connected through the older OAuth flow, click Switch to Service Key instead - your existing sync position and ARR settings are kept.
Click Connect. VocxAI checks the key, identifies the HubSpot account, and verifies Companies and Deals access before saving it securely.
Step 4: Let the first sync run
HubSpot now shows as connected and the first sync starts in the background. A large portal can take several sweeps to finish (see how sync works). Click Sync now on the card if you don't want to wait for the next scheduled sweep.
Step 5: Choose which deals count as ARR (optional)
By default every closed-won deal across every pipeline and deal type counts toward a company's ARR. If that overcounts for you - for example a "Services" pipeline that shouldn't count as recurring revenue - click ARR settings on the HubSpot card and uncheck the pipelines or deal types that shouldn't be included, then Save and recalculate ARR. See Revenue scoring for exactly how the total is computed.
Managing the Service Key
Service Keys are long-lived credentials, so there is no OAuth token refresh or recurring authorization prompt. If you rotate the key in HubSpot, return to the HubSpot connector card in VocxAI, click Replace key, and paste the replacement. HubSpot provides a seven-day grace period during rotation, giving you time to update VocxAI before the old key stops working.
If you delete the key or remove either read permission in HubSpot, the next sync will fail and the connector card will ask you to replace the key or restore its permissions.
What this is used for
Companies and deals never become signals themselves - they're the pricing layer. Every theme's ARR-at-risk and ARR-unlocked figures come from here, and every signal from every other connector gets linked to a HubSpot company so its revenue context shows up alongside the evidence. Full mechanics: Revenue scoring.
Disconnecting
Disconnect in Settings → Connectors removes the connection and deletes the synced companies and deals - they're the customer's financial data, so nothing is kept once you disconnect. Signals stay, just unlinked from any company.