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. However, if you want to use workflow triggers and actions, Operations Hub Pro (or above) on the HubSpot side is required.

Connect the integration (org level)

Go to Settings → Integrations.
Find HubSpot in the list.
Click Connect.
You're redirected to HubSpot for OAuth authorization.
Pick the portal you want to connect.
Review the permissions Katalyz is requesting and click Authorize.
You're redirected back to Katalyz; integration status shows Connected.

User-level connection

Once the HubSpot integration is enabled at the workspace level by an admin, each user also has to 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.

Each user opens their profile.
They click Sign in with HubSpot and authorize the connection.
From then on, their actions use their own HubSpot token.

Without this step, the org-level integration is still healthy but that user's individual actions won't sync. See My CRM isn't syncing for the full two-level 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.

After connecting

Once the integration is connected, configure specifics in Settings → HubSpot:

Synced fields — map Katalyz properties to HubSpot properties
Activities — choose which Katalyz events post to HubSpot timelines
Tasks — sync Katalyz tasks with HubSpot tasks

See CRM field mapping & sync.

Disconnecting

Settings → Integrations → HubSpot → Disconnect. See Disconnecting an integration.

Updated on: 18/06/2026

Was this article helpful?

Thank you!