> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zudo.so/llms.txt
> Use this file to discover all available pages before exploring further.

# HubSpot

> Connect your HubSpot portal to Zudo. Early access: connecting works today, and company sync is coming next.

The HubSpot integration is being built in stages. Today you can connect a HubSpot portal to your Zudo organization. Zudo checks the token, shows you which portal it belongs to and what it can read, and lets you disconnect cleanly.

<Warning>
  **Nothing syncs from HubSpot yet.** Connecting a portal doesn't add traits, contacts or deals to your accounts.
  Company sync is the next stage, and this page will be updated when it ships.
</Warning>

## Availability

HubSpot is in **early access**. The HubSpot option only appears under **Settings → Connections → Add Connection** once it has been turned on for your organization. Contact us to turn it on.

Each organization can connect **one** HubSpot portal.

## What you need

A HubSpot token with **read** access to:

| Object    | Scope                        | Required?                                          |
| --------- | ---------------------------- | -------------------------------------------------- |
| Companies | `crm.objects.companies.read` | Yes. Zudo won't save a token that can't read them. |
| Contacts  | `crm.objects.contacts.read`  | Recommended                                        |
| Deals     | `crm.objects.deals.read`     | Recommended                                        |
| Owners    | `crm.objects.owners.read`    | Recommended                                        |

Zudo never writes to HubSpot today, so a read-only token is enough.

The token can be either of these. Both start with `pat-`.

* **A service key**, created under **Settings → Integrations → Service Keys** in HubSpot. HubSpot lists service keys as a public beta. Creating one needs a super admin or a user with developer tools access, and a key can only be given scopes the person creating it already has.
* **A legacy private app token**, from **Settings → Integrations → Private Apps**.

<Note>
  HubSpot is ending the creation of new legacy private apps: for existing HubSpot accounts, the option goes away on
  **October 26, 2026**. Private apps created before then keep working. After that date, use a service key.
</Note>

## Connect

<Steps>
  <Step title="Create the token in HubSpot">
    Create a service key or private app with the read scopes above, and copy its token.
  </Step>

  <Step title="Add the connection in Zudo">
    Go to **Settings → Connections**, click **Add Connection**, select **HubSpot**, and paste the token.
  </Step>

  <Step title="Check the connection card">
    Zudo verifies the token with HubSpot before saving it. Expand the HubSpot connection card to see the portal ID,
    account type, time zone and currency, and a link to the portal's companies in HubSpot.
  </Step>
</Steps>

## What Zudo checks when you connect

* **The token works.** A revoked, expired or mistyped token is rejected with a message saying so, and nothing is saved.
* **It can read companies.** A token without company read access is rejected, and the error names the missing scope where HubSpot provides it.
* **What else it can read.** Zudo tries to read one contact, one deal and one owner. If any of them fail, the connection is still saved, and the card warns you which objects the token can't read. To fix it, add the missing scopes in HubSpot and connect again.
* **Which portal it belongs to.** If HubSpot doesn't return portal details for the token, the connection is still saved without them.

## Disconnect

An organization admin can disconnect HubSpot from the connection card:

1. Expand the HubSpot connection under **Settings → Connections**.
2. Click **Disconnect**. Zudo shows how many trait definitions and values will be deleted.
3. Type `DISCONNECT` and confirm.

Disconnecting deletes the stored token and every trait synced from HubSpot. Your accounts and contacts are kept, because HubSpot never creates them. While nothing syncs, there are no HubSpot traits to delete.

## What's coming

These are planned, in roughly this order. None of them are available yet.

* **Company sync.** HubSpot company properties you choose land on matching accounts as traits, usable in segments, smart traits, filters and reports. Companies are matched to accounts by HubSpot record ID or domain, and unmatched companies are listed for review.
* **Contacts.** HubSpot contacts are linked to the right accounts, with contact owner and job title.
* **Deals as traits.** Deal summaries on each account, such as open deal amount and the last closed-won date, with stage names instead of stage IDs.
* **Write-back.** Health score, MRR, segments and renewal date are written to Zudo-owned properties on each HubSpot company, so your sales team sees them without leaving HubSpot.