Welcome to Lead Router

Lead Router is a self-hosted lead routing engine for Salesforce. Deploy it to your own VPS with a single CLI command and gain full control over how Leads, Contacts, and Accounts are assigned to your team -- all without your data leaving your infrastructure.

Architecture

Lead Router runs as a Docker Compose stack on your server. When Salesforce records are created or updated, Apex triggers fire and send the record to the routing engine, which evaluates your rules and updates the owner in real time.

What you'll need

Step 1: VPS & DNS Setup

Provision a server and point two domain names at it.

Provision a VPS

Create a Linux server with any cloud provider. Recommended specs:

Popular options: DigitalOcean ($12/mo), Hetzner ($5/mo), Linode ($12/mo), AWS Lightsail ($10/mo).

Create DNS A Records

In your DNS provider, create two A records pointing to your VPS IP address:

New to DNS?

An A record maps a domain name to an IP address. When someone visits app.acme.com, their browser looks up the A record to find the server's IP.

After adding the records, it can take 5-30 minutes for DNS to propagate. You can check propagation with dig app.acme.com from your terminal.

The CLI will automatically provision SSL certificates via Let's Encrypt once DNS is pointing correctly, so you don't need to worry about HTTPS configuration.

Step 2: Salesforce Connected App

Create an OAuth Connected App so Lead Router can securely access your org.

Step-by-step

1. In Salesforce, go to Setup → search "App Manager" → click New Connected App
2. Fill in the basic info:
   - Connected App Name: Lead Router
   - API Name: Lead_Router (auto-filled)
   - Contact Email: your email
3. Under API (Enable OAuth Settings), check "Enable OAuth Settings"
4. Set the Callback URL to:
   https://app.acme.com/api/auth/sfdc/callback
   Replace app.acme.com with your actual app domain
5. Add these OAuth Scopes:
   - Access your basic information (api)
   - Perform requests at any time (refresh_token, offline_access)
6. Check "Require Secret for Web Server Flow"
7. Click Save, then wait ~2 minutes for Salesforce to register the app
8. Click "Manage Consumer Details" → verify your identity → copy the Consumer Key and Consumer Secret

What is a Connected App?

A Connected App is Salesforce's way of allowing external applications to authenticate via OAuth 2.0. It provides a Consumer Key (Client ID) and Consumer Secret that Lead Router uses to securely obtain access tokens for your org.

Your credentials are stored exclusively on your server -- Lead Router never sends them to any third party.

Step 3: Run the CLI

One command deploys the entire stack to your server.

Run the installer

Open a terminal on your local machine (not the VPS) and run:

Requires Node.js 20+. The CLI runs on your machine and connects to the VPS via SSH -- nothing is installed locally.

CLI prompts

The wizard will ask for the following information:

lead-routing

  The CLI will SSH into your server to deploy the full stack.
  You will need:
    - Server hostname or IP address
    - SSH password for your server (root access)
    - A fresh Linux VPS -- Docker installed automatically

-- Server connection -----------------------------

? Server hostname or IP address
  165.22.100.50  or  vps.acme.com
  > 165.22.100.50

? SSH password for root@165.22.100.50
  > ************

-- App configuration -----------------------------

? App URL (public URL where the web app will be accessible)
  https://routing.acme.com
  > https://app.acme.com

? Engine URL (public URL Salesforce will use to route leads)
  https://engine.acme.com  or  https://acme.com:3001
  > https://api.acme.com

-- Salesforce Connected App setup -------------------

? Consumer Key (labelled "Client ID" in newer orgs)
  > 3MVG9dAEux2v1sLt...

? Consumer Secret (labelled "Client Secret" in newer orgs)
  > ****************

-- Admin Account ---------------------------------

? Admin email address
  > admin@acme.com

? Admin password (min 8 characters)
  > **********

What happens next

The CLI will automatically perform these steps on your VPS:

✔ Node.js v20+ found
✔ Connected to 165.22.100.50 via SSH
✔ Docker detected on remote server
✔ Config files uploaded to ~/lead-routing

