Registration Data Reference

This document provides authoritative reference information for the client registration system.

Form Fields

Field	Type	Required	Max Length	Validation	Default
name	string	Yes	100	Non-empty, trimmed	—
email	string	Yes	255	Valid email format	—
phone	string	No	20	Phone number format (flexible)	null

Field Validation Rules

Name

Pattern: ^[^\s].{0,98}[^\s]$
Min length: 1 character
Max length: 100 characters
Allowed: Any characters except leading/trailing whitespace
Trimming: Automatic

Valid examples:

• John Smith
• Mary-Jane O'Connor
• José García
• 李明

Invalid examples:

• John (leading space)
• John (trailing space)
• `` (empty string)

Email

Pattern: RFC 5322 compliant
Max length: 255 characters
Case: Case-insensitive (normalized to lowercase)
Uniqueness: Not enforced (same email can register multiple times)

Valid examples:

• john@example.com
• mary.smith+realestate@gmail.com
• jose@subdomain.example.co.uk

Invalid examples:

• john@ (no domain)
• @example.com (no local part)
• john@.com (invalid domain)
• john smith@example.com (space in local part)

Phone

Pattern: Flexible (accepts various formats)
Max length: 20 characters
Allowed: Digits, spaces, hyphens, parentheses, plus sign
Normalization: Stored as entered (not normalized)

Valid examples:

• 555-1234
• (555) 123-4567
• +1 555 123 4567
• 5551234567

Invalid examples:

• call me (non-numeric)
• 555-CALL (letters not allowed)

Note

Phone validation is intentionally permissive to accommodate international formats and user preferences.

System Behavior

Duplicate Handling

Scenario	Behavior
Same email, different name	Creates new lead record
Exact duplicate (email + name)	Updates existing lead’s last_contact timestamp
Same email, registration within 24 hours	Skips routing, updates existing lead

Caution

Duplicate detection is based on email address only. Multiple people can use the same email (e.g., couples).

Lead Record Creation

When registration is submitted, a lead record is created with:

{
  "id": "lead_abc123",
  "name": "John Smith",
  "email": "john@example.com",
  "phone": "+1 555 123 4567",
  "source": "website_registration",
  "status": "new",
  "assigned_agent_id": null,
  "brokerage_id": "broker_xyz",
  "created_at": "2024-01-15T10:30:00Z",
  "last_contact": "2024-01-15T10:30:00Z",
  "preferences": {},
  "notes": ""
}

Lead Status Lifecycle

Status	Meaning	Next States
new	Just registered, not yet contacted	contacted, assigned
assigned	Routed to agent, agent notified	contacted, qualified
contacted	Agent made first contact	qualified, nurture, dead
qualified	Verified as serious buyer	showing, offer
nurture	Not ready yet, follow up later	qualified, dead
dead	Not interested or unresponsive	—

Automatic Status Transitions

Trigger	Old Status	New Status
Registration submitted	—	new
Routing assigns agent	new	assigned
Agent views lead in CRM	assigned	contacted
30 days no activity	Any	nurture

Routing Configuration

Round Robin Algorithm

1. Get all active agents for brokerage
2. Filter to eligible agents (not on vacation, accepting leads)
3. Sort by last_lead_assigned_at (ascending)
4. Assign to agent with oldest timestamp
5. Update agent.last_lead_assigned_at

Fairness guarantee: Over time, each agent receives equal number of leads (±1).

Weighted Distribution

1. Get all active agents with weights
2. Create weighted pool (agent with weight=3 appears 3 times)
3. Rotate through pool sequentially
4. Reset pool when exhausted

Example:

Agent A (weight=3): Gets 3/6 leads
Agent B (weight=2): Gets 2/6 leads
Agent C (weight=1): Gets 1/6 leads

Primary Agent

1. Check if brokerage has primary_agent_id set
2. If yes, assign to that agent
3. If primary agent inactive, fall back to round robin

Semantic Matching (Scribe)

1. Get session preferences (if available)
2. Build preference embedding
3. Query agent specialty embeddings for similarity
4. Return top 3 matches
5. If <3 matches, supplement with round robin

Note

Semantic matching requires Scribe to have detected preferences. Falls back to round robin if no preference data exists.

Notifications

Agent Notification

When a lead is assigned, the agent receives:

Email subject: New lead assigned: [Name]

Email body includes:

• Lead name, email, phone
• Registration timestamp
• Preferences (if detected by Scribe)
• Link to lead in CRM

Delivery: Within 1 minute of assignment

Lead Confirmation

Visitor receives a confirmation email:

Email subject: Welcome to [Brokerage Name]

Email body includes:

• Confirmation of registration
• Link to saved favorites
• Link to My Data page
• Contact info for assigned agent (if applicable)

Delivery: Immediately after registration

API Response Format

Success Response

HTTP 200 OK
Content-Type: application/json

{
  "success": true,
  "lead_id": "lead_abc123",
  "assigned_agent": {
    "id": "agent_xyz",
    "name": "Jane Smith",
    "email": "jane@brokerage.com",
    "phone": "+1 555 987 6543"
  }
}

Error Responses

Validation Error

HTTP 400 Bad Request
Content-Type: application/json

{
  "success": false,
  "error": "validation_failed",
  "details": {
    "email": "Invalid email format"
  }
}

Rate Limit Error

HTTP 429 Too Many Requests
Content-Type: application/json

{
  "success": false,
  "error": "rate_limit_exceeded",
  "retry_after": 60
}

Rate Limits

Endpoint	Limit	Window	Scope
POST /register	3 requests	15 minutes	Per IP address
POST /register	5 requests	1 hour	Per email address

Exceeding limits:

• HTTP 429 response
• Retry-After header with seconds to wait
• Client should implement exponential backoff

Data Retention

Data Type	Retention Period	Deletion Method
Lead records	Indefinite (until deleted by brokerage)	Manual via CRM
Session preferences	30 days after last activity	Automatic cleanup
Email notifications	Not stored (transient)	—
Audit logs	90 days	Automatic cleanup

Privacy Compliance

GDPR Rights (where applicable)

Right	Implementation
Right to access	Export lead data via CRM
Right to rectification	Edit fields in CRM
Right to erasure	“Delete lead” button in CRM
Right to portability	JSON export available
Right to object	Opt-out flag in lead record

CCPA Compliance (California)

• Privacy policy link on registration form
• “Do Not Sell My Info” opt-out available
• Data deletion requests honored within 45 days

CAN-SPAM Compliance

• Unsubscribe link in all email notifications
• Honor unsubscribe within 10 business days
• Physical address in email footer
• Clear “From” name (brokerage name)

Related Documentation

• Understanding Client Registration — Conceptual overview
• Brokerage Administration — Routing configuration
• Lead Management — CRM lead handling
• Understanding Scribe — Preference detection system