Step 1: Setup (one-time)
In HubSpot, go to Settings → Integrations → Legacy Apps. (This section was recently renamed from "Private Apps" — same feature, just relabeled. You'll need super admin access.)
Select Create → Private, name it (e.g., "OuterSignal"), and go to the Scopes tab.
Name your integration and provide a description.
Add new scopes and search “contact”. Grant the scopes needed to read and write contact properties crm.objects.contacts.read and crm.objects.contacts.write.
Select Create app, confirm, then go to the Auth tab and select Show token to reveal your access token. Copy it.
While you're in HubSpot, grab your portal ID (also called Hub ID) — it's in the account dropdown in the top-right corner next to your account name, or in the URL of any HubSpot page (the number after /app.hubspot.com/.../).
In OuterSignal, go to Settings → Integrations → HubSpot and select Connect.
A window opens asking for your HubSpot access token and portal ID — enter both and select Connect.
The integration card flips to Connected.
You only need to do this once. You won't be asked for these credentials again — every Playbook that uses HubSpot pulls them from here automatically.
Step 2: Creating and finding your HubSpot properties
Before you can map a field in a Playbook, the property has to already exist in HubSpot — OuterSignal writes to existing properties, it doesn't create new ones. If the property you want isn't there yet, create it first:
In HubSpot, click the settings icon in the top navigation bar.
In the left sidebar, go to Data Management → Properties.
Set the object type to Contact properties, then click Create property in the upper right.
Enter a Property Label — this is the name you'll enter later when mapping the field in your Playbook.
Choose a field type. Single-line text works for most OuterSignal values like persona name; use Number for numeric scores.
Leave "Make this a smart property" unchecked — that's HubSpot's Data Agent feature for auto-researching a value, and it'll conflict with OuterSignal writing to the same field.
Leave "Require unique values for this property" unchecked — most OuterSignal fields (persona, signal score) are shared across many contacts by design, so enabling this will cause the sync to fail.
Click through the remaining setup and select Create.
Once the property exists, you're ready to map it in a Playbook (see Step 3).
Confirming it worked:
Once the Playbook has run, go to Settings → Properties → Contact properties in HubSpot and search for the property name to confirm it's receiving data. To check an individual contact, open their record and look in the About section — any property the Playbook is syncing will show its current value there.
If a property you mapped doesn't appear at all, it means it was never created in HubSpot to begin with — go through the steps above first.
Step 3: Using it in a Playbook
In OuterSignal, go to Playbooks → Create Playbook and pick the segment you want to act on.
Select Add an Action, then choose the HubSpot action.
Configure the action by mapping OuterSignal fields to HubSpot contact properties. Email is required to map the contact to the Hubspot profile.
Select Add Action → Review & Create → Create Playbook.
The email mapping is mandatory. HubSpot contacts are matched on email address only — if you leave that mapping out, the action will fail outright rather than partially syncing. Every other field mapping is optional, but email has to be there.
When a Playbook runs, it updates existing HubSpot contacts that match on email — it does not create new contacts or duplicate existing ones.
FAQ
Where do I enter my access token and portal ID? Always in Settings → Integrations → HubSpot — never inside a Playbook. The Playbook builder doesn't have fields for either.
Why did my Playbook action fail? The most common cause is a missing email mapping — it's required for every HubSpot action, since that's how contacts are matched. Double-check it's included before troubleshooting anything else.
Will this create duplicate contacts in HubSpot? No. The integration updates existing contacts matched by email; it doesn't create new ones.
Private app or OAuth — which should I use? Private apps are the right choice for connecting your own single HubSpot portal, which is what this integration does. OAuth is only necessary if you're building an app meant to be installed across multiple HubSpot accounts.