◇ Pulling Docker images on server (this may take a few minutes)...
✔ Docker images pulled

◇ Starting services...
✔ Services started (5 containers)

◇ Running database migrations...
✔ Database migrated and seeded

◇ Waiting for health checks...
✔ Web app -- https://app.acme.com
✔ Engine  -- https://api.acme.com

◇ Deploying Salesforce package (this may take ~2 min)...
✔ Package deployed (14 components)
✔ Permission set assigned

✔ Lead Router is live!
  Dashboard: https://app.acme.com
  Login with: admin@acme.com

Services deployed

Step 4: Onboarding Wizard

Connect your Salesforce org and activate triggers -- all from the Salesforce UI.

Open the wizard

1. In Salesforce, click the App Launcher (grid icon, top-left)
2. Search for "Lead Router Setup" and click on it
3. The onboarding wizard will open inside Salesforce

Complete all 4 wizard steps

1. Step 1 -- Connect: Click "Connect to Lead Router" → authorize the OAuth popup → wait for the green checkmark (~5 seconds)
2. Step 2 -- Activate Triggers: Click Activate to enable Lead insert/update triggers. This tells Salesforce to send records to the engine whenever they change.
3. Step 3 -- Sync Fields: Click Sync Fields to index your Lead field schema. This enables the rule builder to show your custom fields.
4. Step 4 -- Test: Click Send Test to fire a test routing event. "Test successful" or "No matching rule" are both valid -- it confirms the connection works.

Step 5: Connect Salesforce

Manage your Salesforce connection and package deployment from the web dashboard.

Salesforce Integration Hub

Navigate to Integrations in the sidebar. This page gives you full control over your Salesforce connection without needing the CLI.

What you can do

• Deploy / Redeploy Package -- Push the latest Apex triggers, classes, and components to Salesforce. No CLI required.
• Sync Fields -- Refresh the field schema from Salesforce so the condition builder shows current fields and picklist values.
• Enable Objects -- Choose which objects (Lead, Contact, Account) are routable.
• View Status -- Check deployment status, last sync timestamp, and connection health at a glance.
• Disconnect -- Revoke the OAuth connection and remove stored credentials.

Step 6: Sync Fields

Ensure the route builder has access to your Salesforce field schema.

How field sync works

When you click Sync Fields (either in the onboarding wizard or the Integrations page), Lead Router reads the metadata for all enabled objects (Lead, Contact, Account) and imports:

• Field API names, labels, and data types
• Picklist values for dropdowns in the condition builder
• Required/optional status and relationship references

This is what powers the dropdowns in the route builder's condition editor. If you add new custom fields in Salesforce, re-sync to make them available.

Step 7: Deploy Triggers

Apex triggers are the bridge between Salesforce and the routing engine.

What gets deployed

The Salesforce package includes:

• Apex Triggers -- LeadTrigger, ContactTrigger, AccountTrigger -- fire on insert/update and send record data to the engine.
• Apex Classes -- RoutingEngineCallout (HTTP callout), RoutingPayloadBuilder (JSON serialization), CriteriaEvaluator (pre-callout filtering).
• Custom Settings -- Routing_Settings__c stores the engine endpoint URL, webhook secret, and toggle flags for each object/event.
• Custom Objects -- Route_Criteria__c stores trigger criteria synced from the web app for pre-callout filtering.
• Permission Set -- LeadRouterAdmin grants access to the setup app, custom objects, and fields.

Deploying from the web dashboard

Go to Integrations → click Deploy Package. The deployment uses the Salesforce Metadata API and typically completes in 1-2 minutes.

Deploying from the CLI

Run this from the same directory where you ran init. It reads the saved config from lead-routing.json.

Step 8: Complete Setup

Verify everything is working end-to-end before building your first route.

Checklist

• Web dashboard loads at your app URL with HTTPS
• You can log in with the admin email and password from CLI init
• Integrations page shows Salesforce as "Connected"
• Package shows as "Deployed" with all components
• Field sync shows your Lead fields
• "Lead Router Setup" appears in Salesforce App Launcher

