Location Management

🚀 Quick Start

Add a Location in 3 Steps:

Click "+ Add Location" button
Fill in basic info (ID, name, type, priority, ETA)
Add match criteria (counties, state, cities, or ZIPs)

🎯 Understanding Priority (IMPORTANT!)

Priority determines the ORDER regions are checked. Lower number = checked FIRST.

Recommended Priority Order:

Priority 0-3:   Specific cities/counties (checked FIRST)
Priority 4-6:   State-wide regions
Priority 10+:   Blocked regions & Default/fallback (checked LAST)

Note: Priority 0 = highest priority. Can be used for most important cities or emergency overrides (see Best Practice section below)

⚠️ Rule: Specific BEFORE General

Always give specific regions (cities) LOWER priority than general regions (states).

Blocked regions should have HIGH priority (10+) so they're checked last, allowing city exceptions to be checked first.

Example Scenario:

✅ CORRECT:

San Francisco (Priority 2) → Checked FIRST → Accepts SF jobs
California State (Priority 5) → Checked SECOND → Blocks other CA cities

Result: SF jobs accepted, other CA cities blocked ✓

❌ WRONG:

California State (Priority 2) → Checked FIRST → Blocks ALL CA
San Francisco (Priority 5) → Never checked

Result: ALL CA jobs blocked, including SF ✗

🔍 Understanding Type

Type defines HOW to match jobs to this location:

Type	Match By	Use Case
`county`	County names	Metro areas (Dallas, Austin)
`state`	State name	State-wide coverage
`city`	City names	Specific cities
`zip`	ZIP codes	Very specific areas
`default`	Everything	Catch-all fallback

🎯 Default Type and Priority (CRITICAL!)

⚠️ Special Behavior: Default Type with Empty Criteria

The "default" type with empty matchCriteria: {} has special fallback behavior that IGNORES its priority number!

How Default Type Works:

{
  "id": "houston",
  "type": "default",
  "priority": 5,           ← This number is IGNORED!
  "matchCriteria": {},     ← Empty = fallback only
  "accounts": ["Urgent.ly", "Honk"]
}

What happens:

Empty criteria returns false in priority loop
Skipped during normal priority checking
Only checked if NO other region matches
Acts like priority 21+ (lowest priority)

📋 Example Scenario:

Configuration:
  Priority 5: Houston (default, empty criteria)
  Priority 6: Austin (city, cities: ["Austin"])

Job from "Austin, Texas":
  1. Check Priority 5 (Houston) → Empty criteria → Skip
  2. Check Priority 6 (Austin) → City matches → ACCEPT ✓

Result: Austin wins even though it has HIGHER priority number!

Key Point: City with priority 6 beats default with priority 5 because default is only a fallback.

✅ When Default Matches:

Job from "Houston, Harris County, Texas":
  1. Check Priority 1 (Dallas) → Harris County not in Dallas → Skip
  2. Check Priority 2 (Austin) → Harris County not in Austin → Skip
  3. Check Priority 3 (San Antonio) → Harris County not in SA → Skip
  4. Check Priority 4 (California) → State not California → Skip
  5. Check Priority 5 (Houston default) → Empty criteria → Skip
  6. Fallback Check → Houston (type=default) → MATCH ✓

Result: Houston accepts job as catch-all fallback

Default = "Accept the job if nothing else matches"

💡 Key Takeaway:

Scenario	Behavior
Default with empty criteria	Acts as fallback (lowest priority)
Default with actual criteria	Matches in priority loop like any other
Default priority number	Ignored for empty criteria
Other types vs Default	Always checked before default fallback

❌ Common Misconception:

"If default has priority 5 and city has priority 6, default wins"

This is WRONG!

✅ Correct: Default with empty criteria is ALWAYS checked last, regardless of priority number.

Think of it as: Empty matchCriteria = "I'm a safety net, check me only if nothing else works"

✅ Best Practice:

