State Restrictions

Control lead acceptance based on geographic location to comply with regulatory requirements, licensing restrictions, or business preferences.

Overview

State restrictions allow you to:

• Block leads from specific states or countries
• Allow leads only from permitted regions
• Route leads differently based on location
• Comply with state-specific regulations
• Manage licensing requirements by geography

This is particularly useful for:

• Programs with limited state authorization
• Federal and state compliance requirements
• Regional program offerings
• Geographic expansion planning

How State Restrictions Work

State restrictions are enforced during the lead validation phase:

Lead Received → Extract Location → Check Restrictions → Accept/Reject

Location Detection:

1. Explicit state field: If lead includes state field
2. ZIP code lookup: Map ZIP code to state
3. IP geolocation: Determine state from IP address (fallback)
4. Phone area code: Estimate state from phone number (fallback)

Configuring State Restrictions

Allowed States: CA, NY, TX, FL, IL
Result: Only these 5 states accepted

Blocked States: AK, HI
Result: All states except Alaska and Hawaii

"We're sorry, but we are not currently accepting applications
from your state. Please contact [email protected] for
information about future availability."

Restriction Strategies

Strategy 1: Allowlist by Authorization

Use Case: Only accept leads from states where you’re authorized to operate.

Configuration:

Mode: Allowlist
Allowed States: [List of 30+ authorized states]
Rejection Message: "We are not currently authorized to serve students in your state."

Benefits:

• Ensures compliance
• Clear acceptance criteria
• Easy to update as authorization expands

Strategy 2: Blocklist for Compliance

Use Case: Exclude a few problematic states.

Configuration:

Mode: Blocklist
Blocked States: [State X, State Y]
Rejection Message: "Due to regulatory requirements, we cannot accept applications from your state at this time."

Benefits:

• Simpler for few exclusions
• More permissive by default
• Easy to add states as needed

Strategy 3: Program-Specific Restrictions

Use Case: Different programs have different state authorizations.

Configuration:

MBA Program:

Allowed States: All 50 states

Nursing Program:

Allowed States: CA, NY, TX, FL, PA, OH, IL, NC, GA, MI
(States with nursing board reciprocity)

Teaching Credential:

Allowed States: CA only
(California-specific credential)

Benefits:

• Granular control
• Program-specific compliance
• Accurate tracking

Advanced Features

International Restrictions

Block or allow leads from specific countries:

Allow US Only:

Allowed Countries: US
Rejection Message: "We currently only serve students in the United States."

Block Specific Countries:

Blocked Countries: [List of countries]
Allowed: All others

ZIP Code Restrictions

More granular control by ZIP code:

Block Specific ZIP Codes:

Blocked ZIPs: 90001-90899 (Los Angeles metro)
Reason: "We have a separate campus serving your area. Visit la.university.edu"

Allow Specific Regions:

Allowed ZIPs: 94000-94999, 95000-95999 (SF Bay Area)

Time-Based Restrictions

Temporary restrictions for specific periods:

Example: Phased Rollout:

Phase 1 (Jan-Mar): CA, NY, TX only
Phase 2 (Apr-Jun): Add FL, IL, PA, OH
Phase 3 (Jul-Dec): All authorized states

Example: Temporary Suspension:

Block State: New York
Start: 2025-01-01
End: 2025-03-31
Reason: "Temporary suspension for program review"

Location Detection Methods

1. Explicit State Field

Most reliable method - lead includes state:

{
  "email": "[email protected]",
  "state": "California",
  "country": "US"
}

Advantages:

• 100% accurate
• No guessing required
• Immediate validation

2. ZIP Code Lookup

Map ZIP code to state using built-in database:

{
  "email": "[email protected]",
  "zip_code": "90210"
}
// Detected: California

Advantages:

• Very accurate (99%+)
• Works for US addresses
• Automatic fallback

3. IP Geolocation

Determine location from IP address:

{
  "email": "[email protected]",
  "ip_address": "203.0.113.42"
}
// Detected: California (via IP lookup)

Advantages:

• Works without explicit location
• Good for web forms
• International detection

Limitations:

• Less accurate (70-80%)
• VPNs can mislead
• Use as fallback only

4. Phone Area Code

Estimate state from phone number:

{
  "email": "[email protected]",
  "phone": "+1-415-555-1234"
}
// Estimated: California (415 area code)

Limitations:

• Least accurate method
• Mobile numbers can relocate
• Last resort fallback

Handling Rejected Leads

When a lead is rejected due to state restrictions:

Rejection Response

{
  "success": false,
  "error": "LEAD_REJECTED",
  "reason": "State restriction: We are not currently authorized to serve students in Alaska",
  "rule_id": "state_restriction_nursing",
  "rejected_state": "Alaska",
  "allowed_states": ["CA", "NY", "TX", "FL", "PA"]
}

Rejection Tracking

View rejected leads in Leads → Rejected dashboard:

Waitlist Option

Instead of hard rejection, add to waitlist:

Configuration:

Action: Add to waitlist (instead of reject)
Notification: "We'll notify you when we begin serving your state"

Benefits:

