Skip to main content
Connect HubSpot with a Private App token so you can push leads there as contacts, with a note and their email history attached.
Where
Integrations→Integrations→Apps & CRM
Your role needs
Read access to Apps & CRM read-integrations. Admin, Member and Viewer have it by default.
To create or change
create-integrations to add one, update-integrations to change one, on top of the permission above.
If you cannot find this in your sidebar, your workspace may have a custom menu configuration. Contact support and we will check it for you.

​
Before you begin

  • A HubSpot account where you can create a Private App and give it read and write access to CRM contacts and companies.
  • Nothing has to be set up on our side. The token is your own credential, so this connects the same way on every workspace.

​
Steps

1

Open the HubSpot connect dialog

Go to , choose Add integration, then choose HubSpot from the list. The dialog opens with a walkthrough for creating the token, and an empty field to paste it into underneath.
2

Create a Private App token in HubSpot

The panel’s six instructions walk you through HubSpot’s own settings:
  1. Log in to your HubSpot account.
  2. Go to “Development → Legacy apps” in the left sidebar.
  3. Click “Create legacy app” and select “Private”.
  4. Give it a name (the panel suggests “Email Integration”) and, if you want, a description.
  5. Click the “Scopes” tab, then “Add new scope”, and enable “CRM > Contacts (Read/Write)” and “CRM > Companies (Read/Write)”.
  6. Click “Create app” and copy the access token it shows.
The panel also links straight to HubSpot’s Private Apps page and to its documentation.Only a token starting with pat- is accepted. The dialog checks that prefix itself and rejects anything else without sending it anywhere.
3

Paste the token and connect

Paste the token into the field and choose Connect. The token is used to read a contact from HubSpot, and if that works the dialog shows which HubSpot account it connected to.The name next to “Connected to:” (1) is read from HubSpot’s own account details: the account’s company name, or its portal name. If HubSpot returns neither, the connection is named HubSpot Account.
A workspace only ever holds one HubSpot connection. Connecting again with a different token replaces the existing one rather than adding a second.

​
What happens next

The dialog shows HubSpot Connected! with the account name from the step above. Choose Done, and the HubSpot card on shows a Connected chip and that same name.
Connecting HubSpot does not push any leads by itself. Nothing moves until you turn on Auto-push analyzed leads on the card, choose Push to CRM on a lead’s own page, or add a Send to CRM step to a workflow. See Auto-push analyzed leads and stage filters and Push a lead to your CRM manually. Only one CRM ever owns a lead. If Salesforce, Odoo, Kommo or HeyReach already created a record for it, the automatic push skips it without telling you, and a Send to CRM step reports it as sent while creating nothing. A manual push from the lead’s page is the one route that still goes through. Once a lead is pushed, it lands in HubSpot as a contact: its name split into first and last, its most recently added email and phone number, job title, LinkedIn URL, and its company’s name, website and industry, leaving out whichever of those it does not have. A note is attached carrying the lead’s LinkedIn URL, the lead’s own description, the company’s description and summary, and the company’s saved links (again, whichever of those exist). One email engagement is created for each message in the lead’s email thread, skipping only warm-up traffic. The note and the engagements are attached by separate calls once the contact exists: if either fails, the contact is still created and nothing in the app tells you. Field mapping reference per CRM has the complete, field-by-field version.

​
Troubleshooting

The full message reads Invalid API key format. HubSpot Private App tokens start with "pat-". The dialog checks the prefix itself, so nothing was sent to HubSpot. Copy the token straight from HubSpot’s Private Apps page (the dialog links to it) rather than retyping it.
The full message reads Invalid HubSpot API key. Please ensure you have the correct Private App access token with CRM permissions. The token was sent to HubSpot and the read it was checked with failed, so the connection was refused and nothing was saved. Open the private app in HubSpot, check it still carries CRM > Contacts and CRM > Companies with read and write, and paste a fresh token if it was regenerated.
Connecting only makes HubSpot available as a destination. It doesn’t push anything on its own. Check whether Auto-push analyzed leads is on for this card, and see Auto-push analyzed leads and stage filters for every reason a push can be silently skipped. A contact with no note or no email history is a different, narrower case: those are attached separately from the contact itself, and a failure attaching either one is never shown in the app.

Auto-push analyzed leads and stage filters

What triggers an automatic push, which stages it fires on, and every reason a lead is silently skipped.

Field mapping reference per CRM

What object each connector creates, which lead fields land where, and what happens to your email history.

Push a lead to your CRM manually

Send one lead from its own page, and read the badge it leaves behind once it’s synced.