📂 Multi-Directory Platform

User Guide v2.0

1. Introduction

The Multi-Directory Platform is a full-stack white-label directory SAAS. Create and manage multiple city-specific or industry-specific directories from a single dashboard. Each directory has its own public URL, theme, SEO settings, blog, newsletter, deals, CRM, call tracking, monetization, and more.

🏭 Multi-Industry Templates

10 pre-built templates: local business, farm, restaurant, real estate, medical, service, education, automotive, fitness, hospitality.

🎨 Customizable Themes

Brand colors, fonts, logos, layout per directory. Each directory looks unique.

📱 City-Based URLs

Each directory gets its own public URL at /{slug}. Auto geo-redirect for visitors.

🧮 AI Content Engine

Blog generator, business articles, programmatic pages, content repurposing.

📊 Analytics & CRM

Track views, clicks, calls, visitors. Manage contacts, pipelines, and deals.

💰 Monetization

Tiers, subscriptions, ad zones, sponsored listings, article sponsorships.

43. Admin Panel vs Directory Dashboard

This platform has two layers of navigation. Think of it like a mall:

🏢 Global Admin (The Mall)

Dashboard — cross-directory stats (foot traffic across stores)
Directories — create, manage, clone, sell directories
API Keys — Google, OpenAI, Stripe (fuels all directories)
Settings — tenant name, password

This is where you walk between directories and manage the building.

🏪 Directory Dashboard (Each Store)

Dashboard — directory stats (listings, articles, posts)
Listings + Categories — manage businesses
Blog + SEO Articles (AI Writer) — content marketing
SEO + Trap Doors + Branding — rankings & appearance
Monetize — tiers, subscriptions, ad zones, sponsored articles
Analytics — per-directory views, clicks, events
Integrations — Core Swift, CRM, webhooks, SMTP
Settings + Legal + Domains — directory config

Everything the directory owner needs in one place.

How to Enter a Directory Dashboard

Go to Directories in the global admin
Click the 📂 Dashboard button on any directory card
The sidebar swaps to that directory's controls
Click the back arrow to return to global admin

What Happens When You Sell a Directory

The buyer logs into their own dashboard and sees only their directory — with full access to listings, SEO Articles, monetization, analytics, branding, integrations, and SMTP. They connect their own Core Swift tenant, their own CRM, their own sending email. Everything is independent.

2. Getting Started

Platform URL

Your directory platform — deployed on your domain.

Default Login Credentials

Email:	Your admin email
Password:	Your admin password

Change your password immediately after first login.

Quick Start Steps

Log into your platform with admin credentials.
Create your first directory from the Dashboard using a template.
Add categories relevant to your industry.
Add businesses manually or import via CSV.
Customize the theme (colors, logo, fonts) under directory settings.
Share the public directory URL (e.g., /palm-bay) with visitors.

3. Dashboard

High-level overview with key metrics:

--Total Directories

--Active Listings

--Categories

--API Calls Today

Dashboard Actions

Create a new directory — Click "New Directory" and select a template
View recent listings — Latest 10 listings across all directories
Track growth — Charts showing listing additions over time
Review pending items — Listings awaiting approval

API Endpoint

GET /api/v1/dashboard/stats — Dashboard statistics

4. Directories & Cities

Each directory represents a city or industry. Directories use a city-based URL structure. The root domain is a homepage city grid; each directory lives at /{slug}.

🏠 Root Homepage

The root domain shows a city grid. Visitors browse available cities.

🏡 Per-City Pages

/{city-slug} (e.g., /palm-bay). Displays businesses, deals, blog posts, categories.

🌍 Geo-Redirect

IP-based detection offers to redirect visitors to their nearest city directory. Non-blocking, dismissible banner.

🔍 Per-City SEO

Unique meta title, description, OG tags, JSON-LD schema, canonical URL, sitemap entry per city.

Directory CRUD

GET /api/v1/directories — List all directories

GET /api/v1/directories/:slug — Get single directory with stats

POST /api/v1/directories — Create directory

PUT /api/v1/directories/:slug — Update directory

DELETE /api/v1/directories/:slug — Delete directory and all data

GET /api/v1/directories/:slug/render — Render directory template

GET /api/v1/templates — List available templates

Transfer

POST /api/v1/directories/:id/transfer — Transfer directory to another network

5. Templates

10 industry-specific templates with pre-configured fields and layouts. Templates are loaded from Handlebar files and embeddable at compile time.

🏠 Local Business

Business name, address, phone, website, hours, service area, year established.

🌿 Farm / Farmers Market

Farm name, products, acreage, certifications, pick-your-own hours, market locations.

🍲 Food & Drink

Cuisine type, price range, reservation URL, delivery options, dietary accommodations.

🏢 Real Estate

Property type, beds/baths, sqft, lot size, listing price, agent, open house dates.

🏥 Medical / Healthcare

Providers, specialties, insurance accepted, board certifications, telehealth available.

🔧 Service Professionals

Categories, license numbers, insurance, service radius, availability, reviews.

🎓 Education

Schools, tutoring, colleges, training centers, grade levels, accreditation.

🚗 Automotive

Dealers, repair shops, body shops, parts stores, makes serviced.

💪 Fitness & Wellness

Gyms, studios, trainers, class types, membership options.

🏨 Hospitality

Hotels, B&Bs, vacation rentals, event venues, amenities.

Custom templates with your own field definitions can also be created.

6. Businesses / Listings

Core content of your directories. Each business belongs to a directory and one or more categories.

Key Fields

Name	Business or listing title
Address	Street, city, state, zip
Phone	Primary contact number
Website	Business website URL
Hours	Days and hours of operation
Categories	Assign one or more categories
Description	Rich text description (optional)
Images	Upload up to 10 images per listing
Status	Published, Draft, or Pending Review

CRUD & Search

GET /api/v1/listings — All listings (paginated)

GET /api/v1/directories/:slug/businesses — Directory businesses

GET /api/v1/directories/:slug/businesses/suggestions — Search suggestions

GET /api/v1/directories/:slug/businesses/:business_id — Single business

POST /api/v1/directories/:slug/businesses — Create business

PUT /api/v1/directories/:slug/businesses/:business_id — Update business

DELETE /api/v1/directories/:slug/businesses/:business_id — Delete business

Search

GET /api/v1/search?q=... — Search businesses across directories

GET /api/v1/search/config — List search configs

GET /api/v1/search/config/:directory_id — Get directory search config

PUT /api/v1/search/config/:directory_id — Update search config

GET /api/v1/search/filters/:directory_id — Directory search filters

7. Categories

Organized into 15 categories (Fine Dining & Cuisine, Food & Drink, Home & Outdoor, Professional, etc.) with 61 subcategories underneath. A business can belong to up to 3 subcategories (admins can override to 5). Business owners can remove subcategories instantly; adding new ones requires admin approval.

Category Structure

🍽️ Fine Dining & Cuisine	7 subcategories — Italian, Chinese, Indian, Japanese, French, Mediterranean, Steakhouse
🥤 Food & Drink	7 subcategories — Coffee Shop, Pizza, Seafood, Catering, Bars & Breweries, Food Trucks, Breakfast
🛍️ Hyper-Local Retail	10 categories — Bakeries & Dessert Shops, Boutiques, Farmers Market, Artisan Goods, Specialty Grocery, Home & Decor, Books & Music, Florists, Gifts, Electronics Repair
🔧 Home & Outdoor	10 categories — Cleaning, Electrician, HVAC, Landscaping, Handyman, Plumber, Pool Service, Roofing, Screen Enclosures, Tree Service
🏥 Health & Wellness	7 categories — Chiropractor, Dentist, Medical, Medical Spa, Pet Groomer, Physical Therapy, Veterinarian
💼 Professional	5 categories — Accountant, Business Services, Personal Injury Lawyer, Property Management, Real Estate
🎭 Entertainment	4 categories — Family Entertainment, Live Music & Bars, Attractions & Tours, Special Events
✂️ Personal Care	5 categories — Boat Charter, Day Spa, Fitness Studio, Hair Salon, Tattoo Parlor
🚗 Automotive	3 categories — Auto Repair, Car Detailing, Tire & Oil Change
+ 6 more groups	Pet Services, Education & Family, Other — 1 category each

Multi-Category System

