Oppy for HubSpot
Overview
In Oppy, a card is an account (one company, why it matters now, how to approach it). Leads are people at those accounts. HubSpot connects as an account overlay, not as a way to import prospects.
- Read HubSpot company context onto Oppy accounts: owner, lifecycle, last activity, open deals. If a lead already exists as a HubSpot contact, Oppy can show that match too.
- Sync an account to the HubSpot company matched by website domain — creating or updating that company if needed, then attaching a Why this account note and a link back to the Oppy account.
- Sync a lead only when that person already exists in HubSpot. Oppy never creates a HubSpot contact and never writes email, phone, or other identity fields onto a contact.
Writes are one-way (Oppy → HubSpot) for those company notes and company
fields. Separately, HubSpot deal and contact events feed back into Oppy as
account outcome badges (won, lost, stalled). Those events never
overwrite your HubSpot records.
People and emails stay in Oppy after a reveal. If a lead is not in HubSpot, there is no button that adds them there.
Prerequisites
Before installing, you need:
- An active Oppy account.
- Admin permissions in Oppy (Integrations is admin-only).
- Admin access to the target HubSpot portal to authorize the app.
- No other CRM connected. Oppy supports one CRM at a time — if Attio is connected, disconnect it first (Oppy shows: "Disconnect Attio first — one CRM at a time.").
Integration lifecycle
Connect HubSpot
→ authorize scopes in HubSpot
→ Oppy stores the portal connection
→ provisions an Oppy property group on companies
→ matches approved accounts to HubSpot companies by domain (background)
Approvals (Accounts)
→ pills and CRM strip from that company match
→ Sync writes a company note (and company upsert by domain)
→ lead-row Sync writes a note only if the person already exists
HubSpot events
→ deal stage / lifecycle / deletions update Oppy badges and match cache
Disconnect or revoked token
→ context and logging stop until you reconnect
1. Connect
- In the Oppy dashboard, open Integrations.
- Find HubSpot and click Connect with HubSpot.
- You are redirected to HubSpot to approve access, then returned to Oppy.
- The HubSpot card shows a Connected badge and your portal ID.
On connect, Oppy:
- Creates an Oppy property group on companies (Why this account, last log date, card URL).
- Starts a background account match: approved accounts with a company website are looked up in HubSpot by domain so pills can show before anyone opens an account.
There is no auto-sync-on-approval and no auto-push when you reveal a lead. Sync is always an explicit action (one account, or Sync all).
2. Use it on Approvals
Open Approvals. The Accounts view is your cards. Each account can show a HubSpot pill from the company domain:
| Pill | Meaning |
|---|---|
| In HubSpot | A company with that domain already exists in HubSpot. |
| In HubSpot · Active deal | Same, and there is an open deal on that company. |
| New to HubSpot | No company matched for that domain yet. Sync can create the company (not a person). |
The CRM strip on an open account is company-first: company owner, lifecycle, last activity, open deal count. If the HubSpot owner is not the person using Oppy, Oppy warns you. Sync does not change the HubSpot owner.
The Leads view is people at those accounts. HubSpot actions there apply to an existing contact only.
3. What “Sync” does
| Where | What HubSpot receives | What HubSpot does not receive |
|---|---|---|
| Account Sync in HubSpot | Company upsert by domain, Why this account note on the company, Oppy company properties, optional follow-up task on the company | New contacts, emails, phones |
| Lead Sync in HubSpot | Why this account note on that existing contact | Contact create, email/phone/property writes |
| Lead not in HubSpot | Nothing on a person | No Push / Add contact control |
View in HubSpot opens the company record after an account sync, or the contact record only when that lead already matched.
4. Sync all
Sync all in HubSpot on Approvals (Accounts) starts a server job. It keeps running if you leave the page, switch tabs, or refresh. A toast shows progress (for example 12 of 40 synced in HubSpot) with Cancel.
- Cancel is the only way to stop the job. The account already in flight still finishes; no new accounts start.
- Sync all syncs companies the same way as a single account Sync. It does not create HubSpot people.
If HubSpot rate-limits a write, Oppy queues it and retries. The UI may show that the log is queued until it succeeds.
5. Disconnect
Disconnect HubSpot in Integrations (or a HubSpot admin revoking the app) stops CRM context and logging until you connect again.
Permissions (OAuth scopes)
During authorization, Oppy requests:
- Contacts — Read (lookup people who already exist); write is used for notes on those existing records, not to create contacts or set email/phone.
- Companies — Read and write (match, create/update the company, company properties).
- Deals — Read (open-deal context and outcome webhooks).
- Owners — Read.
- Contact schemas — Write (legacy Oppy property group; overlay logging uses company properties).
HubSpot does not require separate notes or tasks scopes in this flow. Notes and company follow-up tasks use the object write scopes above.
What Oppy writes
Direction: Oppy → HubSpot for company upsert, company properties, and notes. HubSpot → Oppy is read-only context plus outcome badges.
Company — HubSpot companies (upsert by domain)
| Field | Source / rule |
|---|---|
domain | match key |
name | company name |
numberofemployees | if present |
oppy_signal_type | Oppy custom property (activity type on the account) |
oppy_trigger_text | Why this account |
oppy_last_push_date | date of last sync |
oppy_card_url | deep link to the Oppy account |
Oppy creates these custom company properties in an Oppy group in your portal when you connect.
Note on the company
- Body: the account’s Why this account text and a link back to Oppy.
- A new note is created each time you sync (notes accumulate).
- Owner on the HubSpot company is not overwritten.
Note on a contact (existing records only)
- Same Why this account body + account link.
- Logged only after Oppy matches a lead who is already in HubSpot.
- Email, phone, name, job title, and LinkedIn on the HubSpot contact are never written by Oppy.
Re-sync behavior
- Company — matched by domain and updated in place (no duplicate company).
- Contact — never created; note only if already matched.
- Note — a new note each sync.
What Oppy never writes to HubSpot
- New contacts.
- Email, phone, or other identity fields on contacts.
- Automatic logging when you approve an account or reveal a lead.
Deal outcomes (feedback loop)
When deals move stage or contacts change lifecycle in HubSpot, Oppy updates
matching accounts with outcome badges (won, lost, stalled). If a
company or contact is deleted in HubSpot, Oppy clears the cached match so
pills do not keep pointing at a missing record.
No extra setup is required — Oppy registers these webhooks when you connect.
Support & Troubleshooting
- Questions or issues: contact@oppyone.com
- If HubSpot rate-limits a sync, wait for the automatic retry queue, or check Sync health on Integrations (pending pushes, failed pushes in the last 24 hours). Use Retry failed pushes if failures appear.
- A toast that stays at 0 of N then disappears means the bulk job finished; refresh Approvals to see updated pills. Accounts that stay New to HubSpot did not get a successful company sync (for example missing website).
- Disconnect any time via Disconnect HubSpot. Reconnect with Connect with HubSpot if access was revoked.