Step 9: License Users

Control which Salesforce users can receive routed records.

Why license users?

Only licensed users are eligible to receive routed records. This lets you control exactly which reps participate in routing -- an unlicensed user will never be assigned a lead, even if they're in a team.

Sync users from Salesforce

1. In the web dashboard, go to License Users in the sidebar
2. Click the "License Users" button in the top-right
3. Choose a licensing strategy:

Four strategies are available:

• All Users -- License every user from Salesforce
• Individual Users -- Pick specific users to license
• By Role -- License all users with selected Salesforce roles
• By Profile -- License all users with selected Salesforce profiles

Managing the user table

After syncing, you'll see a table of all imported users. Toggle the switch to license or de-license individual users. Use the search bar and filters to find specific users. Select multiple users for bulk actions.

Step 10: Create Teams

Create pools of reps for lead distribution. Choose between equal round robin (every rep gets the same share) or weighted round robin (assign proportional shares per rep).

Create a team

1. In the sidebar, click Teams
2. Click "New Team"
3. Enter a team name (e.g. "SDR West") and optional description
4. Click Create

Add members

1. Click Manage on the team card to open the detail page
2. Click "Add Members" and choose a method:
   - Individual Users -- search and select specific licensed users
   - By Role -- add all users with a specific Salesforce role
   - By Profile -- add all users with a specific Salesforce profile

Team controls

• Active / Paused -- Toggle a member's status. Paused members are skipped during assignment (e.g. when someone is on PTO).
• Reset Pointer -- Resets the rotation back to the first member. Useful after adding or removing members.
• Share % -- Shows each member's share of total assignments. An even distribution means fair routing.

Distribution types

Each team supports two distribution modes, selectable on the team detail page:

• Equal Round Robin (default) -- Every active member receives leads in strict sequential order, one each in turn. All members get an equal share.
• Weighted Round Robin -- Assign a weight to each member to control what proportion of leads they receive. For example, weights of 40/40/20 mean the first two reps each get 40% and the third gets 20%.

In weighted mode, use the sliders to adjust each member's weight. Toggle between Percentage (must sum to 100) and Points (must sum to 10) modes. Use the Equalize button to reset all weights to equal.

Step 11: Create Routes

Set up routing rules in the web dashboard.

Create a rule

1. Log in to the web dashboard at your app URL with the admin email and password you set during CLI init
2. Navigate to Routing Rules in the sidebar
3. Click New Rule
4. Give it a name (e.g. "Enterprise Inbound") and select Lead as the object type
5. Set the trigger to Insert (fires when new Leads are created)
6. Click Edit Flow to open the visual route builder

Example: Route by company size

In the flow builder, create a simple rule: any Lead where Company contains "Enterprise" gets assigned to the Enterprise SDR team via round robin.

Step 12: Route Builder Canvas

Build complex routing flows visually with a drag-and-drop canvas -- like n8n or Zapier, but for lead routing.

The visual canvas

When you click Edit Flow on any rule, you enter the freeform canvas. Drag steps from the right sidebar onto the canvas to build your routing flow.

Step types

Canvas controls

• Zoom -- Scroll wheel or use the +/- buttons in the toolbar (25%-200%)
• Pan -- Hold Space and drag, or use the canvas background
• Fit to view -- Click the maximize icon to center all nodes
• Drag steps -- Drag from the Step Registry panel on the right onto the canvas
• Click to configure -- Click any node to open its config sheet with full options

English View

At the top of the route builder, you'll see two tabs: Canvas and English. Click English to switch to the natural language review that shows your routing logic as plain English sentences.

The English view detects common mistakes and displays warnings:

Trigger Conditions

Trigger conditions let you define criteria that records must meet before the routing engine is called. This filtering happens inside Salesforce's Apex trigger, so records that don't match never leave your org.

1. Open a rule and click on the Trigger step in the canvas
2. In the Trigger config sheet, scroll down to Trigger Criteria
3. Add conditions using the condition builder -- same UI as path conditions
4. Conditions within a group are joined with AND. Multiple groups are joined with OR.
5. Save the rule. Conditions are automatically synced to Salesforce as Route_Criteria__c records.