Use priority 21+ for default types with empty criteria to make it clear they're fallbacks:

{
  "id": "houston",
  "type": "default",
  "priority": 21,          ← Clear intent: fallback region
  "matchCriteria": {},
  "accounts": ["Urgent.ly", "Honk"]
}

This makes the configuration more readable and intent clearer!

🚦 Blocked vs Enabled/Disabled (IMPORTANT!)

Understanding the difference between these two settings:

🔓 Enabled/Disabled (when blocked = false)

Controls whether you're accepting jobs from this region:

✅ enabled: true → "We ARE accepting jobs from this region"
⛔ enabled: false → "We are NOT accepting jobs right now"

🚫 Blocked (overrides enabled status)

Permanent rejection flag:

🚫 blocked: true → "NEVER accept jobs from this region (always reject)"
🔓 blocked: false → "Normal processing (check enabled status)"

⚙️ The Priority Logic

When a job comes in for a region:

1. Is the region blocked?
   YES → ❌ REJECT the job immediately (ignore enabled flag)
   NO  → Continue to step 2

2. Is the region enabled?
   YES → ✅ ACCEPT the job
   NO  → ⛔ DON'T accept the job

📚 Real Examples

Example 1: Florida (Blocked Region)

{
  "id": "florida",
  "blocked": true,
  "enabled": false  ← doesn't matter, blocked overrides
}

Result: ALL Florida jobs are REJECTED

Reason: blocked: true means "never accept"

Example 2: Dallas (Active Region)

{
  "id": "dallas",
  "blocked": false,
  "enabled": true
}

Result: Dallas jobs are ACCEPTED

Reason: Not blocked + enabled = accept jobs

Example 3: Austin (Temporarily Disabled)

{
  "id": "austin",
  "blocked": false,
  "enabled": false
}

Result: Austin jobs are NOT accepted

Reason: Not blocked, but disabled = don't accept right now

Difference from blocked: You can toggle enabled back to true later easily

💡 Key Takeaway:

Scenario	Settings
Never accept jobs (like Florida)	`blocked: true, enabled: false`
Actively accepting jobs (like Dallas)	`blocked: false, enabled: true`
Temporarily not accepting (maintenance)	`blocked: false, enabled: false`
Accept cities, block rest of state	City: `blocked: false, enabled: true` State: `blocked: true, enabled: false`

❌ Common Misconception:

"When we block a region we must enable it to make blocking work"

This is WRONG!

✅ Correct: blocked: true ALONE makes blocking work (enabled is ignored)

Think of it: blocked: true = "Hard NO" (permanent), enabled: false = "Soft NO" (temporary)

✅ In the Dashboard UI:

When you check "Blocked (Reject Jobs)":

Location shown with red border and "BLOCKED" badge
Jobs from this region automatically rejected
Immediately active - no need to do anything else
The enabled checkbox only matters when blocked is false

🎯 Best Practice: Priority for Blocked Regions

💡 For blocked regions, use HIGH priority (10+) because:

✅ Future-proof: If you later add exceptions (specific cities), they'll work
✅ Follows the rule: Specific (cities) before General (states)
✅ No downside: Works the same as low priority when there are no exceptions
✅ Consistent: All blocked catch-all regions at the end

📊 Priority Summary Table

Scenario	Priority Setting	Works?	Best Practice?
Block ALL Florida (no exceptions)	Priority 0 (low)	✅ Yes	⚠️ Works but not recommended
Block ALL Florida (no exceptions)	Priority 10 (high)	✅ Yes	✅ Recommended
Block Florida EXCEPT Miami	Miami: 2, Florida: 0	❌ No (Miami blocked too!)	❌ Wrong
Block Florida EXCEPT Miami	Miami: 2, Florida: 10	✅ Yes	✅ Correct

🚨 Special Case: Emergency Override Pattern

⚠️ When You Need to Block EVERYTHING (Including Exceptions)

Sometimes you need to temporarily block ALL jobs from a region, even if you have specific cities enabled.

