Articles on: Integrations

Connecting HubSpot

The HubSpot integration connects your Katalyz workspace to your HubSpot portal — so rooms, deals, contacts, and activity stay in sync.


⚠️ Requires org role Admin.


Before you start


You'll need:

  • HubSpot admin access (to authorize the connection)
  • No minimum HubSpot plan tier is required to install the Katalyz app. Using the Katalyz workflow actions needs a HubSpot plan that includes workflows — a Professional or Enterprise tier of Marketing Hub, Sales Hub, Service Hub, Data Hub, Smart CRM or Revenue Hub.


Connect the integration (org level)


  1. Go to Settings → Integrations.
  2. Find the HubSpot v2 card in the list — "Install the new Katalyz HubSpot app while keeping the legacy integration active during rollout."
  3. Click Connect.
  4. You're redirected to HubSpot for OAuth authorization.
  5. Pick the portal you want to connect.
  6. Review the permissions Katalyz is requesting and click Authorize.
  7. You're redirected back to Katalyz. The card now carries a green check in its top-right corner, and its button has become Disconnect.


Two HubSpot cards, and that's expected. The list holds both HubSpot (legacy) and HubSpot v2. The first is the original app; if your workspace still uses it, it stays connected and its Disconnect button is greyed out — it isn't yours to remove. HubSpot v2 is the one you install today. See Moving to the new Katalyz app for HubSpot.


User-level connection


Once an admin has turned the HubSpot integration on at workspace level, each user must also authorize HubSpot from their own profile for the integration to work fully for them — their own actions (creating a room from a deal, updating a property, back-sync) then authenticate with their own CRM permissions.


This happens in Settings → Profile. At the very top of the page, before the identity fields, sits the list of accounts you've connected personally: one row per service, with its logo, the address used, and a red Remove button.


Once the personal connection is made, a row with the HubSpot logo appears there carrying your address. From then on your actions use your own HubSpot token. If no HubSpot row is listed, the step hasn't been done.


Without this step the org-level integration stays healthy, but that user's individual actions don't sync. See My CRM isn't syncing for the full two-tier model.


What Katalyz requests access to


The HubSpot app installation surfaces the full list of scopes Katalyz requests, split between required and optional.


Required scopes


Scope

Why Katalyz asks for it

oauth

Allows Katalyz to complete the OAuth connection and inspect token / account authorization details.

crm.objects.companies.read

Read HubSpot companies so Katalyz can link rooms to accounts / companies and display CRM account data.

crm.objects.companies.write

Create or update HubSpot company records from Katalyz when CRM sync is enabled.

crm.lists.read

Read HubSpot lists so users can select CRM list segments for workflows and room creation.

crm.lists.write

Manage or update HubSpot list-related data used by Katalyz CRM workflows.

crm.objects.deals.read

Read HubSpot deals to link rooms to opportunities / deals and import deal data.

crm.objects.deals.write

Create or update HubSpot deals with Katalyz room IDs, statuses, and synced fields.

crm.objects.contacts.read

Read contacts associated with companies / deals so Katalyz can invite or sync participants.

crm.objects.contacts.write

Create or update HubSpot contacts from Katalyz when contact sync is enabled.

crm.objects.owners.read

Read HubSpot owners to map CRM owner fields and display owner information.


Optional scopes


Only used if the HubSpot account exposes them or if the corresponding feature is enabled.


Scope

Why Katalyz asks for it

crm.objects.leads.read

Read HubSpot leads when the connected portal supports lead objects.

crm.objects.leads.write

Create or update HubSpot leads when lead sync is available.

crm.objects.appointments.read

Read appointment objects when used in CRM workflows or custom object sync.

crm.objects.appointments.write

Create or update appointment objects when supported.

crm.objects.users.read

Read HubSpot user records for richer user / owner mapping.

settings.currencies.read

Read HubSpot currency settings so Katalyz can handle deal amounts and currencies correctly.

crm.schemas.companies.read

Read company property / schema definitions for custom-field mapping.

crm.schemas.companies.write

Create or update company properties needed for Katalyz sync fields.

crm.schemas.contacts.read

Read contact property / schema definitions for custom-field mapping.

crm.schemas.contacts.write

Create or update contact properties needed for Katalyz sync fields.

crm.schemas.custom.read

Read custom object schemas for custom CRM object support.

crm.schemas.deals.read

Read deal property / schema definitions for pipeline and custom-field mapping.

crm.schemas.deals.write

Create or update deal properties needed for Katalyz sync fields.

crm.objects.custom.read

Read HubSpot custom object records when custom objects are used.

crm.objects.custom.write

Create or update HubSpot custom object records when custom object sync is enabled.

timeline

Create HubSpot timeline events — for example Katalyz activity or signature events shown on CRM records.

integration-sync

Supports HubSpot integration sync capabilities used by the app.

files

Access HubSpot files used by Katalyz workflows, including signature-related files.

files.ui_hidden.read

Read hidden HubSpot files that may be attached to app workflows but not visible in the standard file UI.


What the app installs in your portal


Authorizing the app puts three things into HubSpot:


  • The Katalyz card — made available for deal, company and contact records, listing the dealrooms, recordings and signatures linked to that record, with + New dealroom and + New envelope on the card itself. A HubSpot admin chooses where it sits on the record page; we recommend giving it its own tab. See Working from HubSpot: the Katalyz card, and Moving to the new Katalyz app for HubSpot if you are coming from the previous app.
  • Five workflow actions — Create Dealroom, Invite Contact to related dealroom(s), Invite Related Contacts to Dealroom (with Magic Links), Send message to Dealroom and Generate Magic Link. These need a HubSpot plan that includes workflows. See Katalyz actions in HubSpot workflows.
  • Timeline activity — room and signature events posted onto your HubSpot timelines, controlled by the Activities checkboxes below.


After connecting


Once the integration is connected, everything else is set in Settings → Data → Hubspot. The page is three panels, in this order:


  • Synced fields — "Map your Katalyz fields to HubSpot properties". One row per pair, joined by a ⇄ arrow; + Add new mapping appends one, Refresh list re-reads the properties from HubSpot. Two of these fields are AI-written: Score → Katalyz health score, and Executive summary → Katalyz AI executive summary.
  • Activities — "Choose which user activities to sync with HubSpot". Nine checkboxes, one per event.
  • Tasks — "Katalyz roadmap tasks synced with CRM tasks." Three checkboxes: Sync steps, Sync actions, Sync tasks.


There is no Save button: every checkbox and every row applies as you set it.


See CRM field mapping & sync.


Disconnecting


Settings → Integrations → HubSpot v2 → Disconnect. A connected integration shows a green check badge on its card and its button reads Disconnect; one that isn't connected reads Connect.


The Disconnect button on the HubSpot (legacy) card is greyed out: the original app can't be removed from this screen — go through support. See Disconnecting an integration.


Updated on: 04/10/2026

Was this article helpful?

Share your feedback

Cancel

Thank you!