Skip to content
HomeStar Docs

Routing Modes

The brokerage’s routing mode decides which agent on your team gets each new inbound lead. There are five modes plus a layered semantic-filter option that modifies several of them. This page is the reference: what each mode does, when to pick it, and what the failure cases look like.

For the hands-on configuration walkthrough, see setting up lead routing.

Quick decision matrix

Section titled “Quick decision matrix”
Your brokerage looks like…Pick
One person handles every inquiry, with everyone else doing fulfillmentprimary_only
Equal team, no specialties, fair distributionround_robin
Equal team with specialties that match common inquiry typesround_robin + semantic filter
Distinct buying / selling / valuation specialistssubject_based
Pure relevance-based matching (best match wins every time)semantic
You want randomrandom (but read the warning below)

That’s the headline. Below is each mode in detail.

How eligibility works (same for all modes)

Section titled “How eligibility works (same for all modes)”

Before any mode runs, the engine builds the eligible-agent pool — every agent at your brokerage who:

  • Has Lead Recipient turned on in their profile
  • Has an active status
  • Is not disabled

Every mode operates on this pool. An agent who’s off-rotation (lead-recipient off, vacation) is invisible to routing regardless of mode. If the eligible pool is empty, routing falls through to the fallback mode (covered at the bottom of this page).

Mode: primary_only

Section titled “Mode: primary_only”

What it does: Every new lead goes to the agent marked primary at your brokerage.

Best for:

  • Solo brokers where you do all your own intake
  • Small brokerages where one person triages every inquiry before personally handing it off
  • A team where the broker insists on first-touch before delegation

When it’s wrong:

  • You have multiple full-time agents and the primary becomes a bottleneck
  • The primary goes on vacation (the fallback rules below kick in, but new leads still concentrate)

Edge case: if no agent is marked primary, the engine falls back to the first eligible agent — which is essentially random over the alphabetically-or-arbitrarily-first agent. Always have someone marked primary if this mode is in use.

Mode: round_robin

Section titled “Mode: round_robin”

What it does: Rotates through eligible agents in order. The engine remembers where it left off across server restarts, so the rotation is stable even if you redeploy.

Best for:

  • Equal-skill team where fair distribution is the explicit goal
  • Brokerages where every agent can handle every inquiry type
  • Avoiding the appearance of favoritism

When it’s wrong:

  • Agents have meaningfully different specialties (a luxury-only agent shouldn’t be in the rotation for a first-time buyer inquiry — use subject_based or layer in the semantic filter)
  • Some agents are part-time and shouldn’t get the same share as full-time agents — toggle them off lead-recipient when they’re not working

Edge case: round-robin is fair on average over time, not in any individual snapshot. If you look at active-lead counts on a given morning, one agent will always look slightly heavier. That’s not a bug — it’s the math of rotation.

Mode: subject_based

Section titled “Mode: subject_based”

What it does: Looks at the inquiry’s subject field (buying, selling, valuation, etc.) and routes to the agent you’ve assigned to handle that subject. If no agent is assigned to the subject or the assigned agent isn’t eligible, the engine falls back.

Best for:

  • Brokerages where one agent owns all buyer inquiries and another owns all seller inquiries
  • A dedicated valuation specialist who should see every “what’s my home worth” lead
  • Teams structured around inquiry type rather than relationship

When it’s wrong:

  • Inquiry subject doesn’t reliably predict who should handle it (a “buying” inquiry from a luxury client might fit a luxury-only agent better than the generic buyer specialist)
  • The subject taxonomy is fuzzy at your brokerage — agents have overlapping responsibilities

Edge case: if a subject isn’t in the assignment map, the engine falls back to the configured fallback mode. Make sure every subject your forms can submit has at least a default mapping.

Mode: semantic

Section titled “Mode: semantic”

What it does: For each new lead, the engine compares the inquiry text against each agent’s match criteria (price range, service areas, property types, client types, specializations) and assigns the lead to the agent with the closest match. Pure relevance — no rotation, no fairness considerations.