Max per business	3 categories (admin can override to 5 for verified businesses)
Primary category	First category assigned gets full search weight. Additional categories at 75%.
Business owner → remove	Instant self-service. No admin approval needed.
Business owner → add	Request-based. Admin approves from Pending Category Requests panel.
Admin → assign	Direct assignment during search, import, or manual creation. No request flow.

API Endpoints

GET /api/v1/categories — All categories (optional ?directory_id=)

GET /api/v1/categories/:id — Single category with listing count

GET /api/v1/directories/:slug/categories — Directory categories

POST /api/v1/directories/:slug/categories — Create category

PUT /api/v1/directories/:slug/categories/:category_id — Update category

DELETE /api/v1/directories/:slug/categories/:category_id — Delete category

POST /api/v1/directories/:slug/categories/bulk-move — Bulk move categories

POST /api/v1/directories/:slug/categories/bulk-delete — Bulk delete categories

8. Reviews & Submissions

Review moderation and business submission approval flows.

Reviews

GET /api/v1/reviews — List all reviews

GET /api/v1/reviews/stats/:business_id — Review stats per business

GET /api/v1/directories/:slug/businesses/:business_id/reviews — Business reviews

POST /api/v1/reviews — Create review

PUT /api/v1/reviews/:id — Update review

DELETE /api/v1/reviews/:id — Delete review

POST /api/v1/reviews/:id/approve — Approve review

POST /api/v1/reviews/:id/reject — Reject review

Submissions

GET /api/v1/submissions — List submissions

GET /api/v1/submissions/:id — Single submission

POST /api/v1/submissions — Create submission

PUT /api/v1/submissions/:id — Update submission

DELETE /api/v1/submissions/:id — Delete submission

POST /api/v1/submissions/:id/approve — Approve submission (creates business)

POST /api/v1/submissions/:id/reject — Reject submission

9. Deals (Groupon-Style)

Limited-time offers, coupons, and promotions linked to directories and businesses.

🎯 Coupons & Deals

Percentage-off or fixed-price deals. Original vs deal price. Coupon codes for redemption.

⏰ Scheduled Offers

Start/end dates. Deals auto-activate and auto-expire.

📊 Redemption Tracking

Track claims, set limits, auto-mark "Sold Out". Manual claim for testing.

🏢 Featured Deals

Toggle deals as featured. They appear prominently on directory landing pages.

API Endpoints

GET /api/v1/deals — List all deals

GET /api/v1/deals/featured — List featured deals

GET /api/v1/deals/:id — Single deal

GET /api/v1/directories/:slug/deals — Directory deals

GET /api/v1/directories/:slug/businesses/:bid/deals — Business deals

POST /api/v1/deals — Create deal

PUT /api/v1/deals/:id — Update deal

DELETE /api/v1/deals/:id — Delete deal

POST /api/v1/deals/:id/claim — Claim/redeem a deal

10. SEO Module

Per-page SEO meta, sitemap generation, robots.txt, search config, and schema markup.

GET /api/v1/seo/sitemap-config — List all sitemap configs

GET /api/v1/seo/sitemap-config/:directory_id — Get sitemap config

PUT /api/v1/seo/sitemap-config/:directory_id — Update sitemap config

GET /api/v1/seo/:page_type/:page_id — Get SEO meta

PUT /api/v1/seo/:page_type/:page_id — Update SEO meta

POST /api/v1/seo/regenerate-sitemap — Regenerate sitemap

GET /sitemap.xml — Generated sitemap

GET /robots.txt — Robots.txt

GET /api/v1/sitemap.xml — API sitemap

Advanced SEO Config

GET /api/v1/directories/:id/seo-settings — Get directory SEO settings

PUT /api/v1/directories/:id/seo-settings — Update directory SEO settings

GET /api/v1/directories/:id/sitemap — Generate directory sitemap

GET /api/v1/directories/:id/seo-fallbacks — List SEO fallbacks

PUT /api/v1/directories/:id/seo-fallbacks/:page_type — Upsert SEO fallback

GET /api/v1/directories/:id/schema-configs — List schema configs

PUT /api/v1/directories/:id/schema-configs/:schema_type — Upsert schema config

11. Blog System

Full-featured blog per directory. Write, schedule, publish, and distribute blog posts. Supports multiple templates, extended content fields, and scheduled publishing.

📖 Posts & Content

Rich text editor, featured images, tags, categories, author attribution.

⏰ Scheduling

Schedule posts for future publishing. Auto-processes scheduled posts on CRON.

📤 Distribution

Distribute posts across multiple directories simultaneously.

📄 Templates

Pre-built blog post templates for consistent formatting.

Posts CRUD

GET /api/v1/blog-posts — List all posts

GET /api/v1/directories/:slug/blog-posts — Directory posts

GET /api/v1/blog-posts/:id — Single post

POST /api/v1/blog-posts — Create post

PUT /api/v1/blog-posts/:id — Update post

DELETE /api/v1/blog-posts/:id — Delete post

POST /api/v1/blog-posts/:id/publish — Publish post

GET /api/v1/blog-posts/scheduled — List scheduled posts

Extended Posts

GET /api/v1/blog-posts/ext — List extended posts

POST /api/v1/blog-posts/ext — Create extended post

PUT /api/v1/blog-posts/:id/ext — Update extended fields

GET /api/v1/directories/:slug/blog-posts/ext — Directory extended posts

POST /api/v1/blog/distribute — Distribute post

POST /api/v1/blog/process-scheduled — Process scheduled posts

Blog Templates

GET /api/v1/blog-templates — List templates

POST /api/v1/blog-templates — Create template

GET /api/v1/blog-templates/:id — Get template

PUT /api/v1/blog-templates/:id — Update template

DELETE /api/v1/blog-templates/:id — Delete template

Legacy Blog Endpoints

GET /api/v1/blog — List posts (legacy)

POST /api/v1/blog — Create post (legacy)

GET /api/v1/blog/:id — Single post (legacy)

PUT /api/v1/blog/:id — Update post (legacy)

DELETE /api/v1/blog/:id — Delete post (legacy)

GET /api/v1/directories/:slug/blog — Directory posts (legacy)

12. Blog Generator (AI)

AI-powered blog post generation. Generate SEO-optimized content for your directories using templates and topic feeds.

🤖 AI Generation

Generate complete blog posts from topic prompts or template configurations.

🔄 Regeneration

Regenerate existing posts with updated or expanded content.

📋 Template Mapping

Assign blog templates to specific directories for consistent AI output.

POST /api/v1/blog-generate — Generate blog posts via AI

POST /api/v1/blog-posts/:id/regenerate — Regenerate a post

GET /api/v1/blog-templates/:id/directories — List template directories

POST /api/v1/blog-templates/:id/directories — Set template directories

13. Business Articles

Generate and manage individual business profile articles. Each article is tied to a business in a directory and can be auto-generated with AI on a weekly schedule.

📝 Per-Business Content

Generate unique articles for each business listing with AI-driven content.

🔄 Weekly Automation

Auto-generate weekly articles for all businesses in a directory.

📈 Tracking

Track article views and engagement events.

GET /api/v1/directories/:id/business-articles — List articles for directory

POST /api/v1/directories/:id/business-articles/generate — Generate articles

PUT /api/v1/business-articles/:id — Update article

DELETE /api/v1/business-articles/:id — Delete article

POST /api/v1/business-articles/:id/generate-weekly — Generate weekly batch

GET /api/v1/articles/:slug — Serve article publicly

POST /api/v1/business-articles/:id/track — Track article event

Email newsletter system per directory. Build subscriber lists, create AI-generated newsletters, send campaigns.

📥 Subscriber Management

Collect subscribers via opt-in forms. Import in bulk. One-click unsubscribe.

🤖 AI Generation

Auto-generate newsletter content from directory blog posts and listings.

✉️ Send Campaigns

Send newsletters to all subscribers. Per-directory sender settings.

Newsletters

GET /api/v1/newsletters — List newsletters

POST /api/v1/newsletters — Create newsletter

GET /api/v1/newsletters/:id — Get newsletter

PUT /api/v1/newsletters/:id — Update newsletter

DELETE /api/v1/newsletters/:id — Delete newsletter

POST /api/v1/newsletters/:id/generate — AI-generate content

POST /api/v1/newsletters/:id/send — Send newsletter

Subscribers & Settings

GET /api/v1/directories/:slug/email-settings — Get email settings. Answers 200 {"configured": false} (never a 404) when the directory has not configured email yet; configured is true on the stored settings.