Fuzzy & AI Matching

When configuring the Match step, you can enable company name matching with one of three modes:

• Strict -- Exact normalized match only. "Acme Inc" = "acme"
• Fuzzy -- Levenshtein, Soundex, Double Metaphone + abbreviation dictionary (~85 common mappings)
• AI Smart -- LLM-powered semantic matching with 3-layer alias cache (in-memory, Redis, Postgres)

How fuzzy matching works

The fuzzy matcher runs a cascading resolution chain -- it tries the fastest method first and only falls back to more expensive checks if needed:

1. Exact normalized -- Strip suffixes (Inc, LLC, Corp, Ltd, GmbH), lowercase, remove punctuation
2. Abbreviation dictionary -- ~85 common mappings (IBM → International Business Machines, HP → Hewlett Packard)
3. Levenshtein similarity -- Character-level edit distance, threshold >= 0.85
4. Soundex match -- 4-character phonetic codes
5. Double Metaphone -- Primary + alternate phonetic encodings

AI Smart mode

When AI Smart is selected, the system adds an additional resolution step after fuzzy matching fails:

1. Alias cache check -- L1 in-memory (1,000 entries, 1hr TTL) → L2 Redis (24hr TTL) → L3 Postgres (permanent)
2. AI provider call -- Sends company name pair to your configured LLM (Claude, OpenAI, Gemini, or custom endpoint)
3. Cache result -- Writes the AI's decision to all cache layers to avoid repeated calls

Condition operators

Step 13: Verify It Works

Create a test Lead and watch it get routed in real time.

End-to-end test

1. In Salesforce, create a new Lead that matches your rule (e.g. Company = "Enterprise Corp")
2. Within 2-3 seconds, the Lead's Owner should update to the assigned user
3. In the web dashboard, go to Activity to see the routing event logged

What to check

Step 14: Activity & Analytics

Monitor every routing decision in real time.

Routing History

The Activity page shows every record the engine has processed. Navigate to Activity in the sidebar. Use filters to narrow by object type, status, rule, team, or specific assignee.

Status types

Activity tabs

• Routing History -- The main event log with full details per record
• Assignment Stats -- Aggregated statistics on routing volume, success rates, and assignee distribution
• Failed Routings -- Filtered view showing only failed events for quick debugging
• Audit Log -- System-level log of configuration changes (rule edits, user licensing, team modifications)

Analytics Dashboard

Navigate to Analytics in the sidebar for a dedicated reporting dashboard with four tabs:

Step 15: AI Assistant PRO

Chat with an AI that understands your routing data -- get optimization suggestions, debug issues, and query activity.

What it does

The AI Assistant is a conversational interface that has access to your routing rules, activity history, team configuration, and analytics. It can:

• Answer questions about your routing setup -- "Which rule handles APAC leads?"
• Suggest optimizations -- "How can I improve my conversion rate?"
• Debug routing failures -- "Why did this lead go to the wrong team?"
• Generate reports -- "Show me routing volume by team this week"
• Explain rules in plain English -- "Walk me through the Enterprise Inbound rule"

Configure your AI provider

Navigate to Settings → AI to connect your LLM provider. Bring your own API key (BYOK) -- your data stays on your server.

Supported providers:

• Claude (Anthropic) -- Recommended
• OpenAI -- GPT-4o, o1
• Gemini -- Google AI
• Custom -- Any OpenAI-compatible endpoint

Setup steps

1. Go to Settings → AI in the sidebar
2. Click Connect on your preferred provider card
3. Enter your API key and select a model (e.g. claude-sonnet-4-5-20250514, gpt-4o)
4. For Custom endpoints: provide a base URL and optional custom headers for auth
5. Click Save -- the key is encrypted and stored server-side
6. Navigate to AI Assistant in the sidebar and start chatting

How To Videos

Video walkthroughs to help you get the most out of Lead Router.

