White-Label API Integration

Integrate Happierleads into Your Own Platform

Use our API to seamlessly integrate visitor intelligence into your platform without users ever knowing they're using Happierleads. Complete control, your brand.

📘 Integration Overview

This guide explains how to integrate Happierleads as a white-label solution using our REST API. Your users will interact only with your interface while Happierleads powers the visitor intelligence behind the scenes.

Perfect for: SaaS platforms, marketing tools, CRM systems, and agencies wanting to offer visitor identification without building the technology themselves.

🔀 Two Integration Patterns

Pattern A: Internal Mapping Only (Recommended)

You maintain a mapping between your users and website IDs. Only your root API user has access to Happierleads. Simpler and more secure.

Use when: You want full control and will handle all data presentation in your UI.

Pattern B: User Invitations

You create individual Happierleads users for each of your users. Enables automated features like CSV exports with white-labeled emails.

Use when: You want to leverage our automated features or email communications.

🚀 Step-by-Step Integration Guide

Create a Website

Before anything else, you need to create a website workspace. This is where all leads for a specific domain will be tracked.

📡 API Endpoint

POST /admin/websites

View Full Documentation

📝 Request Example

{
  "name": "Customer Website #1234"
}

✅ Response Example

{
  "websiteId": "507f1f77bcf86cd799439016"
}

⚠️ IMPORTANT: Save this websiteId in your database! You'll need it for all subsequent API calls.

💡 Pro Tip

Create a mapping in your database: YOUR_USER_ID → WEBSITE_ID. This allows you to query leads for specific users without creating Happierleads accounts for them.

Set Website Limits (CRITICAL - DO NOT SKIP)

🚨 CRITICAL WARNING

If you don't set limits immediately, the website will have UNLIMITED credit access and could consume your entire account quota in minutes. Always set limits right after creating a website!

📡 API Endpoint

PUT /admin/websites/set-limits/{websiteId}

View Full Documentation

Option A: Trial Mode (Recommended for New Users)

PUT /admin/websites/set-limits/507f1f77bcf86cd799439016

{
  "credits": 500,
  "emailAccounts": 2
}

// Then enable trial mode:
PUT /admin/websites/507f1f77bcf86cd799439016

{
  "trialEnds": "2025-02-25T23:59:59.000Z",  // 30 days from now
  "websiteLimitsEnabled": true
}

✅ When trial expires, credits automatically set to 0 (stops tracking)

Option B: Active Subscription

PUT /admin/websites/set-limits/507f1f77bcf86cd799439016

{
  "credits": 5000,
  "emailAccounts": 10
}

// Then enable limits:
PUT /admin/websites/507f1f77bcf86cd799439016

{
  "websiteLimitsEnabled": true
}

✅ User has active subscription with defined limits

Option C: Pause/Disable Tracking

PUT /admin/websites/set-limits/507f1f77bcf86cd799439016

{
  "credits": 0,  // Zero credits = tracking disabled
  "emailAccounts": 0
}

✅ Stops all tracking without deleting the website

💡 Understanding Website States

Trial Mode: Has trialEnds date set → automatically becomes inactive when trial expires
Active Mode: Has credits > 0, no trial date → tracking active, deducts credits as used
Inactive Mode: credits = 0 → tracking stopped, data preserved
No Limits Set: UNLIMITED access → 🚨 DANGEROUS - can drain entire account!

Invite Users (Optional - Pattern B Only)

Only needed if you want users to access Happierleads features directly or receive automated emails. For most integrations, skip this step.

📡 API Endpoint

POST /admin/invites

View Full Documentation

📝 Request Example

{
  "invites": [
    {
      "email": "customer@example.com",
      "role": "Editor",  // ✅ Recommended: Can view & edit, no admin access
      "websites": ["507f1f77bcf86cd799439016"]
    }
  ]
}

CRITICAL: Make sure your account has inviteEmailNotification: false to prevent users from receiving emails!

✅ Response Example

{
  "status": "Invite Sent",
  "invitationLinks": [
    "https://app.happierleads.com/reset-password?isInvite=true&resetId=abc-123..."
  ]
}

You can send this invitation link to your users to let them set their password.

👥 Role Comparison

Role	View Leads	Edit Leads	Invite Users
Viewer	✅	❌	❌
Editor (Recommended)	✅	✅	❌
Admin	✅	✅	✅

Fetch Leads Data

Retrieve visitor intelligence data for a specific website to display in your own UI.

📡 API Endpoint

GET /admin/leads-table

View Full Documentation

📝 Request Example

GET /admin/leads-table?websiteId=507f1f77bcf86cd799439016&dateFrom=2025-01-01&dateTo=2025-01-31&page=1

Required Parameters:

websiteId - The website ID from Step 1
dateFrom - Start date (YYYY-MM-DD)
dateTo - End date (YYYY-MM-DD)
page - Page number for pagination

✅ Response Example

{
  "leads": [
    {
      "company": "Acme Corp",
      "domain": "acme.com",
      "industry": "Technology",
      "employeeCount": 250,
      "revenue": 50000000,
      "location": {
        "city": "San Francisco",
        "state": "California",
        "country": "United States"
      },
      "visits": 5,
      "lastVisit": "2025-01-15T14:30:00Z",
      "pages": ["/pricing", "/features", "/contact"]
    }
  ],
  "totalLeads": 42,
  "totalPages": 5,
  "currentPage": 1
}

🎨 Display This Data

Present this visitor intelligence data in your own UI. Style it to match your brand. Your users never know it's powered by Happierleads.