Back to Home|Documentation

FreshLeads Docs

Everything you need to set up, configure, and scale your lead routing engine.

Getting Started

FreshLeads is a hybrid lead generation and routing engine. Follow these steps to get your instance running.

1. Install Dependencies

npm install

2. Configure Environment

Create a .env.local file in the project root with the variables listed in the Environment Variables section below.

3. Set Up Database

Run the SQL from migrations/001_init.sql against your PostgreSQL database, then optionally seed test data.

4. Start the Dev Server

npm run dev

The app will be available at http://localhost:3000.

Environment Variables

All secrets are managed via a .env.local file. Never commit this file to version control.

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=fnm_leads
DB_USER=fnm_user
DB_PASSWORD=your_password

# Auth
JWT_SECRET=your_jwt_secret

# Redis
REDIS_URL=redis://localhost:6379

# Twilio
TWILIO_ACCOUNT_SID=your_sid
TWILIO_AUTH_TOKEN=your_token
TWILIO_FROM_PHONE=your_twilio_number

# Stripe
STRIPE_SECRET_KEY=your_secret_key
STRIPE_WEBHOOK_SECRET=your_webhook_secret

# App
NEXT_PUBLIC_APP_URL=http://localhost:3000

API Reference

All API routes are under /api. Authenticated routes require a valid JWT session cookie.

POST/api/intake

Submit a new lead for validation and routing.

{ "name": "John Doe", "phone": "555-0100", "zip": "90210", "service_type": "roofing" }
GET/api/leads

Retrieve all leads assigned to the authenticated contractor.

POST/api/leads/[id]/status

Update the status of a specific lead (e.g., contacted, converted).

{ "status": "contacted" }
POST/api/wallet/topup

Initiate a Stripe payment to top up the contractor wallet balance.

{ "amount": 500 }
POST/api/webhooks/stripe

Stripe webhook endpoint for processing payment confirmations.

POST/api/twilio/voice

Twilio voice webhook for handling live call transfer flows.

Routing Modes

The routing engine supports two primary delivery modes, configurable per contractor.

Exclusive Mode

A lead is delivered to a single contractor. Ideal for premium traffic. Typical price: $200-$300 / lead.

Shared Mode

A lead is delivered to up to 3 contractors simultaneously using fair rotation. Typical price: $85 x 3 = $255 revenue.

Routing Logic

  1. Lead is submitted via /api/intake.
  2. Validation checks for duplicates and geo-matching against contractor service areas.
  3. Eligible contractors are ranked by wallet balance and speed tier.
  4. Lead is dispatched and wallet is debited atomically.
  5. Contractor is notified via webhook or SMS (Twilio).

Lead Validation

Every incoming lead passes through an automated validation pipeline before routing.

Duplicate Check

Detects leads with the same phone number submitted within a configurable time window.

Geo-Matching

Validates that the lead ZIP code falls within at least one active contractor's service area.

Required Fields

Ensures name, phone, ZIP, and service type are present and properly formatted.

AI Scoring (Optional)

An AI scoring layer can rank lead quality based on historical conversion data.

Metrics & Analytics

The dashboard tracks key performance indicators in real time.

Revenue per Lead

Calculated automatically on successful delivery based on routing mode.

CPL (Cost Per Lead)

Integrate with your ad platform API to track acquisition cost.

Response Rate

Calculated per contractor based on lead status updates (contacted / converted).

Wallet Balance

Real-time balance tracking with automated Stripe top-up triggers.

Tech Stack

Next.js 14

App framework (App Router)

PostgreSQL

Relational database

Redis

Queue & caching layer

Twilio

SMS & live call transfers

Stripe

Payments & wallet top-ups

TypeScript

Type-safe codebase