Skip to content
Pipemetry docs

Connect HubSpot

Pipemetry reads your HubSpot deals, their property history, and your owners. It never writes back to HubSpot.

The same walkthrough is built into the app, with copy-to-clipboard values, on the HubSpot card under Onboarding.

What Pipemetry needs from you

  • A HubSpot app with read access to your deals.
  • One credential: either a private-app access token (starts with pat-) or an OAuth client id + client secret + refresh token for a public app.
  • These three CRM scopes granted to that app:
crm.objects.deals.read
crm.schemas.deals.read
crm.objects.owners.read

You need Super Admin on a regular HubSpot portal (not a developer-account portal) to create a private app.

Step 1 — Choose how to connect

HubSpot renamed standalone Private apps to legacy apps and moved new development to the Projects platform. Pipemetry accepts either result, so pick whichever path your account uses — you only need one.

  • Fastest for most teams: a private app (step 2, option A). It gives you a single, non-expiring access token. HubSpot labels these “legacy”, but they are fully supported and are the quickest path for an API-only integration.
  • If your org has standardised on the new platform: a Projects app (step 2, option B), created with the HubSpot CLI.

Step 2, option A — Private app (recommended)

  1. In HubSpot, open Development → Legacy apps. (On older portals: Settings ⚙ → Integrations → Private Apps.)
  2. Create legacy app → choose Private.
  3. Basic Info: name it Pipemetry.
  4. Scopes tab → Add new scope → search for and check crm.objects.deals.read, crm.schemas.deals.read, crm.objects.owners.read → Update.
  5. Create app and confirm.
  6. Open the app → Auth tab → Show token → copy the access token (it starts with pat-).

Step 2, option B — A new app on the Projects platform

  1. Install the CLI: npm install -g @hubspot/cli, then hs init to authenticate.
  2. hs project create → add an app component. Choose a private app for a token, or a public app for OAuth.
  3. Grant the same three CRM scopes.
  4. hs project upload to build and deploy, then install the app on your account.
  5. For a private app in the project, copy its access token. For a public app, note the Client ID and Client secret, and generate a Refresh token through the OAuth flow.

Step 3 — Connect in Pipemetry

On the HubSpot card in Onboarding:

  1. Pick your grant.
  2. Private app: paste the access token (pat-…) and Save. OAuth: enter the Client ID, Client secret and Refresh token and Save.
  3. Click Verify — it checks that your deals and the required properties are readable.
  4. Click Run backfill to import your deal history.

Credentials are stored encrypted and never returned: secret fields are always blank when you reopen the form.

What Pipemetry reads

  • Required deal properties: Amount, Deal stage and Close date — mapped to Pipemetry’s amount, stage and close-date.
  • Deal property history (propertiesWithHistory), read through crm.objects.deals.read. This is what makes point-in-time and trend views accurate.
  • Owners (crm.objects.owners.read), so the forecast can be broken down by owner.

HubSpot deals land in the same canonical event log Salesforce writes to, so forecasting, trends and point-in-time reconstruction behave identically once connected.

How the sync stays current

Two consequences worth knowing:

  • The full backfill must run first — until it does there is no watermark, and the incremental sync reports that it has nothing to sync from.
  • The watermark only advances after a write succeeds, so a mid-run failure re-covers the same window on the next run. Re-writing the same events is harmless: every event is content-addressed, so a repeat writes nothing new.

HubSpot reference