HubSpot integration

Vaam’s HubSpot integration keeps your prospects and contacts in sync, so your sales team works from one shared source. Once connected, Vaam matches prospects to existing HubSpot contacts, fills in missing details, and follows ownership and lifecycle rules so reps do not work the same contact at the same time.

Looking for which Vaam events you can use as workflow triggers in HubSpot? See HubSpot signals.

Connect Vaam to HubSpot

The HubSpot integration applies to one team. One HubSpot account connects to one Vaam team, and every team member uses the same connection. A team admin sets it up once for the whole team.

To connect:

1. Go to Settings → Integrations in Vaam.
2. Click HubSpot → Connect.
3. Sign in to HubSpot and choose the account you want to link.
4. Review the permissions Vaam requests and approve them.

Vaam asks for four permissions:

• Read and write contacts: match prospects to contacts, fill in missing information, and create new contacts when none exist.
• Read companies: identify the company a contact belongs to.
• Write timeline events: show activity on the contact’s HubSpot record.
• Read owners: let admins map Vaam users to the matching HubSpot owner.

Grant all four permissions. If you skip one, part of the integration stops working. For example, denying write access means Vaam cannot create new contacts or post timeline events. Denying owner access disables the prospect-blocking rules below.

Reconnecting

If HubSpot adds new permission scopes, or if your admin needs to refresh the connection, open Settings → Integrations → HubSpot and re-authorize from the same screen. You do not lose any data by reconnecting.

Disconnect

You can disconnect the integration at any time from Settings → Integrations → HubSpot → Disconnect. Vaam stops reading from and writing to HubSpot immediately. Existing HubSpot data stays untouched.

Automatic disconnects

Vaam disconnects the integration automatically if HubSpot returns repeated authentication failures. This can happen when a refresh token expires, the Vaam app is revoked in HubSpot, or the linked HubSpot account is deleted.

When this happens, no data is lost in HubSpot. Reconnect from Settings → Integrations → HubSpot to resume the integration.

What Vaam writes to HubSpot

Contacts

When you add a prospect to Vaam, Vaam looks for a matching HubSpot contact in this order:

1. Email address: the most reliable match.
2. LinkedIn profile URL: used when there’s no email match.
3. Full name: used as a last resort and only when nothing else fits.

If Vaam finds a match, it updates the existing contact with new information. It does not overwrite fields that already have values, so information your team has manually curated in HubSpot stays safe.

If Vaam finds no match, it creates a new contact when the connection has write permission. The new contact contains what Vaam knows about the prospect at that point: name, email, LinkedIn URL, company, and any other fields you’ve collected.

If Vaam finds more than one possible match, see Multiple contacts match a prospect under troubleshooting.

Companies

When someone watches a Vaam video without identifying themselves, Vaam can often identify the visitor’s company from their network domain. In those cases, Vaam can create or update a matching company record in HubSpot. Your team can see which accounts are engaging, even before Vaam knows a contact.

This is especially useful for outbound campaigns. A video view from an unknown viewer is often the first signal that an account is paying attention.

Account properties

For contacts and companies a Vaam user owns, Vaam writes these account-level properties for cohort filters and reporting:

• Account creation date
• Account language
• Onboarding status
• Subscription type
• Trial status
• Subscription end date
• UTM source (when applicable)

These properties update whenever the underlying value changes in Vaam.

What Vaam reads from HubSpot

• Vaam loads the list of owners so admins can map each Vaam user to the matching HubSpot owner. This mapping powers the prospect-blocking rules below.
• Vaam reads the lifecycle stage and contact owner on prospects for the prospect-blocking rules.
• Vaam performs contact lookups when you import prospects from a HubSpot list or view.

Prospect blocking rules

Configure prospect blocking in Settings → Integrations → HubSpot. It runs every time a rep adds a contact to a sequence, before any messages are sent. If a rule blocks the prospect, Vaam cancels the action and shows the reason to the rep.

Block contacts owned by other reps

When this is on, Vaam refuses to add a contact whose HubSpot owner is mapped to a different Vaam user. This prevents two reps from working the same contact at the same time.

