> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pivotal.app/llms.txt.
> For full documentation content, see https://docs.pivotal.app/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pivotal.app/_mcp/server.

# Connect HubSpot

HubSpot is the source of truth for who your customers are. Pivotal pulls HubSpot companies into Pivotal customers, and HubSpot contacts into Pivotal contacts, on a one-way sync. Changes in HubSpot show up in Pivotal. Changes in Pivotal stay in Pivotal.

You need to be a Pivotal **admin** and have a HubSpot account with **Sales Hub Professional or above** to authorize the OAuth scopes.

## Wire it up

Go to **Admin > Integrations > HubSpot** and click **Connect HubSpot**.

HubSpot opens its consent screen. Pivotal asks for read access on `crm.objects.companies`, `crm.objects.contacts`, `crm.schemas.companies`, and `crm.schemas.contacts`. Pick the HubSpot account you want to connect and click **Connect app**.

Back in Pivotal, pick which HubSpot companies to mirror. You can scope by HubSpot list (recommended), lifecycle stage, or pipeline. Most teams pick a list called *Customers / Active* to keep prospects and churned accounts out.

Pivotal shows the default field map: HubSpot `Company name` to Pivotal `name`, `Domain` to `domain`, `Hubspot Owner` to `owner`, `Annual Revenue` to `arr`. Add custom fields here or [open the full field mapping doc](/product/integrations/field-mapping) for the reference table.

Sync runs one-way, HubSpot to Pivotal. There is no toggle to flip it. If you need a field to flow the other way, use a [webhook](/product/integrations/webhooks) to write back to HubSpot from your own code.

Click **Run initial sync**. The first pull takes 30 seconds for a few hundred companies, longer for thousands. Watch the count tick up on the integration page. When it finishes, every mirrored company shows up in your Customers list.

## How updates flow after the initial sync

Two paths keep Pivotal in step with HubSpot:

* **Real-time**: HubSpot fires a webhook to Pivotal when a company or contact changes. Most updates land within ten seconds.
* **Nightly reconciliation**: Pivotal runs a full diff against HubSpot at 02:00 UTC to catch anything the webhook missed (HubSpot webhooks have a small drop rate). Deletions also surface in the nightly pass.

## Gotcha: HubSpot deletes do not delete in Pivotal

If you delete a company in HubSpot, the matching Pivotal customer archives. It does not hard-delete. The onboarding, tasks, and history stay intact so you can resurrect the customer if the deletion was a mistake. To purge for real, open the archived customer and click **Delete permanently**.

## Related

* [Field mapping](/product/integrations/field-mapping)
* [Troubleshoot sync](/product/integrations/troubleshoot-sync)
* [Connect your CRM](/product/setup/connect-your-crm)

Email **[help@pivotal.app](mailto:help@pivotal.app)** with a screenshot of where you got stuck and the customer or onboarding id from the URL.