Example Scenario:

You're currently accepting jobs from Miami, but need to temporarily block ALL Florida (including Miami) due to an emergency.

❌ Normal Setup (Allow Miami):

Priority 2: Miami (enabled: true, blocked: false)
Priority 10: Florida (enabled: false, blocked: true)

Result: Miami accepted ✅, Other Florida rejected ❌

✅ Emergency Override (Block Everything):

Priority 0: Florida (enabled: false, blocked: true)  ← NEW! Override
Priority 2: Miami (enabled: true, blocked: false)    ← Existing, never reached

Result: ALL Florida rejected ❌ (including Miami)

Why Priority 0 Works Here:

Florida checked FIRST (priority 0)
Miami job matches Florida → Blocked → REJECTED
Never reaches Miami rule (priority 2)

🎓 Two Valid Patterns:

Pattern 1: Allow Exceptions (Normal Case)

Priority 2: Miami (enabled)         ← Checked first
Priority 10: Florida (blocked)      ← Checked last

Use when: You want specific cities enabled, rest blocked

Pattern 2: Override Everything (Emergency)

Priority 0: Florida (blocked)       ← Checked first (overrides)
Priority 2: Miami (enabled)         ← Never reached

Use when: You want to block EVERYTHING temporarily, ignoring exceptions

✅ When to Use Each Pattern:

Situation	Pattern	Priority
Block Florida, EXCEPT Miami	Allow exceptions	Florida: 10 (high)
Block ALL Florida (including Miami)	Emergency override	Florida: 0 (low)
Temporarily disable region	Normal	Set enabled: false

⚠️ Important Note:

The emergency override pattern (priority 0) is useful for temporary situations. Once the emergency is over, consider removing the override or changing it back to high priority (10+) to allow future exceptions.

📋 Match Criteria Examples

Example 1: Dallas Metro (County-Based)

ID: dallas
Type: county
Priority: 1
Match Criteria:
  Counties: Dallas County, Denton County, Tarrant County

Matches: Jobs from any of these counties

Example 2: California State-Wide

ID: california
Type: state
Priority: 5
Match Criteria:
  State: California

Matches: Any job where state = "California"

Example 3: Multiple Criteria (OR Logic)

ID: texasmetro
Type: county
Match Criteria:
  Counties: Dallas County, Harris County
  Cities: Houston, Dallas
  State: Texas

Matches: If county OR city OR state matches (any one is enough)

🔗 How Multiple Criteria Work (CRUCIAL!)

⚠️ Key Rule: OR Logic (Any Match = Success)

When a location has multiple criteria types, they use OR logic. Only ONE needs to match!

Example: Austin with Counties + ZIPs

{
  "id": "austin",
  "matchCriteria": {
    "counties": ["Travis County", "Williamson County"],
    "zips": ["78701", "78702", "78703"]
  }
}

This matches if:

County is "Travis County" OR
County is "Williamson County" OR
ZIP is "78701" OR
ZIP is "78702" OR
ZIP is "78703"

Only ONE criterion needs to match!

Real Job Examples:

✅ Job 1: Downtown Austin

County: Travis County
ZIP: 78701

→ MATCHES! Travis County is in counties list

✅ Job 2: Round Rock

County: Williamson County
ZIP: 78664 (NOT in zip list)

→ MATCHES! Williamson County is in counties list
(Even though ZIP is not in list, county matched!)

✅ Job 3: ZIP Match Only

County: Hays County (NOT in counties list)
ZIP: 78702 (IS in zip list)

