Connecting HubSpot

Sign in with HubSpot, or paste a Service Key, so contacts, deals and pipeline flow into reporting and attribution.

I'm using the platform as a
All help topics

You can connect one CRM per account. Where it's offered, the HubSpot card shows two ways in:

  • Option 1 - Recommended: Connect with HubSpot. You sign in to HubSpot and approve access. Nothing to copy or paste, and the connection renews itself.
  • Option 2 - Use a Service Key instead. You create a key in HubSpot and paste it. See Using a Service Key below. It works exactly as before.

If your card shows only the Service Key form, signing in isn't available on your workspace yet - use a Service Key.

To connect by signing in:

  1. Open Setup, go to CRM and open the HubSpot card.
  2. Click Connect with HubSpot and sign in to HubSpot.
  3. If you have more than one HubSpot account, choose the one your business uses.
  4. Approve the access HubSpot lists (see What HubSpot asks you to approve below).
  5. You come back to Setup and the card finishes the connection - it says so while it works. When it reads Connected, your HubSpot figures fill in over the next few minutes.

For a client's HubSpot: open the client's Setup, go to CRM and open the HubSpot card, then click Connect with HubSpot. Whoever signs in must be allowed to install apps in the client's HubSpot account - usually the client's own HubSpot admin, so it is often easiest to send them the link to their Setup page. You come back to the client's Setup and the card finishes the connection.

Once connected, the card reads Connected by signing in with HubSpot, with Sign in again to switch to a different HubSpot account. Disconnect removes the connection here; the app stays installed in the client's HubSpot until they remove it under Connected Apps, which is worth telling a client who is leaving.

What HubSpot asks you to approve

HubSpot shows a list of what the app can see. Required: contacts, deals, the account's own details, the users assigned to records, and logged one-to-one emails - the same read access the Service Key below needs. Optional: creating and changing contacts, used only to send a new lead from your website chat or calls back into HubSpot. You can untick it and still connect.

"You're connecting an unverified app." Until the app is listed on HubSpot's marketplace, HubSpot shows this warning and asks you to type I accept the risk before connecting. It is HubSpot's standard notice for apps that have not been through its marketplace review, not a sign that anything is wrong with your account.

Using a Service Key

Create a Service Key in HubSpot -> Development -> Keys -> Service keys, add the read scopes below, paste the key (pat-...) into Option 2 and click Save & test.

  • The key starts with pat- and a region, e.g. pat-na1-... or pat-eu1-.... HubSpot now labels private apps as legacy; a Private App token you already have still works, but new connections should use a Service Key. A Developer API key (it starts with a region like eu1-..., with no pat-) is a different thing and will be rejected.
  • Add these read scopes: crm.objects.contacts.read (contacts, plus logged calls, texts and WhatsApp messages), crm.objects.deals.read (deals), crm.objects.owners.read (team member names) and sales-email-read (logged emails). A key missing one of these connects but returns gaps or a scope error - without the last three, the CRM tab's sales activity simply doesn't appear.
  • The portal ID is detected automatically - there's no separate ID field.

When signing in doesn't finish

"The install was cancelled in HubSpot. Start again when you're ready."

  • Why: you left or declined the HubSpot screen. Fix: click Connect with HubSpot again.

"The install took too long or couldn't be verified. Start again from this card."

  • Why: the sign-in was left open too long. Fix: start again from the card.

"The install couldn't be verified. Start again from this card, in the same browser."

  • Why: the sign-in finished in a different browser from the one it started in. Fix: start and finish it in the same browser.

"HubSpot approved the install but we couldn't finish it. Try again in a minute."

  • Why: HubSpot said yes but the last step failed. Fix: wait a minute and try again; if it keeps happening, use a Service Key (Option 2).

For token errors (rejected key, missing scopes), and what a connected CRM powers, see Connecting your CRM.