Frequently Asked Questions

Troubleshooting

Common issues and how to resolve them.

Health check times out during CLI init

Cause: DNS hasn't propagated yet, or ports 80/443 are blocked.

Fix:

• Verify DNS: dig app.acme.com should return your VPS IP
• Check firewall: ufw status (Ubuntu) -- ports 80 and 443 must be open
• Check Docker: SSH into VPS and run docker ps -- all 5 containers should be running
• Let's Encrypt rate limit: if you've provisioned too many certificates for the same domain, wait 1 hour

redirect_uri_mismatch error during Salesforce login

Cause: The callback URL in your Connected App doesn't match the one Lead Router is using.

Fix: In Salesforce Setup → App Manager → your Connected App → Edit, verify the Callback URL is exactly:

https://app.acme.com/api/auth/sfdc/callback

Replace app.acme.com with your actual app domain. No trailing slash.

Records are not being routed

Check these in order:

1. Triggers active? -- Open "Lead Router Setup" in Salesforce App Launcher and check Step 2 shows triggers are activated
2. Rule matches? -- Ensure your rule conditions match the Lead field values. Check the Activity page for "Unmatched" entries.
3. Custom Settings configured? -- In Salesforce Setup, search "Custom Settings" → "Routing Settings" → Manage. The Engine Endpoint should be your API URL.
4. Engine reachable? -- Run curl https://api.acme.com/health from any machine. Should return {"status":"ok"}

"Lead Router Setup" doesn't appear in App Launcher

Cause: The LeadRouterAdmin permission set isn't assigned to your user.

Fix: Salesforce Setup → Users → Permission Sets → Lead Router Admin → Manage Assignments → Add your user.

Viewing server logs

SSH into your VPS and use Docker logs:

# Web app logs
docker logs lead-routing-web-1 --tail 100 -f

# Engine logs
docker logs lead-routing-engine-1 --tail 100 -f

# All services
docker compose -f ~/lead-routing/docker-compose.yml logs --tail 50 -f

Redeploying the Salesforce package

If you need to redeploy the Apex triggers and components:

This re-deploys all Apex classes, triggers, and configurations to your Salesforce org. Run this from the same directory where you ran init.

Updating Lead Router to a new version

This pulls the latest images and recreates the containers with zero downtime.

Fuzzy matching not working -- exact matches only

Cause: The match mode is set to "Strict" (default) instead of "Fuzzy" or "AI Smart".

Fix:

• Open the rule in the Route Builder and click the Match step
• In the config sheet, look for Company Match Mode
• Switch from "Strict" to "Fuzzy" or "AI Smart"
• Save the rule -- fuzzy matching takes effect immediately on the next routing event

If using AI Smart mode, also verify your API key is configured in Settings → AI and the provider is reachable from your server.

AI Assistant not responding or returning errors

Check these in order:

1. API key valid? -- Go to Settings → AI and verify the key shows "Connected". Try disconnecting and reconnecting.
2. Provider reachable? -- SSH into your VPS and test: curl https://api.anthropic.com/v1/messages (or your provider's API). Firewall rules may block outbound HTTPS.
3. Rate limited? -- Check the engine logs for 429 responses. The AI assistant respects provider rate limits and will queue retries.
4. Custom endpoint? -- Verify the base URL includes the correct path prefix and that any custom headers (auth tokens) are correct.

Trigger criteria not syncing to Salesforce

Cause: The sync from web app to Salesforce Route_Criteria__c records failed silently.

Fix:

• Check Salesforce connection -- Go to Integrations and verify the Salesforce org shows "Connected". Reconnect if the OAuth token expired.
• Verify the object exists -- In Salesforce Setup, search for "Route Criteria" under Custom Objects. If missing, redeploy the package from Integrations → Deploy Package.
• Manual sync -- Open the rule, make any small edit to a trigger condition, and save again. This forces a re-sync.
• Check logs -- Look at web app logs (docker logs lead-routing-web-1 --tail 50) for SFDC_SYNC_ERROR messages with details.

Changelog