→ MATCHES! ZIP 78702 is in zips list
(County doesn't match, but ZIP does!)

❌ Job 4: No Match

County: Hays County (NOT in list)
ZIP: 78748 (NOT in list)

→ NO MATCH - Neither county nor ZIP matches
(Falls through to next priority region)

💡 Why This Is Useful:

You can cover a broad area (counties) PLUS specific exceptions (ZIPs)!

Use Case: Service all of Travis & Williamson counties,
PLUS 3 downtown ZIPs that might be in adjacent counties.

Result:
✅ ALL of Travis County
✅ ALL of Williamson County
✅ PLUS those 3 specific ZIPs (even if in Hays County)

Flexibility! Broad coverage + special cases!

❌ Common Mistake - Thinking AND Logic:

Multiple criteria does NOT mean "must match ALL"

WRONG: "Must be in Travis County AND must be ZIP 78701"
RIGHT: "Must be in Travis County OR must be ZIP 78701"

Adding criteria EXPANDS matching, not restricts it!

🔢 Can Cities Have Same Priority?

✅ YES - Safe when cities DON'T overlap:

Priority 2: San Francisco
Priority 2: Los Angeles
Priority 2: San Diego

Priority 10: California (other areas)

These cities don't overlap, so same priority is fine!

❌ NO - Risky when regions OVERLAP:

Priority 2: Austin (has Travis County)
Priority 2: San Antonio (also has Travis County)

Travis County in both → Unpredictable which matches first!

Fix: Use priority 2 for Austin, priority 3 for San Antonio

➕ How to Add a Location

Click "+ Add Location" button in header
Fill in Basic Information:
- ID: Lowercase, no spaces (e.g., "newyork")
- Name: CamelCase (e.g., "NewYork")
- Display Name: User-friendly (e.g., "New York Location")
- Type: county/state/city/zip/default
- Priority: 1-3 for cities, 4-6 for states, 7+ for default
- ETA: Minutes (e.g., 45)
Add Match Criteria:
- Click "Add" to add counties, cities, or ZIPs
- Enter state name if state-level
- Click "×" on tags to remove items
Select Allowed Accounts (empty = allow all)
Check "Enabled" to activate (or leave off to test first)
Click "Save Location"

🗑️ How to Remove a Location

Find the location card in the grid
Click the "Delete" button (red)
Confirm deletion in the popup
Location is immediately removed from system

⚠️ Warning: Deletion is permanent and cannot be undone!

✏️ How to Edit a Location

Find the location card in the grid
Click the "Edit" button (orange)
Modify any fields (ID cannot be changed)
Click "Save Location"

💡 Best Practices

Test First: Add new locations with enabled: false to test before going live
Specific First: Always give cities lower priority than states
Block Last: Blocked regions should have high priority (checked last)
One Default: Have exactly one "default" type region as fallback
Check Overlaps: Use different priorities if regions share counties/cities
Clear Names: Use descriptive display names for easy identification

🎓 Complete Example: California Setup

Goal: Accept SF/LA/SD, block rest of California

Setup:
1. San Francisco
   - Priority: 2 (checked first)
   - Type: city
   - Cities: San Francisco, Oakland
   - Counties: San Francisco County
   - Enabled: ✓

2. Los Angeles
   - Priority: 2 (same level as SF)
   - Type: city
   - Cities: Los Angeles, Long Beach
   - Counties: Los Angeles County
   - Enabled: ✓

3. San Diego
   - Priority: 2 (same level)
   - Type: city
   - Cities: San Diego
   - Counties: San Diego County
   - Enabled: ✓

4. California Other
   - Priority: 10 (checked last!)
   - Type: state
   - State: California
   - Blocked: ✓

Result:
✓ SF job → Matches priority 2 → Accepted
✓ LA job → Matches priority 2 → Accepted
✓ SD job → Matches priority 2 → Accepted
✗ Fresno job → Matches priority 10 → Blocked

📌 Quick Reference

Field	Purpose	Example
ID	Unique identifier for API	`dallas`
Priority	Check order (lower first)	`1-3` cities, `4-6` states
Type	Matching strategy	`county`, `state`, `city`
Enabled	Accept jobs?	✓ Yes / ✗ No
Blocked	Reject all jobs?	✓ Yes (like Florida)

📍 Location Management

Add Location

📖 Location Management Guide