Capturing Leads

The lead() function is Usermaven’s dedicated method for capturing lead information. It’s designed specifically for lead generation and requires a valid email address.

Before you begin

Usermaven tracking script is installed on your website
You have forms or interactions that capture email addresses

The lead() function

Basic syntax


window.usermaven('lead', {
  email: 'lead@example.com',    // Required
  first_name: 'John',           // Optional
  last_name: 'Doe',             // Optional
  company: 'Acme Inc',          // Optional
  // ... additional properties
});

Parameters

Parameter	Type	Description
`email`	string	Required. Must be a valid email address.
`first_name`	string	Lead’s first name
`last_name`	string	Lead’s last name
`company`	string	Company name
`phone`	string	Phone number
`job_title`	string	Job title
`lifecycle_stage`	string	Lead stage (e.g., ‘subscriber’, ‘marketing_qualified’)
Custom properties	any	Any additional data you want to capture

Validation

The lead() function enforces strict validation:

Email is required: The function will not execute without a valid email
Email format validation: Invalid email formats are rejected
Email trimming: Leading/trailing whitespace is automatically removed


// These will NOT work:
window.usermaven('lead', { name: 'John' });  // Missing email
window.usermaven('lead', { email: '' });     // Empty email
window.usermaven('lead', { email: 'invalid' }); // Invalid format
 
// This WILL work:
window.usermaven('lead', { email: 'john@example.com' });

Implementation examples

Vanilla JavaScript


document.getElementById('lead-form').addEventListener('submit', function(e) {
  e.preventDefault();
 
  const formData = new FormData(this);
 
  window.usermaven('lead', {
    email: formData.get('email'),
    first_name: formData.get('first_name'),
    last_name: formData.get('last_name'),
    company: formData.get('company'),
    phone: formData.get('phone')
  });
 
  // Continue with form submission or show success message
  alert('Thank you for your interest!');
});

With form validation


function captureLeadWithValidation(formElement) {
  const email = formElement.querySelector('[name="email"]').value.trim();
 
  // Validate email format
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!emailRegex.test(email)) {
    alert('Please enter a valid email address');
    return false;
  }
 
  window.usermaven('lead', {
    email: email,
    first_name: formElement.querySelector('[name="first_name"]')?.value,
    last_name: formElement.querySelector('[name="last_name"]')?.value,
    company: formElement.querySelector('[name="company"]')?.value
  });
 
  return true;
}

React with useUsermaven hook


import { useUsermaven } from '@usermaven/react';
import { useState } from 'react';
 
function LeadCaptureForm() {
  const { lead } = useUsermaven();
  const [formData, setFormData] = useState({
    email: '',
    first_name: '',
    company: ''
  });
 
  const handleSubmit = (e) => {
    e.preventDefault();
 
    lead({
      email: formData.email,
      first_name: formData.first_name,
      company: formData.company
    });
 
    // Show success state
    alert('Thanks for signing up!');
  };
 
  return (
    <form onSubmit={handleSubmit}>
      <input
        type="email"
        name="email"
        value={formData.email}
        onChange={(e) => setFormData({ ...formData, email: e.target.value })}
        required
      />
      <input
        type="text"
        name="first_name"
        value={formData.first_name}
        onChange={(e) => setFormData({ ...formData, first_name: e.target.value })}
      />
      <input
        type="text"
        name="company"
        value={formData.company}
        onChange={(e) => setFormData({ ...formData, company: e.target.value })}
      />
      <button type="submit">Get Started</button>
    </form>
  );
}

Next.js


'use client';
 
import { useUsermaven } from '@usermaven/react';
 
export default function NewsletterSignup() {
  const { lead } = useUsermaven();
 
  async function handleSubmit(formData) {
    const email = formData.get('email');
 
    // Capture lead
    lead({
      email: email,
      source: 'Newsletter Signup',
      page: window.location.pathname
    });
 
    // Submit to your API
    await fetch('/api/newsletter', {
      method: 'POST',
      body: JSON.stringify({ email })
    });
  }
 
  return (
    <form action={handleSubmit}>
      <input type="email" name="email" required placeholder="Enter your email" />
      <button type="submit">Subscribe</button>
    </form>
  );
}