• Capture interested leads
• Notify when restrictions lift
• Track demand by state

Compliance Considerations

State Authorization Database

Maintain up-to-date records:

Track:

• Which states you’re authorized in
• Expiration dates for authorizations
• Pending applications
• Renewal schedules

Example Tracking:

Audit Trail

Every restriction decision is logged:

Lead: [email protected]
State: Alaska
Program: Nursing
Decision: Rejected
Rule: state_restriction_nursing_program
Timestamp: 2024-12-25T10:30:00Z
Detection Method: ZIP code (99501)

Compliance Reports

Generate reports for compliance:

Monthly Rejection Report:

• Leads rejected by state
• Programs affected
• Detection method accuracy
• Appeal requests

Authorization Coverage:

• Leads by state (accepted vs. rejected)
• Authorization gaps
• Demand in non-authorized states

Best Practices

1. Use Allowlist for Strict Compliance

When in doubt, allowlist is safer:

// ✅ Good - Explicit about what's allowed
Allowed States: [List of authorized states]

// ❌ Risky - Might miss a state you shouldn't accept
Blocked States: [Few states]

2. Provide Clear Rejection Messages

Help rejected leads understand why:

// ✅ Good - Clear and helpful
"We are not currently authorized to serve students in Alaska.
For information about future availability, contact [email protected]"

// ❌ Bad - Vague and unhelpful
"Your application cannot be processed"

3. Review Rejections Regularly

Monitor for issues:

// Alert if rejection rate is high
if (rejectionRate > 0.1) {
  alert("10%+ of leads are being rejected due to state restrictions");
}
 
// Track demand in blocked states
if (alaskaRejections > 50) {
  alert("High demand in Alaska - consider pursuing authorization");
}

4. Keep Authorization Status Updated

Review quarterly:

• ✅ Verify current authorizations
• ✅ Check expiration dates
• ✅ Update restrictions
• ✅ Add newly authorized states

5. Test Location Detection

Verify accuracy:

Test with:
- Leads with explicit state field
- Leads with only ZIP code
- Leads with only IP address
- International leads
- Edge cases (territories, military addresses)

API Integration

Setting Restrictions via API

Endpoint: POST /api/validation/state-restrictions

await fetch('https://api.ledly.io/api/validation/state-restrictions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    program_id: 'nursing',
    mode: 'allowlist',
    allowed_states: ['CA', 'NY', 'TX', 'FL', 'PA', 'OH', 'IL'],
    rejection_message: 'Not authorized in your state',
    enabled: true
  })
});

Checking Restrictions

Endpoint: POST /api/validation/check-state

const response = await fetch('https://api.ledly.io/api/validation/check-state', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    state: 'California',
    program_id: 'nursing'
  })
});
 
const result = await response.json();
// { allowed: true, reason: null }

Examples

Example 1: Nursing Program with Limited Authorization

Scenario: Nursing program only authorized in 10 states.

Configuration:

Program: Nursing (BSN)
Mode: Allowlist
Allowed States: CA, NY, TX, FL, PA, OH, IL, NC, GA, MI
Rejection Message: "We are not currently authorized to offer our Nursing
program in your state due to state board requirements. Contact
[email protected] for more information."

Example 2: Online MBA Available Nationwide

Scenario: Online MBA available in all 50 states.

Configuration:

Program: MBA Online
Mode: No restrictions
All States: Allowed

Example 3: Teaching Credential (California Only)

Scenario: Teaching credential is California-specific.

Configuration:

Program: Teaching Credential
Mode: Allowlist
Allowed States: CA only
Rejection Message: "Our teaching credential is specific to California.
We recommend contacting your state's department of education for
approved programs in your state."

Example 4: International Student Restrictions

Scenario: Online program available worldwide except sanctioned countries.

Configuration:

Program: MBA Online
Mode: Blocklist (international)
Blocked Countries: [List of sanctioned countries]
Allowed: All other countries
Detection: Country code from IP or explicit country field

Troubleshooting

Issue: False Rejections

Symptom: Leads from allowed states being rejected.

Causes:

• VPN showing different location
• IP geolocation inaccuracy
• Incorrect state abbreviation

Solutions:

• Require explicit state field
• Use ZIP code as primary detection
• Allow manual override

Issue: False Acceptances

Symptom: Leads from blocked states being accepted.

Causes:

• Missing state information
• IP geolocation bypass
• Incomplete restrictions

Solutions:

• Require state field for critical programs
• Set default action to “reject if unknown”
• Enable stricter validation

Issue: High Rejection Rate

Symptom: Many leads rejected for state restrictions.

Solutions:

• Review authorization status
• Consider expanding to high-demand states
• Add waitlist instead of hard rejection
• Analyze rejected states for expansion opportunities

Related Features

• Lead Validation - Other validation rules
• Enrichment Rules - Add geographic routing
• Custom Fields - Track additional location data
• Analytics - Geographic performance reports

Regulatory Compliance

State restrictions help comply with:

• State Authorization Reciprocity Agreements (SARA)
• State licensing requirements
• Professional board regulations
• Department of Education requirements
• Regional accreditation standards