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

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';


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)

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

1. Always validate email client-side before calling lead()

2. Capture at the right moment - after successful form submission, not before

3. Include relevant context - source, campaign, page URL

4. Don't capture sensitive data - avoid passwords, SSNs, credit cards

5. Use consistent property names - establish naming conventions

6. 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