JavaScript SDK (module import)


import { usermavenClient } from '@usermaven/sdk-js';
 
const usermaven = usermavenClient({
  key: 'YOUR_API_KEY',
  trackingHost: 'https://events.usermaven.com'
});
 
// Capture a lead
usermaven.lead({
  email: 'lead@example.com',
  first_name: 'Sarah',
  last_name: 'Johnson',
  company: 'Tech Corp',
  lifecycle_stage: 'marketing_qualified'
});

Direct send option

By default, lead events are queued and sent with retry logic. For time-sensitive captures (like before page unload), use the directSend option:


// Standard (with retry queue)
window.usermaven('lead', { email: 'lead@example.com' });
 
// Direct send (immediate, no retry)
usermaven.lead({ email: 'lead@example.com' }, true);

Use direct send when:

Capturing leads before page navigation
Real-time lead capture is critical
You’re handling your own retry logic

Adding custom properties

Include any additional data relevant to your business:


window.usermaven('lead', {
  email: 'lead@example.com',
  first_name: 'Alex',
  company: 'StartupXYZ',
 
  // Custom properties
  lead_source: 'Google Ads',
  campaign: 'Q1 Product Launch',
  utm_source: 'google',
  utm_medium: 'cpc',
  utm_campaign: 'product_launch_2024',
  interest: 'Enterprise Plan',
  company_size: '50-100',
  industry: 'Technology',
  use_case: 'Analytics'
});

Lifecycle stages

Track where leads are in your funnel:


window.usermaven('lead', {
  email: 'lead@example.com',
  lifecycle_stage: 'subscriber'  // or 'lead', 'marketing_qualified', 'sales_qualified'
});

Common lifecycle stages:

subscriber - Signed up for newsletter/updates
lead - Showed interest (downloaded content, attended webinar)
marketing_qualified - Meets marketing criteria
sales_qualified - Ready for sales outreach
opportunity - Active sales conversation
customer - Converted to paying customer

lead() vs track()

Use the right function for the right purpose:

Use `lead()` when	Use `track()` when
Capturing contact information	Tracking user actions/events
Email is available	Email may not be available
Lead generation forms	General form submissions
Creating/updating contacts	Recording behavioral events


// lead() - creates/updates a contact
window.usermaven('lead', {
  email: 'user@example.com',
  first_name: 'John'
});
 
// track() - records an event
window.usermaven('track', 'form_submitted', {
  form_name: 'Contact Form'
});

You can use both together:


function handleFormSubmit(formData) {
  // Capture the lead
  window.usermaven('lead', {
    email: formData.email,
    first_name: formData.name
  });
 
  // Also track the form submission event
  window.usermaven('track', 'demo_requested', {
    form_name: 'Demo Request',
    page: window.location.pathname
  });
}

Error handling

The lead() function logs errors to the console when validation fails. In production, you may want to handle these gracefully:


function captureLead(data) {
  if (!data.email || !isValidEmail(data.email)) {
    console.warn('Invalid email provided to lead capture');
    return false;
  }
 
  try {
    window.usermaven('lead', data);
    return true;
  } catch (error) {
    console.error('Lead capture failed:', error);
    return false;
  }
}
 
function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

Best practices

Always validate email client-side before calling lead()
Capture at the right moment - after successful form submission, not before
Include relevant context - source, campaign, page URL
Don’t capture sensitive data - avoid passwords, SSNs, credit cards
Use consistent property names - establish naming conventions
Set lifecycle stages - helps with lead qualification

What’s next?

Leads in Contacts Hub - View and manage captured leads
Form Tracking - Automatic lead capture from forms