What is FlowRouter
FlowRouter is a visual lead routing platform built specifically for HubSpot. It lets revenue operations teams design routing logic with a drag-and-drop canvas — territory rules, round-robin pools, account matching, SLA enforcement, and more — then deploy that logic to automatically assign incoming leads, companies, and deals to the right rep in HubSpot in real time.
FlowRouter is a standalone web application at app.flowrouter.io with two HubSpot surfaces that put routing information in front of reps where they already work:
- An App Home page inside HubSpot that shows routing activity, errors, and quick links
- Record cards on contact, company, and deal pages that display the assigned owner and routing history for that record
Routing flows themselves are built and managed in the FlowRouter web app, not inside HubSpot.
Before you install
You will need:
- A HubSpot account with admin permissions (required to authorize app installation)
- At least one active HubSpot user who will receive routed leads
- A sales or marketing hub subscription (Free tier works for basic testing, Starter or higher recommended for production use)
Optional but recommended:
- HubSpot teams and owners configured — FlowRouter routes to owners that already exist in your HubSpot Users settings
- A form or lifecycle stage you'd like to use as a routing trigger
Step 1 — Install the app
- Go to the FlowRouter listing on the HubSpot Marketplace.
- Click Install app.
- HubSpot will show you a list of permissions (scopes) the app is requesting. Review them (see "What permissions FlowRouter requests" below for an explanation of each) and click Connect app.
- You'll be redirected to FlowRouter at
app.flowrouter.ioto complete onboarding.
The first time you install, FlowRouter creates a new workspace tied to your HubSpot portal ID. If multiple admins from the same portal install FlowRouter, they'll all land in the same workspace.
Step 2 — Sign in and complete onboarding
- After the HubSpot OAuth flow completes, FlowRouter will sign you in automatically.
- The first-run setup will:
- Import your HubSpot users as potential routing targets
- Sync your HubSpot companies and contacts for lead-to-account matching
- Discover your HubSpot properties so you can reference them in condition and routing rules
- This initial sync takes 2–5 minutes depending on the size of your CRM. You can continue configuring while it runs.
Step 3 — Build your first flow
Flows are built in the web app, not inside HubSpot.
- In FlowRouter, go to Flows → New flow.
- Choose an object type: Contact, Company, or Deal.
- Use the drag-and-drop canvas to add nodes:
- Start with a Trigger node that fires on contact creation, form submission, property change, or deal stage change
- Add Match, Condition, Route, SLA, or Action nodes to define your logic
- Every flow should have at least one Route node that assigns an owner
- Click Validate to check your flow for errors.
- Click Deploy to make the flow live.
Only one flow per object type can be active at a time. Deploying a new flow automatically retires the previous one.
For a detailed walkthrough of each node type, see the Flow Builder documentation.
Step 4 — Verify it's working
- Trigger an event in HubSpot that matches your flow's trigger (e.g. submit the form, create a contact, change a property).
- In FlowRouter, open the Audit Log — you should see the record appear within a few seconds with the assigned owner and the full decision path.
- In HubSpot, open the contact record — you should see FlowRouter's App Card showing the routing history.
What permissions FlowRouter requests
FlowRouter uses OAuth only — no API keys, no tokens pasted into config files. When you install, HubSpot asks you to approve a specific list of permissions. Here's what each one is for:
Required scopes
| Scope | Why FlowRouter needs it |
|---|---|
oauth | The authentication flow itself |
crm.objects.contacts.read | Read contact properties to evaluate routing conditions (e.g. lifecyclestage, lead source) |
crm.objects.contacts.write | Set the hubspot_owner_id when a contact is routed to a rep — this is how assignment actually happens |
crm.objects.companies.read | Read company properties for account matching and territory routing |
crm.objects.deals.read | Read deal properties to route deals based on stage, amount, or pipeline |
crm.objects.deals.write | Set the hubspot_owner_id on deals when routed |
crm.objects.owners.read | Read the list of HubSpot owners so FlowRouter knows who's eligible to receive assignments |
crm.objects.users.read | Read HubSpot user settings like working hours and time zone — used to skip reps who are off-hours |
crm.schemas.contacts.read | Discover the custom properties defined on your contacts so you can reference them in flows |
crm.schemas.companies.read | Same, for companies |
crm.schemas.deals.read | Same, for deals |
Optional scopes
These unlock additional features but aren't required for core routing. You can decline them during install and FlowRouter will still work — just with those features disabled.
| Scope | Feature it unlocks |
|---|---|
forms | Trigger flows from specific HubSpot forms. Without this, form-submission triggers won't work but you can still route on contact creation. |
automation.sequences.read | Discover your HubSpot sequences so you can reference them in flow actions |
automation.sequences.enrollments.write | The Sequence Enrollment node — automatically enroll contacts in a HubSpot sequence after routing |
sales-email-read | The first-response tracking feature — FlowRouter detects when the assigned rep first replies to measure response time against SLA |
Data FlowRouter stores
When FlowRouter reads data from HubSpot, it caches a minimal subset in its own database to make routing decisions fast:
- Contacts, companies, deals: ID, name, email, owner, the properties referenced by your active flow, and the routing history
- Users and owners: ID, name, email, team, working hours
- Forms and sequences: ID and name only (for dropdowns in the flow builder)
FlowRouter does not store email content, call recordings, notes, engagement bodies, or any sensitive business data beyond what your flow's conditions reference.
All data is encrypted at rest, access is scoped to your workspace (row-level security), and transit is TLS-only.
Uninstalling and disconnecting
You can disconnect FlowRouter from HubSpot two ways:
From HubSpot
- Go to Settings → Integrations → Connected Apps in HubSpot
- Find FlowRouter and click Uninstall
This revokes FlowRouter's OAuth token immediately. All further webhook deliveries from HubSpot to FlowRouter stop.
From FlowRouter
- In the FlowRouter web app, go to Settings → Integrations → HubSpot
- Click Disconnect
This revokes the token on HubSpot's side and also tears down the FlowRouter workspace's sync state.
What happens to your data
When you uninstall or disconnect:
- In HubSpot: nothing changes. Contact owners, deal owners, and any properties FlowRouter wrote to remain as they are. HubSpot is the system of record.
- In FlowRouter: your routing flows and audit log are retained for 30 days in case you reconnect and want to restore them. After 30 days, the workspace is deleted along with all cached HubSpot data (contacts, companies, deals, users, owners, audit log, flow definitions).
If you want your data deleted immediately instead of waiting 30 days, email support@flowrouter.io from the email address associated with your workspace and we'll process the deletion within 3 business days.
Troubleshooting
"OAuth callback failed" after clicking Install
Check that your HubSpot account has admin permissions. Only HubSpot admins can install third-party apps. If you're an admin and still seeing this, email support.
Flow deploys successfully but nothing is routing
Most common causes:
- The flow's trigger doesn't match the event you're expecting. A "Contact created" trigger won't fire on property changes — you need a "Property changed" trigger for that.
- The required scopes weren't granted during install. Re-install and accept all required scopes.
- The flow has a validation error that prevents deployment. Click Validate in the flow builder to see what's flagged.
- Working hours rules are filtering out every eligible rep. If your routing runs at 2 AM and no reps are in-hours, the flow either waits or falls back (depending on your config).
The Audit Log shows "Stopped" on every run
Stopped is the intentional outcome when a flow branch ends without assigning an owner — usually because a Stop node was reached or a condition disqualified the lead. It is not an error. If you expected the lead to be routed, check the decision path in the audit log detail to see which branch was taken and why.
Record cards show "FlowRouter not connected"
This usually means the OAuth token was revoked or expired. Go to Settings → Integrations → HubSpot in FlowRouter and click Reconnect.
Something else
Email support@flowrouter.io with your HubSpot portal ID (visible in the bottom-left of the FlowRouter sidebar) and a description of what you're seeing. We typically respond within one business day.
Accessibility, privacy, and GDPR
- Accessibility: FlowRouter is built with keyboard navigation support and ARIA labels throughout. If you encounter an accessibility issue, please contact support — we treat accessibility bugs as first-class issues.
- Privacy: See the FlowRouter Privacy Policy for the full statement on how we handle your data.
- GDPR and data processing: FlowRouter acts as a processor of your HubSpot data. We sign Data Processing Agreements with customers on request. Email support@flowrouter.io to request a DPA.
- Data residency: All FlowRouter infrastructure and data is hosted in the United States.
- Subprocessors: A current list of subprocessors is available in the Privacy Policy.
Getting help
- Documentation: www.flowrouter.io/docs
- Support email: support@flowrouter.io
- Status page and changelog: available in-app under Settings