PUT /api/v1/directories/:slug/email-settings — Update email settings

DELETE /api/v1/directories/:slug/email-settings — Delete email settings

GET /api/v1/directories/:slug/subscribers — List subscribers

POST /api/v1/directories/:slug/subscribers — Add subscriber

POST /api/v1/directories/:slug/subscribers/import — Bulk import subscribers

POST /api/v1/directories/:slug/subscribers/:id/unsubscribe — Unsubscribe

15. Email Campaigns

Standalone email campaign system with templates and send scheduling.

Email Templates

GET /api/v1/email/templates — List email templates

POST /api/v1/email/templates — Create email template

GET /api/v1/email/templates/:id — Get template

PUT /api/v1/email/templates/:id — Update template

DELETE /api/v1/email/templates/:id — Delete template

Campaigns

GET /api/v1/email/campaigns — List campaigns

POST /api/v1/email/campaigns — Create campaign

GET /api/v1/email/campaigns/:id — Get campaign

PUT /api/v1/email/campaigns/:id — Update campaign

DELETE /api/v1/email/campaigns/:id — Delete campaign

POST /api/v1/email/campaigns/:id/send — Send campaign

16. CRM

Built-in CRM for managing contacts, pipelines, and deals. Track leads from directory listings, form submissions, and manual entry.

👤 Contacts

Contact records with search, custom fields, and directory association.

📋 Pipelines

Custom sales pipelines with stages. Move deals through stages.

💰 Deals

Deal tracking per pipeline with value, stage, expected close date.

Contacts

GET /api/v1/crm/contacts — List contacts

GET /api/v1/crm/contacts/search — Search contacts

POST /api/v1/crm/contacts — Create contact

PUT /api/v1/crm/contacts/:id — Update contact

DELETE /api/v1/crm/contacts/:id — Delete contact

GET /api/v1/directories/:slug/crm/stats — Directory CRM stats

Pipelines

GET /api/v1/crm/pipelines — List pipelines

POST /api/v1/crm/pipelines — Create pipeline

PUT /api/v1/crm/pipelines/:id — Update pipeline

DELETE /api/v1/crm/pipelines/:id — Delete pipeline

Deals

GET /api/v1/crm/deals — List deals

POST /api/v1/crm/deals — Create deal

PUT /api/v1/crm/deals/:id — Update deal

DELETE /api/v1/crm/deals/:id — Delete deal

17. Analytics

Track events, page views, and directory performance metrics. Built-in event tracking system with per-directory breakdowns.

📊 Event Tracking

Track custom events with type, metadata, and directory association.

📋 Directory Breakdown

View analytics filtered by individual directory.

🗑️ Data Purge

Purge old events to maintain database performance.

POST /api/v1/analytics/track — Track an event

GET /api/v1/analytics — List all events

GET /api/v1/analytics/events — List events (paginated)

GET /api/v1/analytics/summary — Analytics summary

GET /api/v1/analytics/by-directory/:directory_id — Directory analytics

DELETE /api/v1/analytics/events/old — Purge old events

18. Monetization

Revenue features for directory operators. Tiered subscription plans, ad zones, sponsored listings, invoices, and payouts.

💵 Subscription Tiers

Define pricing tiers with different features per directory. Monthly/annual billing.

📰 Ad Zones

Sell ad placements within directory pages. Multiple zone positions.

⭐ Sponsored Listings

Premium business listings with enhanced visibility and badges.

📄 Invoices & Payouts

Generate invoices for advertisers. Track payouts and commissions.

GET /api/v1/monetization — Monetization dashboard

GET /api/v1/monetization/tiers — List tiers

POST /api/v1/monetization/tiers — Create tier

GET /api/v1/monetization/tiers/:id — Get tier

PUT /api/v1/monetization/tiers/:id — Update tier

DELETE /api/v1/monetization/tiers/:id — Delete tier

19. Call Tracking

Track phone calls generated from directory listings. Provision local phone numbers per business, record calls, and view analytics.

📞 Phone Numbers

Provision local phone numbers for directory businesses. Numbers are assigned and forwarded.

🎙️ Call Recording

Record inbound calls for quality assurance. Store recordings per call.

📊 Analytics

Track call volume, duration, source directory, and time of day.

Number Management

GET /api/v1/call-tracking/numbers — List provisioned numbers

POST /api/v1/call-tracking/numbers — Provision a number

GET /api/v1/call-tracking/numbers/available — List available numbers

GET /api/v1/call-tracking/numbers/:id — Get number details

PUT /api/v1/call-tracking/numbers/:id — Update number config

DELETE /api/v1/call-tracking/numbers/:id — Release a number

Call Logs & Analytics

GET /api/v1/call-tracking/calls — List calls

GET /api/v1/call-tracking/calls/:id — Get call details

POST /api/v1/call-tracking/calls/:id/recording — Upload recording

GET /api/v1/call-tracking/summary — Call tracking summary

GET /api/v1/call-tracking/by-directory/:directory_id — Per-directory call stats

20. Data Company & Enrichment

Import business data from third-party sources and enrich existing listings with additional information. Enriched listings display a Data Freshness Timestamp showing when the data was last updated (e.g., "Data last updated: June 2025 from Google Places"). This gives visitors confidence that the business information they see is current and accurate.

🔍 Yelp Search

Search Yelp for businesses in any location. Pull name, address, rating, review count, and URL.

📦 Business Enrichment

Enrich listings with Google Places data, contact info, hours, and social profiles.

🎨 Brand Color Extraction

Extract brand colors from logo images. Auto-suggest color palettes for directory branding.

GET /api/v1/yelp/search?term=... — Yelp business search

POST /api/v1/enrich/:id — Enrich a business listing

POST /api/v1/branding/:directory_id/extract — Extract brand colors

21. Import/Export

Bulk import and export data. CSV import for businesses. Export businesses, reviews, contacts in CSV or JSON. Custom export templates for scheduled runs. All website URLs are automatically cleaned on import — tracking parameters like utm_*, fbclid, ref, and 30+ others are stripped before the URL is stored.

📥 CSV Import

Import businesses, services, and locations from CSV files. View import logs for error tracking. URLs are auto-cleaned of tracking params.

📤 Export Data

Export businesses, reviews, and contacts per directory in CSV or JSON format.

📄 Export Templates

Create reusable export templates with field mapping and scheduling.

Import

POST /api/v1/import — Import business data (CSV)

GET /api/v1/import/logs — List import logs

GET /api/v1/import/logs/:id — Get import log details

Export

GET /api/v1/export/businesses/:directory_id — Export businesses

GET /api/v1/export/reviews/:directory_id — Export reviews

GET /api/v1/export/contacts/:directory_id — Export contacts

Export Templates

GET /api/v1/export/templates — List export templates

POST /api/v1/export/templates — Create export template

GET /api/v1/export/templates/:id — Get template

PUT /api/v1/export/templates/:id — Update template

DELETE /api/v1/export/templates/:id — Delete template

POST /api/v1/export/templates/:id/run — Execute export template

22. Programmatic Pages

AI-generated content pages at scale. Generate hundreds of location+service+keyword combination pages with SEO metadata, topics, and author profiles.

📄 Page Generation

Generate programmatic pages from topic templates. Bulk status updates.

📝 Topic Management

Manage topics with suggestions, bulk actions, and author assignment.

✏️ AI Drafting

Generate AI drafts from topic outlines. Repurpose existing content.

🔗 Internal Links

Get internal link suggestions for content SEO optimization.

Pages

GET /api/v1/directories/:id/programmatic-pages — List pages

GET /api/v1/directories/:id/programmatic-pages/:page_id — Get page

POST /api/v1/directories/:id/programmatic-pages/generate — Generate pages

POST /api/v1/directories/:id/programmatic-pages/bulk-status — Bulk status update

Topics & Authors

GET /api/v1/directories/:id/topics — List topics

POST /api/v1/directories/:id/topics — Create topic

PUT /api/v1/directories/:id/topics/:topic_id — Update topic

DELETE /api/v1/directories/:id/topics/:topic_id — Delete topic

POST /api/v1/directories/:id/topics/bulk — Bulk topic action

GET /api/v1/directories/:id/topics/suggestions — Topic suggestions

GET /api/v1/directories/:id/authors — List authors

