> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://katalyz.crisp.help/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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)

1. Go to **Settings → Integrations**.
2. Find **HubSpot** in the list.
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; 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.

1. Each user opens **their profile**.
2. They click **Sign in with HubSpot** and authorize the connection.
3. 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](https://katalyz.crisp.help/en/article/my-crm-isnt-syncing-hubspot-salesforce-16192yz/) 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](https://katalyz.crisp.help/en/article/crm-field-mapping-sync-hubspot-salesforce-fzz4c/).

## Disconnecting

**Settings → Integrations → HubSpot → Disconnect**. See [Disconnecting an integration](https://katalyz.crisp.help/en/article/disconnecting-an-integration-prb53m/).

## Related articles
- [HubSpot: syncing rooms with deals, companies and contacts](https://katalyz.crisp.help/en/article/hubspot-syncing-rooms-with-deals-companies-and-contacts-mahadg/)
- [CRM field mapping & sync](https://katalyz.crisp.help/en/article/crm-field-mapping-sync-hubspot-salesforce-fzz4c/)
- [Troubleshooting HubSpot sync](https://katalyz.crisp.help/en/article/my-crm-isnt-syncing-hubspot-salesforce-16192yz/)