# HubSpot

> Connect HubSpot, choose which companies become customers, and keep the connection's permissions up to date.

import { Aside, Steps } from '@astrojs/starlight/components';

Connect HubSpot once and CustomerCatalyst brings in your companies, contacts and their activity, every night and whenever you press **Sync now**.

## Connect

You need to be an organization admin in CustomerCatalyst, and able to approve apps in your HubSpot account.

<Steps>

1. Open **Integrations** in the sidebar and choose **HubSpot**.
2. Click **Connect to Hubspot**.
3. Sign in, pick the HubSpot account to connect, and approve the permissions.
4. HubSpot sends you back to Integrations. The button now reads **Import Customers & Sync**.
5. Check [which companies become customers](#choose-which-companies-become-customers) and which [data types](#what-syncs) are on, then click **Import Customers & Sync** for the first full import.

</Steps>

After the first import, HubSpot syncs every night by itself. See [Syncing](/integrations/syncing/).

## Choose which companies become customers

Under **Customer status**, decide which HubSpot companies become customers and whether each one is active or churned. This runs on every sync.

- **Default**: companies with the lifecycle stage "customer" become active customers. Companies at any other stage aren't imported.
- **Custom**: pick a field on the HubSpot company, then map its values to a CustomerCatalyst status under **Status value mappings**. Add at least one value mapping.

A company whose value has no mapping isn't imported. A company that is already a customer is still updated.

## What syncs

Each data type has its own **Sync** switch. Organization admins turn them on or off.

| In CustomerCatalyst | From HubSpot |
|---|---|
| Customers | Companies |
| Contacts | Contacts |
| Calls | Calls |
| Meetings | Meetings |
| Tasks | Tasks |
| Tickets | Tickets, with their messages and notes |
| Notes | Notes |
| Opportunities | Deals |

Owners are matched to your team by email: a HubSpot owner whose email belongs to a CustomerCatalyst user becomes the owner here. Owners with no matching user stay empty, and no users are created.

Which HubSpot property fills which field is set under [Field mapping](/integrations/field-mapping/).

## HubSpot tickets are read-only

Tickets sync from HubSpot into CustomerCatalyst. Nothing is sent back.

- On a ticket from HubSpot you can add internal notes, but there is no public reply. Answer the customer in HubSpot.
- Turning on ticket sync switches the **Support tickets** health metric to Automatic for all your customers. You can change this any time in Health score settings, or for a single customer.

<Aside type="caution" title="Duplicate tickets">
If your support address sends email to both HubSpot and CustomerCatalyst (see [Support](/support/)), each email becomes two tickets. Use only one of them for your support address.
</Aside>

## Permissions

CustomerCatalyst asks HubSpot for these permissions:

- `oauth`
- `crm.objects.contacts.read`, `crm.objects.contacts.write`
- `crm.objects.companies.read`, `crm.objects.companies.write`
- `crm.objects.deals.read`, `crm.objects.deals.write`
- `crm.objects.tickets.read`, `crm.objects.tickets.write`
- `crm.schemas.tickets.read`, `crm.schemas.tickets.write`
- `crm.objects.owners.read`
- `crm.objects.feedback_submissions.read`
- `crm.objects.marketing_events.read`, `crm.objects.marketing_events.write`
- `sales-email-read`

## Missing permissions and reconnecting

When CustomerCatalyst needs a permission the connection doesn't have yet, organization admins see:

> Hubspot needs new permissions. Reconnect to keep syncing.

Click **Reconnect**, sign in to the **same** HubSpot account and approve. Your connection, settings and mappings stay as they are.

Until you reconnect, a data type that needs the missing permission shows *Missing permission:* followed by its name, and you can't switch it on. Types that are already on can still be switched off.

<Aside type="caution">
Reconnecting with a **different** HubSpot account changes nothing: the existing connection stays linked to the first account, and no message is shown. To move to another HubSpot account, disconnect first and connect again.
</Aside>

## Disconnect

Organization admins can click **Disconnect** on the HubSpot page and confirm. This removes the connection and stops syncing. Records that were already synced stay in CustomerCatalyst.