POST /api/v1/directories/:id/authors — Create author

PUT /api/v1/directories/:id/authors/:author_id — Update author

DELETE /api/v1/directories/:id/authors/:author_id — Delete author

AI Content Tools

POST /api/v1/directories/:id/ai-draft — Generate AI draft

POST /api/v1/directories/:id/repurpose — Repurpose content

GET /api/v1/directories/:id/internal-links — Internal link suggestions

23. Services & Locations

Manage services and locations for directory businesses. Useful for multi-location businesses and service-area professionals.

🏢 Services

Define services offered by businesses. Name, description, price range, duration.

📍 Locations

Manage multiple business locations per directory. Address, phone, hours per location.

📁 CSV Import

Bulk import services and locations from CSV files.

Services

GET /api/v1/directories/:id/services — List services

POST /api/v1/directories/:id/services — Create service

PUT /api/v1/directories/:id/services/:svc_id — Update service

DELETE /api/v1/directories/:id/services/:svc_id — Delete service

POST /api/v1/directories/:id/services/import — CSV import services

Locations

GET /api/v1/directories/:id/locations — List locations

POST /api/v1/directories/:id/locations — Create location

PUT /api/v1/directories/:id/locations/:loc_id — Update location

DELETE /api/v1/directories/:id/locations/:loc_id — Delete location

POST /api/v1/directories/:id/locations/import — CSV import locations

24. Networks

Group directories into networks for shared branding, cross-directory navigation, and homepage management.

🌐 Multi-Directory Groups

Group related directories into networks. Shared themes and navigation.

🏠 Homepage Editor

Customizable homepage sections per network. Hero, featured cities, categories, blog feed.

🎨 Network Branding

Apply consistent branding across all directories in a network.

Networks CRUD

GET /api/v1/networks — List networks

POST /api/v1/networks — Create network

GET /api/v1/networks/:id — Get network

PUT /api/v1/networks/:id — Update network

DELETE /api/v1/networks/:id — Delete network

GET /api/v1/networks/:id/directories — Network directories

POST /api/v1/networks/:id/export — Export network

POST /api/v1/networks/:id/transfer — Transfer network

Branding & Homepage

GET /api/v1/networks/:id/branding — Get network branding

PUT /api/v1/networks/:id/branding — Update network branding

GET /api/v1/networks/:id/homepage — Get network homepage

GET /api/v1/directories/:slug/homepage — Get directory homepage

POST /api/v1/homepage-sections — Create homepage section

GET /api/v1/homepage-sections/:id — Get section

PUT /api/v1/homepage-sections/:id — Update section

DELETE /api/v1/homepage-sections/:id — Delete section

25. Legal Pages

Create and manage legal pages for each directory. Privacy policy, terms of service, cookie policy, and custom legal content.

GET /api/v1/legal-pages — List legal pages

POST /api/v1/legal-pages — Create legal page

GET /api/v1/legal-pages/:id — Get legal page

PUT /api/v1/legal-pages/:id — Update legal page

DELETE /api/v1/legal-pages/:id — Delete legal page

26. Branding

Custom branding per directory. Colors, logos, fonts, and visual identity settings.

🎨 Brand Settings

Primary/secondary colors, logo upload, custom CSS, font selection.

🎥 Color Extraction

Auto-extract brand colors from uploaded logo images.

🔄 Brand Sync

Sync branding assets across directories.

GET /api/v1/directories/:slug/branding — Get directory branding

PUT /api/v1/branding/:directory_id — Update branding

POST /api/v1/branding/:directory_id/extract — Extract brand colors

POST /api/v1/admin/brand-sync — Sync branding

27. ZaarHub Network