For this rule to work, map every rep to their HubSpot owner in the integration settings.

Block by lifecycle stage

Pick the HubSpot lifecycle stages where outreach should not happen, such as customer or opportunity. Contacts in those stages cannot be added to a Vaam sequence.

You can combine both rules. They run together, and a prospect must pass every active rule before Vaam adds it to the sequence. If a prospect is blocked, the rep sees the reason on screen and can pick a different prospect, hand the contact off internally, or, if appropriate, change the lifecycle stage or owner in HubSpot first.

Sync timing

The integration runs in the background. You do not need to schedule it or press a manual sync button.

• Contact and company writes: Vaam writes them when you create or update a prospect, or when Vaam identifies an anonymous viewer by their company.
• Account property updates: Vaam writes them when the underlying value changes in Vaam, such as when a user’s subscription changes or onboarding completes.
• Timeline events: Vaam posts them immediately when the trigger occurs in Vaam. A short cooldown debounces rapid-fire updates, so you do not see duplicate writes for the same change.

The timeline of a sequence starts when Vaam links the prospect to a HubSpot contact. Sometimes the link arrives after you add the prospect to the sequence, for example when Vaam is still matching the contact. Then Vaam posts these events:

• Sequence Started appears with the time you added the prospect to the sequence.
• If the sequence is canceled when the link arrives, Sequence Started appears first, then Sequence Canceled.
• Steps that ran before the link do not appear on the timeline. Vaam does not post them later. Contact Vaam support if you need them.
• Steps that run after the link appear as usual.
• A sequence that finished before the link gets no timeline events.

If a write fails, for example, because HubSpot is temporarily unavailable, Vaam retries automatically.

Best practices

Use these practices to manage the integration:

• Map every Vaam user to a HubSpot owner. Without the mapping, the “block contacts owned by other reps” rule has nothing to compare against and will not protect your team from collisions.
• Agree on which lifecycle stages are off-limits for outreach before turning on the lifecycle block, so reps are not surprised when Vaam refuses to add prospects.
• Keep duplicate contacts under control in HubSpot. Vaam flags prospects with multiple matches for manual review, and a clean contact database keeps the queue short.
• Reconnect after HubSpot admin changes. If a HubSpot admin changes the scopes available to apps or rotates credentials, reconnecting from Vaam is the fastest fix.

Troubleshooting

Integration disconnected unexpectedly

See Automatic disconnects for the reasons.

Fix: reconnect from Settings → Integrations → HubSpot. No HubSpot data is lost.

Contact properties are missing

If account properties are not appearing on a contact or company:

• Confirm the Vaam user is the owner of that prospect or account in Vaam. Properties are only written for records owned by a Vaam user.
• Confirm the HubSpot owner mapping is set under Settings → Integrations → HubSpot.
• Confirm the HubSpot connection still has write permissions. If a HubSpot admin downgraded the app’s scopes, reconnect to restore them.

Vaam isn’t adding a prospect

If a rep cannot add a contact and Vaam shows a blocked-prospect message:

• Check the prospect-blocking rules under Settings → Integrations → HubSpot.
• Look at the contact’s HubSpot owner. If it is mapped to a different Vaam user and “block contacts owned by other reps” is on, the rule blocks the prospect.
• Look at the contact’s lifecycle stage. If it matches a blocked stage, the rule blocks the prospect.

Prospects aren’t syncing to HubSpot

• Confirm the HubSpot integration is connected under Settings → Integrations.
• Confirm the prospect has at least an email address or LinkedIn profile URL. Vaam needs one of them to match or create a contact.
• If the connection shows as disconnected, reconnect and retry.

Data isn’t updating in HubSpot

Vaam never overwrites a HubSpot field that already has a value. It only fills in blanks. To change an existing value in HubSpot, edit it directly in HubSpot.

Multiple contacts match a prospect

When Vaam finds more than one possible match, up to five candidates, it flags the prospect for manual review. Open the prospect in Vaam, pick the correct HubSpot contact, and Vaam links them. If more than five candidates match, Vaam does not link the prospect automatically. Clean up the duplicates in HubSpot or pick the right contact manually.