Best for:

  • Brokerages with strongly differentiated specialists where the best-fit agent should always win
  • High-value lead environments where relevance matters more than equal distribution
  • Teams that have populated match criteria carefully for each agent

When it’s wrong:

  • Your agents have similar specialties — the engine will repeatedly pick the same agent for similar inquiries, creating unfair distribution
  • Match criteria are sparse or inconsistent across the team — the engine falls back to the first eligible agent, which defeats the purpose
  • Fairness matters to your team culture — semantic routing has no rotation built in

Edge case: if no agent in the eligible pool has any match criteria populated, the engine falls back to the first eligible agent (effectively meaningless). Semantic mode requires investment in agent match criteria to work as intended.

Mode: random

Section titled “Mode: random”

What it does: Picks a random eligible agent for each lead. No memory, no rotation, no relevance.

Best for:

  • Almost nothing in production
  • A/B testing scenarios where you want to break correlations between agent and lead type
  • Brokerages where the broker actively wants the absence of any pattern

When it’s wrong:

  • Almost always. round_robin gives you fair distribution with stable behavior; random gives you fair distribution only at high volume and creates visibly uneven splits at low volume.

Layered option: semantic filter

Section titled “Layered option: semantic filter”

The semantic filter (separate from the semantic mode itself) is an option that can modify round_robin, subject_based, or random. When enabled, the engine narrows the eligible pool to the top N semantic matches before applying the chosen mode.

This gives you hybrids like:

  • round_robin + semantic filter (top 3) — fair rotation, but only among the three most relevant agents for the inquiry. The textbook configuration for a team with mild specialties.
  • subject_based + semantic filter — primary route is by subject, but within the subject’s eligible agents, narrow to the top N.

The semantic filter requires match criteria on agents (same as the pure semantic mode). Agents without match criteria are excluded from the filter consideration.

Default N: 3. Configurable.

When semantic filter helps:

  • You have 4+ agents with varying specialties
  • You want fair distribution within a relevance-filtered subset
  • You’re considering pure semantic but want to keep some rotation

When it doesn’t:

  • Your team is small (≤3 agents) — “top 3 of 3” is the whole pool, so the filter is a no-op
  • Match criteria aren’t populated — the filter falls back to including everyone

Fallback mode

Section titled “Fallback mode”

When routing can’t pick an agent — no eligible agents, semantic filter excluded everyone, subject map didn’t have an entry — the fallback mode decides what happens next.

Two options:

ModeWhat happensBest for
primary_agentThe lead goes to your primary agent.Most brokerages — guarantees no lead lands without an owner.
unassignedThe lead is created with no assigned_agent_id. It sits in the NEW column with no agent attached; someone has to claim it manually.Brokerages where the broker actively reviews every routing failure before assigning. Risky if lead volume scales.

Pick primary_agent unless you have a specific reason not to.

Mode behavior summary

Section titled “Mode behavior summary”
ModeConsiders inquiry text?Considers agent specialty?Fair distribution?Notes
primary_onlyNoNoNo (one agent)One agent gets everything.
round_robinNoNoYes (over time)Rotation; stable across restarts.
subject_basedSubject field onlyVia your mappingDepends on inquiry mixHard mapping; needs subject→agent setup.
semanticYes (full text)Yes (match criteria)NoBest-fit always wins.
randomNoNoYes at high volumeAvoid unless you have a specific reason.
round_robin + semantic filterYes (narrows pool)Yes (match criteria)Yes within filtered poolThe pragmatic default for differentiated teams.

Configuration changes take effect immediately

Section titled “Configuration changes take effect immediately”

The routing mode is read fresh for each new lead. Changing the mode on Tuesday at 2pm means the next inquiry that arrives at 2:01pm uses the new mode. No restart, no reindex, no waiting period.

If you’re making a significant change, it’s safe to do it during low-volume hours and watch the next few leads to confirm the new behavior is correct.

Section titled “Related”