ZaarHub is the community aggregation engine that connects multiple directories into a unified discovery experience. Each directory can opt in to share its businesses, deals, and events across the entire platform. ZaarHub includes Verification Badges (Verified Owner, Top Rated, Editor's Pick), a 3-step Claim Workflow at /claim, Editor's Picks for admin-curated featured businesses, and Near-Me Geolocation for proximity-based browsing.

🌐 Multi-Directory Aggregation

Search businesses across all participating directories from a single search bar. Results include city labels so visitors know where each business is located.

📂 Category Pills

Browse categories across all directories via clickable pill filters. Quickly narrow down by industry or service type regardless of city.

📡 Community Activity Feed

Real-time feed showing new businesses, recent deals, and upcoming events from all opt-in directories. Drives cross-directory discovery.

⭐ Featured Deals & Events

Flag deals and events as "Featured" to highlight them across ZaarHub. Featured items appear in the ZaarHub spotlight carousel.

How ZaarHub Works

Each directory has a zaarhub_config in its settings that controls ZaarHub participation.
Toggle Enable ZaarHub on for each directory you want to include.
Toggle Show Featured Deals/Events to push promoted content to the ZaarHub front page.
ZaarHub aggregates at /zaarhub/ or /z/ — a single-page application that loads data from all enabled directories.

Enabling ZaarHub

Navigate to the directory's Settings page.
Find the ZaarHub Configuration section.
Toggle Enable ZaarHub Network to ON.
Optionally toggle Featured Deals and Featured Events to promote specific content.
Save settings. The directory will appear in ZaarHub search results immediately.

ZaarCash Loyalty Programme

ZaarCash 💎 is the network's loyalty currency — native to the platform, not a third-party service. It is earned and spent across every ZaarHub city, and new cities join the same programme automatically.

Earn: 1 ZaarCash per $1.00 of earnable spend at any participating business
Value: 100 ZaarCash = $1.00 (1 ZaarCash = 1¢)
Redemption cap: at most 10% of a bill may be paid with ZaarCash
Minimum: a member must bank at least 100 ZaarCash before redeeming
Free items: free or fully discounted items earn nothing — only the paid subtotal earns
Opt-in: only businesses that sign up to the loyalty programme participate and show the ZaarCash 💎 badge

Every one of those numbers is a per-programme setting, not a constant. Edit them in the admin panel's ⭐ Loyalty Programmes card — earn rate, redemption cap %, minimum balance to redeem, whether free items earn nothing, and the currency's name and icon, plus the per-check-in, per-visit and per-redemption rates. A programme can be scoped to one directory or a whole network (ZaarHub runs one network-wide programme), so another directory could call its currency something else and run different numbers.

ZaarHub Frontend Features

City selector — Dropdown to filter by city/directory.
Global search — Search across all directories with auto-suggest.
Category pills — Filter by category across all cities.
Deals & Events carousel — Rotating featured content.
Community activity feed — Latest additions across the network.
Ticker bar — Scrollable announcements from admin (see Section 30).
Notification bell — In-header icon with directory alerts and updates.
Sign In / Profile — Auth-based identity with role switcher (Visitor, Business Owner, Supplier).
Role switcher — Toggle between visitor, business owner, and supplier views in the header.
Owner verification badges — Verified Owner, Top Rated, and other badges on business listings.
Map/Split view — List, Map, or Split layout toggle using Leaflet.js + OSM tiles.
Happening Today ticker — Rotating micro-ticker with featured deals, events, and spotlights.
Meet the Founder — Story cards section for featured businesses.
Saved bookmarks — localStorage-based collections for quick access to favorite businesses.
Mobile bottom nav — Home, Cities, Deals, Events, Search tabs on small screens.

Secondary Pages

/biz/:slug/:id — Business detail page with gallery, hours, map, reviews, and message form.
/grow — Business owner landing page with feature tiers, plan comparison, and testimonials.
/claim — 3-step business claiming flow: search → verify → confirm.
/user/saved — User profile dashboard with saved spots, written reviews, and redeemed perks.

API Endpoints

GET /api/v1/zaarhub/search?q=... — Search across all ZaarHub directories

GET /api/v1/zaarhub/categories — List aggregated categories

GET /api/v1/zaarhub/deals — Featured deals across directories

GET /api/v1/zaarhub/events — Featured events across directories

27a. Editor's Picks

Editor's Picks are admin-curated businesses that receive special placement on the directory frontend and ZaarHub carousel. This is a manual curation tool — it doesn't affect subscription tiers or billing.

⭐ Curation Controls

Mark any business as an Editor's Pick from the admin panel. The business immediately receives the Editor's Pick badge and appears in the featured section.

↕️ Drag-and-Drop Ordering

Editor's Picks can be reordered via drag-and-drop. The display order on the frontend and ZaarHub carousel follows this ordering.

🌐 Cross-Directory Exposure

Editor's Picks appear in the ZaarHub carousel alongside featured deals and spotlights, giving them visibility across the entire directory network.

💡 Tip: Rotate Editor's Picks weekly or monthly to keep the carousel fresh. Highlight seasonal businesses, new arrivals, or community favorites.

API Endpoints

GET /api/v1/editors-picks — List all Editor's Picks with display order

POST /api/v1/editors-picks/:business_id — Mark business as Editor's Pick

DELETE /api/v1/editors-picks/:business_id — Remove Editor's Pick status

PUT /api/v1/editors-picks/reorder — Update display order

27b. Data Freshness & Timestamp Tracking

Every business listing displays a Data Freshness Timestamp that tells visitors when the listing was last verified. This builds trust and improves engagement on listings with recent verification.

How It Works

Enrichment timestamp	When a listing is enriched from third-party sources (Google Places, Yelp, etc.), the enrichment date and source are recorded. Visitors see: "Data last updated: August 2026 from Google Places."
Manual updates	When a business owner updates their profile via the Business Portal, the timestamp refreshes to reflect the most recent edit.
Stale data flagging	Listings not refreshed in 6+ months appear in the admin panel as "stale." Admins can trigger re-enrichment with one click.
Visitor impact	Listings with recent timestamps ("Updated this month") see higher click-through rates and call conversions than listings with outdated data.

💡 Tip: Set up a recurring n8n workflow to auto-enrich listings older than 90 days. This keeps your directory data current without manual effort and maximizes visitor confidence.

27c. URL Cleanliness

All website URLs submitted by businesses are automatically cleaned of tracking parameters before storage. This keeps listings looking professional and prevents tracking data from leaking through displayed URLs.

What Gets Stripped

Over 30 tracking and analytics parameters are automatically removed, including:

utm_source, utm_medium, utm_campaign, utm_term, utm_content
fbclid, gclid, gclsrc
ref, ref_src, ref_url
_ga, _gl, _ke
mc_cid, mc_eid, mc_tc
hsCtaTracking, hsa_cam, hsa_grp, hsa_mt

And 15+ additional marketing/tracking parameters. The core domain and path are preserved — only query parameters are cleaned.

Where It Applies

Business website URLs — Cleaned on import, manual entry, and API updates.
CSV imports — All URLs in bulk imports are automatically cleaned.
API submissions — URLs submitted via REST API are cleaned before storage.
Display-only delivery — Raw URLs are stored cleaned; tracking params are not recoverable.

27d. Near-Me Geolocation

The Near-Me feature lets visitors find businesses closest to their current location. It uses the browser's Geolocation API with a fallback to IP-based geolocation.

📍 Browser Geolocation

Visitors click the "Near Me" button. The browser prompts for location permission. On approval, businesses are sorted by distance from the visitor's GPS coordinates.

🌍 IP Fallback

If the visitor declines GPS access, the system falls back to IP-based geolocation to approximate their location and show nearby results.

📏 Distance Sorting

Businesses are ranked by Haversine distance from the visitor's position. Each result shows "X.X mi away" for transparency.

Requirements for Near-Me Visibility

Business must have a complete, accurate address with street, city, state, and zip.
Coordinates are geocoded from the address using the platform's geocoding provider.
Incomplete addresses are excluded from near-me results — ensure all business listings have full address data.

⚠️ Important: Near-Me results depend on geocoded coordinates. Newly imported or address-changed businesses may take a few minutes to appear in near-me results while geocoding completes.

API Endpoints

GET /api/v1/near-me?lat=...&lng=...&radius=50 — Businesses within radius (km)

GET /api/v1/geocode?address=... — Geocode address to lat/lng

27e. Collections & Saved Favorites

Visitors can save businesses to their personal collections for quick access. Favorites are stored in localStorage for anonymous users and synced to the server for logged-in users.

How Collections Work

Save any business — Click the bookmark/heart icon on any business listing card or detail page.
LocalStorage fallback — Anonymous visitors' favorites persist in the browser via localStorage. No account required.
Account sync — When a visitor creates an account or signs in, their localStorage favorites are merged with their server-side saved collection.
Cross-device access — Logged-in users see the same saved businesses on any device.

📁 My Saved

The /user/saved dashboard shows all saved businesses, written reviews, and redeemed perks in one view.

🏠 Feed Integration

The ZaarHub feed at /feed surfaces saved businesses, upcoming events, and personalized recommendations.

API Endpoints

GET /api/v1/saved — Get saved businesses for authenticated user

POST /api/v1/saved/:business_id — Save a business to favorites

DELETE /api/v1/saved/:business_id — Remove from favorites

28. Sponsors & Advertising

The advertising system enables directory operators to sell ad placements to businesses. It uses a three-tier structure: Sponsor Profiles → Ad Creatives → Ad Schedules, all managed through an approval queue.

👤 Sponsor Profiles

Sponsors are businesses that have opted to advertise. Sponsor profiles are auto-created from existing business data when an ad is submitted.

🖼️ Ad Creatives

Image-based advertisements with enforced dimensions that must match the selected ad zone. Each creative includes a name, image URL, and optional target URL.

📅 Ad Schedules

Schedules define when an ad runs — with start date, end date, and status (active/paused/ended). Multiple schedules can run concurrently for the same creative.

📋 Approval Queue

All submissions pass through a cascading approval flow: sponsor → creative → schedule. Each level must be approved before the ad goes live.

Ad Zones

Ad zones define the available placement slots in the directory interface. Three zone types are supported:

Zone Type	Size	Location	Max Price
Hero Banner	728×90	Top of directory pages	Configurable
Sidebar	300×250	Side panel on search results	Configurable
Footer	468×60	Bottom of directory pages	Configurable

GET /api/v1/ad-zones — List available ad zones

POST /api/v1/ad-zones — Create ad zone

PUT /api/v1/ad-zones/:id — Update ad zone

DELETE /api/v1/ad-zones/:id — Delete ad zone

Sponsor Profiles

GET /api/v1/sponsors — List sponsors

POST /api/v1/sponsors — Create sponsor profile

GET /api/v1/sponsors/:id — Get sponsor

PUT /api/v1/sponsors/:id — Update sponsor

DELETE /api/v1/sponsors/:id — Delete sponsor

Ad Creatives & Schedules

GET /api/v1/ad-creatives — List ad creatives

POST /api/v1/ad-creatives — Create ad creative

PUT /api/v1/ad-creatives/:id — Update creative

DELETE /api/v1/ad-creatives/:id — Delete creative

GET /api/v1/ad-schedules — List schedules

POST /api/v1/ad-schedules — Create schedule

PUT /api/v1/ad-schedules/:id — Update schedule

DELETE /api/v1/ad-schedules/:id — Delete schedule

Approval Workflow

Each ad submission goes through a three-stage approval process:

Sponsor Approval — Admin reviews the business submitting the ad. Verify the sponsor profile is complete and the business is legitimate.
Creative Approval — Admin reviews the ad creative (image, copy, target URL). Verify dimensions match the zone and content is appropriate.
Schedule Approval — Admin reviews the proposed schedule dates and slot availability. Approve or adjust the date range.

Each level has its own approval endpoint. All three must show "Approved" status before the ad renders publicly.

POST /api/v1/ad-sponsors/:id/approve — Approve sponsor

POST /api/v1/ad-sponsors/:id/reject — Reject sponsor

POST /api/v1/ad-creatives/:id/approve — Approve creative

POST /api/v1/ad-creatives/:id/reject — Reject creative

POST /api/v1/ad-schedules/:id/approve — Approve schedule

POST /api/v1/ad-schedules/:id/reject — Reject schedule

Self-Serve Business Submissions

Business owners can submit ads directly from their Business Portal (/portal):

Log in to the Business Portal and select your business.
Click + New Ad in the Promotions section.
Fill in: Ad Name, Slot Size (from available zones), Image URL, and optional Target URL.
Submit for admin review. The ad appears as "Pending" until all approvals clear.
Track status from the My Ads list — Pending, Approved, or Rejected with reason.

Earnings Tracking

The system tracks earnings at multiple levels:

Per slot — Revenue earned from each scheduled ad placement.
Per sponsor — Aggregate earnings per business across all their ads.
Dashboard — Total earnings overview across all ad zones and sponsors.

GET /api/v1/ad-earnings — Aggregate earnings dashboard

GET /api/v1/businesses/:id/ads/earnings — Per-business ad earnings

GET /api/v1/businesses/:id/ads — List business's ads

POST /api/v1/businesses/:id/ads/submit — Submit ad from business portal

29. Spotlight Listings

Spotlight listings are premium placements that give businesses enhanced visibility both in their local directory and across the ZaarHub network. They appear in a dedicated spotlight carousel section with a configurable badge.

✨ Premium Placement

Spotlight listings render at the top of directory pages and in the ZaarHub spotlight carousel. They stand out from regular listings with a visual badge.

🏷️ Configurable Badge

Each spotlight listing has a custom badge text (e.g., "Featured", "Top Pick", "Best of [City]"). Badges are displayed inline with the listing.

📅 Scheduled Placement

Set a start date and end date for each spotlight. Listings auto-activate and auto-expire based on the schedule.

🌍 ZaarHub Exposure

Toggle the ZaarHub featured flag to expose a spotlight listing across the entire ZaarHub network, not just its local directory.

Managing Spotlight Listings

Go to the Monetization section in the directory dashboard.
Select Spotlight Listings tab.
Click Add Spotlight to create a new premium placement.
Select the business, enter badge text, and choose a slot position (1-based ordering).
Set the start and end date for the placement period.
Toggle Featured on ZaarHub to enable cross-network visibility.
Save. The listing appears in the spotlight carousel immediately (if within date range).

API Endpoints

GET /api/v1/spotlight — List all spotlight listings

GET /api/v1/directories/:slug/spotlight — Directory spotlight listings

POST /api/v1/spotlight — Create spotlight listing

PUT /api/v1/spotlight/:id — Update spotlight

DELETE /api/v1/spotlight/:id — Remove spotlight

POST /api/v1/spotlight/:id/feature — Toggle ZaarHub featured flag

30. Directory Notifications

The notification system powers the ticker bar at the top of the ZaarHub and directory frontends. Create scrolling announcements that inform visitors about events, promotions, or important updates.

📢 Ticker Bar

The ticker bar is a horizontally scrolling strip at the top of the page. Notifications cycle through in a smooth auto-scroll animation.

🔖 Notification Types

Four types: Info (blue), Warning (amber), Announcement (green), and Event (purple). Each type has a distinct visual style.

🔄 Auto-Expiry

Notifications automatically expire based on their date range. Past-due notifications are not displayed and can be purged.

🔗 Link Support

Each notification can include an optional link. Clicking the ticker item navigates the visitor to the specified URL.

Creating a Notification

Navigate to the directory Settings and find the Notifications tab.
Click + New Notification.
Enter the message text (plain text, rendered in the ticker bar).
Select the type: Info, Warning, Announcement, or Event.
Optionally enter a link URL for clickable notifications.
Set the display start and end dates.
Save. The notification appears in the ticker bar immediately (if within date range).

Managing Notifications

Active notifications are shown in the ticker bar, rotating through all currently valid entries. Multiple notifications can be active simultaneously — they cycle in order. Notifications respect their date range; expired ones automatically stop displaying. The ticker bar can be dismissed by visitors, but reappears on the next page load if active notifications exist.

API Endpoints

GET /api/v1/notifications — List all notifications

GET /api/v1/directories/:slug/notifications — Directory notifications (active)

POST /api/v1/notifications — Create notification

GET /api/v1/notifications/:id — Get notification

PUT /api/v1/notifications/:id — Update notification

DELETE /api/v1/notifications/:id — Delete notification

31. Mobile Experience

All front-end pages are fully responsive and optimized for mobile browsing. The ZaarHub frontend and directory pages include mobile-specific navigation and touch-optimized interactions.

📱 Bottom Navigation Bar

On mobile, the primary navigation switches to a fixed bottom bar with five icons: Home, Cities, Deals, Events, Search. This replaces the desktop top navigation.

👆 Touch-Optimized Targets

All interactive elements have a minimum touch target of 44×44px as recommended by Apple's HIG and Material Design guidelines.

🍔 Hamburger Menu

On screens narrower than 768px, the desktop nav links collapse into a hamburger menu. The menu slides in from the side with a clean overlay.

📐 Responsive Layout

All grid layouts, cards, and content sections fluidly adjust from desktop (1280px+) to tablet (768px) to mobile (320px+). No horizontal scrolling required.

Bottom Nav Details

Icon	Label	Destination
🏠	Home	ZaarHub homepage with city grid and featured content
🏙️	Cities	Directory/city browser showing all available cities
🏷️	Deals	Featured deals and coupons from all directories
📅	Events	Upcoming community events across directories
🔍	Search	Global search across all directories and listings

The bottom nav includes safe-area-inset padding for devices with a home indicator (iPhone X+). It is only visible on screens narrower than 768px.

Mobile Best Practices

Cards — Stack vertically on mobile; use full-width cards with clear visual hierarchy.
Forms — Full-width inputs with large tap targets. Labels remain visible above inputs.
Images — Use responsive images with max-width: 100% and WebP format.
Modals — Full-screen modals on mobile with a close button in the top-right corner.
Loading states — Skeleton loaders for content-heavy sections; spinner for small requests.
Touch feedback — Buttons and links have :active states for tactile response.

Tested Viewports

Device	Width	Behavior
Desktop	1280px+	Full sidebar, top nav, multi-column grids
Tablet	768-1279px	Condensed sidebar, 2-column grids, hamburger menu
Mobile	320-767px	Single column, bottom nav, full-width cards

32. API Keys

Manage API keys for external integrations. Create scoped keys with usage tracking and rate limiting.

🔑 Key Management

Create, revoke, and manage API keys with optional expiry dates.

📊 Usage Tracking

Track API call volume per key. View usage history and quotas.

✅ Verification

Verify API keys are valid and active before use.

GET /api/v1/api-keys — List API keys

POST /api/v1/api-keys — Create API key

GET /api/v1/api-keys/:id — Get API key

PUT /api/v1/api-keys/:id — Update API key

DELETE /api/v1/api-keys/:id — Delete API key

GET /api/v1/api-keys/:id/usage — Get key usage

POST /api/v1/api-keys/verify — Verify API key

33. Webhooks

Send real-time notifications to external services when events occur. Integrate with n8n and other automation platforms.

🔗 Event Triggers

Trigger webhooks on listing creation, review submission, deal claims, and more.

📋 Delivery Logs

View delivery status and retry logs for each webhook.

GET /api/v1/webhooks — List webhooks

POST /api/v1/webhooks — Create webhook

GET /api/v1/webhooks/:id — Get webhook

PUT /api/v1/webhooks/:id — Update webhook

DELETE /api/v1/webhooks/:id — Delete webhook

GET /api/v1/webhooks/:id/deliveries — List deliveries

34. Provider Keys

Manage third-party API provider keys. Store and rotate keys for external services used by the platform.

GET /api/v1/provider-keys — List provider keys

POST /api/v1/provider-keys — Upsert provider key

DELETE /api/v1/provider-keys/:provider — Delete provider key

35. Visitor Tracking

Track visitor sessions, page views, and events across directories. Understand how users interact with your listings.

👤 Session Tracking

Track visitor sessions with pag views, events, and duration.

📋 Business Analytics

Per-business visitor summary with page views and actions.

📥 Export

Export visitor data per directory for external analysis.

🎯 Business Claim

Visitors can claim business listings through the tracking system.

Tracking

POST /api/v1/visitors/track — Track visitor session

POST /api/v1/visitors/page-view — Track page view

POST /api/v1/visitors/event — Track visitor event

POST /api/v1/visitors/session/:id/end — End session

Analytics & Claims

GET /api/v1/visitors/summary — Visitor summary

GET /api/v1/visitors/business/:business_id — Business visitor summary

GET /api/v1/visitors/category-summary/:directory_id — Category visitor summary

GET /api/v1/visitors/export/:directory_id — Export visitors

POST /api/v1/businesses/:id/claim — Claim business listing

36. Landing Pages

Create and manage public landing pages per directory. Customizable themes, publish controls, and SEO-friendly URLs.

📄 Page Builder

Create landing pages with rich content, images, and call-to-action sections.

🎨 Public Themes

Pre-built public themes for landing pages. Customizable colors and layout.

📢 Publish Controls

Toggle publish status per page. Preview before going live.

Landing Pages

GET /api/v1/landing-pages — List landing pages

POST /api/v1/landing-pages — Create landing page

GET /api/v1/landing-pages/:id — Get landing page

PUT /api/v1/landing-pages/:id — Update landing page

DELETE /api/v1/landing-pages/:id — Delete landing page

POST /api/v1/landing-pages/:slug/publish — Toggle publish status

GET /api/v1/landing-pages/featured — List featured pages

GET /api/v1/directories/:slug/public-pages — Directory pages

Public Pages (Alias)

GET /api/v1/public-pages — List public pages

POST /api/v1/public-pages — Create public page

GET /api/v1/public-pages/:id — Get public page

PUT /api/v1/public-pages/:id — Update public page

DELETE /api/v1/public-pages/:id — Delete public page

POST /api/v1/public-pages/:slug/publish — Toggle publish

Themes

GET /api/v1/public-themes — List public themes

POST /api/v1/public-themes — Create theme

GET /api/v1/public-themes/:id — Get theme

PUT /api/v1/public-themes/:id — Update theme

DELETE /api/v1/public-themes/:id — Delete theme

37. Domains

🌐 Custom Domains

Point your own domain to a directory. Automatic DNS verification.

✅ Verification

Verify domain ownership via DNS record or HTML file upload.

📋 Domain Limit

Domain limits are managed per subscription plan.

GET /api/v1/domains — List registered domains

POST /api/v1/domains — Register domain

DELETE /api/v1/domains/:domain_id — Remove domain

POST /api/v1/domains/:domain_id/verify — Verify domain

GET /api/v1/plans/:plan_id/domains — Check plan domain limits

38. Automation / n8n

The platform integrates with n8n for workflow automation. Webhooks, CRON triggers, and event-driven actions enable automated content generation, lead sync, review moderation, and more.

Key Automation Use Cases

📡 Lead Sync

Forward new business submissions and review notifications to external CRMs or email lists via webhooks.

🔄 Content Automation

Schedule AI content generation on CRON. Auto-publish blog posts and programmatic pages.

📋 Review Moderation

Auto-approve or flag reviews based on content rules. Send alerts for critical reviews.

📢 Broadcast Notifications

Send email digests, SMS alerts, or Slack messages when new listings are created.

Integration Points

Webhooks — Configure webhooks per-directory or globally for each event type.

API Keys — Use scoped API keys in n8n HTTP Request nodes to call platform APIs.

Provider Keys — Store OpenAI or other provider keys for AI-powered n8n workflows.

CRON — Schedule recurring content generation and data export workflows via n8n CRON triggers.

Format — Webhook payloads use JSON with consistent event envelope format.

39. Industries

The verticals a directory can be built on. The whole list is managed from the admin panel's Industries section — add, rename, re-describe, re-icon, reorder, publish or switch one off. Nothing here needs SQL or a code change.

GET /api/v1/industries/catalogue — Every industry, published or not · operator

POST /api/v1/industries/catalogue — Add an industry (the slug is derived from the name) · operator

PUT /api/v1/industries/catalogue/:slug — Edit, reorder, publish or unpublish · operator

GET /api/v1/industries/available — The published list (active only), in display order · authenticated

Where to click: Admin Panel → 🏭 Industries. Edit a row and press Save; use ↑ / ↓ to reorder; untick published to hide an industry from the list; ＋ Add industry creates one. Preview published list shows exactly what the published-list endpoint returns.

40. Settings

User profile settings, password management, and account configuration.

👤 Profile

Manage your name, email, and account preferences.

🔐 Security

Change password and manage session tokens.

📧 Notifications

Configure email notification preferences per directory.

GET /api/v1/auth/me — Get user profile

PUT /api/v1/auth/password — Change password

41. API Reference

General API usage guidelines for the Multi-Directory Platform.

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer <your-api-key>

API keys are managed from the admin dashboard or via the /api/v1/api-keys endpoint.

Rate Limits

General API	60 requests per minute per key
Search endpoints	30 requests per minute per key
Import/Export	10 requests per minute per key

Content Types

Request: application/json for all POST/PUT requests

Response: application/json for all API responses

File uploads: multipart/form-data for image and CSV uploads

Error Handling

Standard HTTP status codes are used:

200	Success
201	Created
400	Bad request / validation error
401	Unauthorized / missing API key
403	Forbidden / insufficient permissions
404	Not found
409	Conflict / duplicate entry
429	Rate limit exceeded
500	Internal server error

Error responses include a message field with details and an optional errors field with field-level validation messages.

Pagination

List endpoints support pagination with query parameters:

GET /api/v1/businesses?page=1&per_page=20

`page`	Page number (default: 1)
`per_page`	Items per page (default: 20, max: 100)

Responses include total, page, per_page, and total_pages in the response metadata.

44. AI Article Writer (Answer-First)

The AI Article Writer generates SEO-optimized content in the Answer-First format. Access it via SEO Articles in the directory dashboard sidebar.

How It Works

A 10-question wizard collects the business name, category, city, competitors, and nearby areas. The AI generates:

Direct Answer — bold blockquote answering "Who is the best X in Y?"
Comparison Table — side-by-side comparison with competitors
"Why [City] Trusts" — community trust section with nearby cities woven in
FAQ — 4-6 questions in <details> elements

Competitor Auto-Suggest

When you select a directory and enter a business name, the system automatically queries the directory for other businesses that could serve as competitors. These appear as clickable badges — click one to add it. Manual entry is still supported.

AI Article Writer Endpoints

POST /api/v1/admin/articles/generate-answer-first — Generate Answer-First article

POST /api/v1/admin/articles/suggest-competitors — Suggest competitors from same directory

Where Articles Appear

Blog Posts — published in the blog_posts table, visible on the blog
Business Detail Page — saved to business_meta, rendered on the business profile
SEO Tab — saved to business_articles, visible in the directory dashboard

45. Core Swift Native Integration

Core Swift is the sister company engine that handles all CRM, communication campaigns, automation, and tagging. Directories are capture points that feed contacts and trigger campaigns. Every directory network gets its own Core Swift tenant account (not the admin account).

⚡ Built-In Architecture

Core Swift — CRM, campaigns, deal pipelines, call tracking, automation
Multi-Directory — capture points for signups, sponsorships, upgrades
SMTP (per-directory) — newsletters, receipts, transactional emails only
Third-party CRM — optional add-on for sold directories

One-Click Tenant + Campaign Creation

Go to a directory Dashboard → Integrations
Click ✨ Auto-Create Tenant + Campaigns
The system creates a Core Swift tenant account scoped to this directory:

Generates a unique API token
Seeds a Signup Campaign (fires when a business signs up)
Seeds a Sponsor Campaign (fires when a business upgrades)
Creates default email lists per city

Auto-fills the endpoint + token fields
Calls Test Connection to verify
Saves everything automatically

Per-Directory Configuration

Each directory stores its own Core Swift endpoint and token in template_config.integrations. When you sell a directory, the buyer connects their own Core Swift tenant:

Your directory	`https://core.yourplatform.com/tenant/your-city`
Sold directory	`https://core.buyer.com/tenant/their-city`

Endpoints

POST /api/v1/admin/core-swift/setup-tenant — Create tenant + campaigns, get token

POST /api/v1/admin/core-swift/test-connection — Test Core Swift reachability

46. Integrations Panel

Each directory has its own Integrations panel (Dashboard → Integrations). The system is designed around Core Swift as the built-in engine.

⚡ Core Swift (Built-in)

This is the default. Core Swift handles all CRM, campaigns, and communication. No API keys required for your own directories.

Business signs up → flows into Core Swift CRM as a contact, tagged with directory + tier
Business sponsors/upgrades → tag changes, moves to sponsor campaign
Auto-Create button seeds signup + sponsor campaigns with one click

📧 Email (SMTP per Directory)

Configured in Directory Settings → SMTP. Used for newsletters, receipts, and confirmation emails. Each directory has its own sending reputation.

📞 External CRM (Optional)

Connect HubSpot, Salesforce, Zoho, or Pipedrive for sold directories that want their own stack.

🔗 Webhooks

Configure URLs for new businesses, new articles, and lead captures. Each directory has its own webhook endpoints.

47. Trap Door Pages

Hyper-niche landing pages targeting long-tail SEO queries. Generated from combinations of services, cities, days of the week, and time slots.

8,400+Pages per Directory

4Factors (svc x city x day x time)

7API Endpoints

How It Works

Enter your services, cities, days, and time tags
Preview the estimated page count
Generate all combinations as Trap Door pages
Each page has unique SEO meta, content, FAQ, and CTA
Weekly automation via n8n discovers new factors and generates fresh pages

Templates

Create Trap Door templates with patterns like: Best {service} in {city} open {day} {time}. Templates auto-fill placeholders for batch generation.

Public Pages

Each Trap Door page lives at /p/{slug} with:

SEO meta title, description, canonical URL
Structured JSON-LD FAQPage schema for rich snippets
Visible FAQ accordion before call-to-action
Asynchronous impression tracking
Click tracking on business links

Analytics

The Analytics tab shows impressions, clicks, and conversion data. Filter by day, time slot, or service.

48. Sponsored Articles

Monetize directory content by selling article sponsorships to businesses. One of 4 monetization methods alongside Plan Tiers, Subscriptions, and Ad Zones.

How Sponsorship Works

Create a sponsorship from the Monetization → Sponsored Articles tab
Select directory, business, target keyword, weekly price, and duration
Article is generated and published with a Sponsored badge
Business gets exposure; directory gets recurring revenue

Tracking

Per-article impression count (page views)
Per-article click count (business link clicks)
Subscription status, expiration date, billing cycle
Archive sponsorships that end

Two-tier model: Owner articles (directory SEO) are free. Business-sponsored articles are paid, with weekly renewal.

42. B2B SSR Pages

The platform includes three server-rendered B2B pages that connect suppliers, businesses, and service providers across the directory ecosystem:

📋 RFQ Marketplace

/rfq-marketplace — Businesses post Request-for-Quote listings. Suppliers browse and respond to RFQs. Server-side rendered for SEO and fast load times.

🤝 Co-op Hub

/coop-hub — Cooperative purchasing and partnership hub. Businesses and suppliers find collaboration opportunities, group buying arrangements, and shared resource agreements.

📣 Lead Exchange

/lead-exchange — Marketplace for business leads. Qualified leads can be bought, sold, or exchanged between businesses within the directory network.

Architecture

All three B2B pages are server-side rendered (SSR) — pre-rendered HTML is served directly, providing instant first paint, crawlable content for search engines, and excellent performance on mobile devices. The pages use the same design system and CSS framework as the rest of the platform.

API Endpoints

GET /rfq-marketplace — Server-rendered RFQ marketplace page

GET /coop-hub — Server-rendered Co-op Hub page

GET /lead-exchange — Server-rendered Lead Exchange page

43. Notifications Ticker

The Notifications Ticker is a real-time scrolling bar on the directory and ZaarHub frontends that automatically displays recent platform activity. Unlike the admin-managed Announcement Ticker (see Section 30: Notifications), this ticker is system-driven — it populates automatically from platform events without manual input.

🏪 New Businesses

Recently added or verified business listings appear in the ticker.

🏷️ New Deals

Businesses posting new deals or promotions trigger a ticker entry.

⭐ New Reviews

Recent customer reviews with high ratings appear in the ticker.

✅ Verified Claims

Newly claimed and verified businesses are highlighted.

⚙️ Configuration

Enable / Disable	Toggle the ticker on or off from the admin panel under Settings → Notifications Ticker.
Position	Choose top (below header nav) or bottom (above footer).
Scroll Speed	Set animation speed: Slow (60s), Normal (30s), or Fast (15s) for a full scroll cycle.
Max Items	Limit how many ticker entries display at once (default: 5, max: 20). Older entries rotate out automatically.
Event Types	Choose which events appear: new businesses, new deals, new reviews, verified claims. Toggle each independently.

💡 Auto-Populated: Ticker items are generated automatically when the corresponding platform event occurs. There's no manual posting — the system detects new businesses, deals, reviews, and claims and adds them to the ticker queue automatically.

🎨 CSS Customization

The ticker appearance can be customized through the admin panel's Theme settings or by overriding CSS variables:

/* Ticker bar background */
--ticker-bg: #1e293b;
/* Ticker item text color */
--ticker-text: #e2e8f0;
/* Ticker font size */
--ticker-font-size: 0.9rem;
/* Animation duration */
--ticker-speed: 30s;
/* Ticker item accent / highlight color */
--ticker-accent: #10b981;

API Endpoints

GET /api/v1/ticker/items — Retrieve current ticker items with metadata (event type, timestamp, link URL)

GET /api/v1/ticker/config — Retrieve current ticker configuration (enabled, position, speed, max items, event filters)

POST /api/v1/ticker/config — Update ticker configuration (admin only)

50. FAQ

How do I create a new directory?

From the Dashboard, click New Directory. Select a template, enter your city/industry name, and choose a URL slug. The directory will be created with default settings and categories matching the template.

Can I change a directory's template after creation?

Yes. Go to the directory settings page and select a new template. Note that custom field values from the old template that don't exist in the new one will be preserved in the database but hidden from the public view.

How do I add businesses in bulk?

Use the CSV Import feature under the Import/Export section. Download the sample CSV template, fill in your business data, and upload. The system validates and imports with a detailed log.

What AI content features are available?

The platform offers AI blog generation, business article generation, programmatic page generation, newsletter content generation, and content repurposing. Each feature has directory-level configuration for tone, length, and topic focus.

How do I set up call tracking?

Navigate to Call Tracking in the admin panel. Provision a local phone number from available inventory, assign it to a business, and configure forwarding. Calls are automatically logged and recorded.

Can I use my own domain?

Yes. Register your domain under Domains in the admin panel. Follow the verification instructions (DNS TXT record or file upload). Once verified, assign the domain to any directory. SSL is automatic.

How does monetization work?

Define subscription tiers with different feature sets and pricing. Businesses can subscribe to premium tiers for enhanced listings, ad zones, and sponsored placements. Invoices are generated automatically and payouts are tracked per directory.

How do I integrate with n8n?

Create an API key under Settings > API Keys. Use the webhook system to send events to n8n endpoints. The platform exposes all CRUD operations via REST API for n8n HTTP Request nodes to consume.

Is there a mobile app?

The platform is fully responsive and works on mobile browsers. There is no native mobile app, but the admin dashboard and public directory pages are optimized for mobile viewing.

How do I get support?

Contact your platform admin for technical issues, account questions, or feature requests. Include your account email and a description of the issue.

📂 Directory Guide

📂 Multi-Directory Platform

1. Introduction

🏭 Multi-Industry Templates

🎨 Customizable Themes

📱 City-Based URLs

🧮 AI Content Engine

📊 Analytics & CRM

💰 Monetization

43. Admin Panel vs Directory Dashboard

🏢 Global Admin (The Mall)

🏪 Directory Dashboard (Each Store)

How to Enter a Directory Dashboard

What Happens When You Sell a Directory

2. Getting Started

Platform URL

Default Login Credentials

Quick Start Steps

3. Dashboard

Dashboard Actions

API Endpoint

4. Directories & Cities

🏠 Root Homepage

🏡 Per-City Pages

🌍 Geo-Redirect

🔍 Per-City SEO

Directory CRUD

Transfer

5. Templates

🏠 Local Business

🌿 Farm / Farmers Market

🍲 Food & Drink

🏢 Real Estate

🏥 Medical / Healthcare

🔧 Service Professionals

🎓 Education

🚗 Automotive

💪 Fitness & Wellness

🏨 Hospitality

6. Businesses / Listings

Key Fields

CRUD & Search

Search

7. Categories

Category Structure

Multi-Category System

API Endpoints

8. Reviews & Submissions

Reviews

Submissions

9. Deals (Groupon-Style)

🎯 Coupons & Deals

⏰ Scheduled Offers

📊 Redemption Tracking

🏢 Featured Deals

API Endpoints

10. SEO Module

Advanced SEO Config

11. Blog System

📖 Posts & Content

⏰ Scheduling

📤 Distribution

📄 Templates

Posts CRUD

Extended Posts

Blog Templates

Legacy Blog Endpoints

12. Blog Generator (AI)

🤖 AI Generation

🔄 Regeneration

📋 Template Mapping

13. Business Articles

📝 Per-Business Content

🔄 Weekly Automation

📈 Tracking

14. Newsletter

📥 Subscriber Management

🤖 AI Generation

✉️ Send Campaigns

Newsletters