blog guide api integration lead-generation

How to Generate Leads from Your Website or App Using Stagewise API

Complete guide to integrating Stagewise's public lead generation API with security best practices and warnings about client-side vs server-side implementation.

By Maulik J
•
How to Generate Leads from Your Website or App Using Stagewise API

Generate Leads Directly from Your Website

Stagewise provides a powerful public API endpoint that allows you to create leads directly from your website or application. This enables seamless integration where contact forms, inquiry forms, or any user interaction on your site can automatically create leads in your Stagewise system.

This guide will walk you through everything you need to know to integrate the lead generation API securely and effectively.

⚠️ Critical Security Warning: Server-Side vs Client-Side

🚨 STRONGLY RECOMMENDED: Use Server-Side Implementation

You MUST implement the API call on your server-side code, not directly from the browser. Here’s why:

Why Server-Side is Essential

  1. 🔒 Security: Your API endpoint URL and configuration remain hidden from end users
  2. 🛡️ Protection Against Attacks: Server-side validation prevents malicious requests
  3. 🤖 Bot Protection: Server-side implementation allows you to implement rate limiting, CAPTCHA, and other bot protection measures
  4. 📊 Better Control: You can validate, sanitize, and log all requests before sending to Stagewise
  5. 🔐 IP Restriction: You can restrict API access to only your server’s IP address

⚠️ Client-Side Implementation Risks

If you choose to implement client-side (NOT RECOMMENDED):

  • 🚨 Your Responsibility: You are fully responsible for handling random attacks, bot attacks, spam submissions, and abuse
  • 🔓 Exposed Endpoint: Your API endpoint URL will be visible in browser developer tools
  • 💥 No Rate Limiting: Malicious users can spam your endpoint with unlimited requests
  • 🤖 Bot Vulnerability: Bots can easily discover and abuse your endpoint
  • 💰 Cost Impact: Excessive API calls may impact your system performance and costs
  • 📉 Data Quality: You’ll receive spam, fake leads, and invalid data

If you must use client-side, you MUST:

  • Configure CORS origins to restrict which domains can call your API
  • Implement client-side rate limiting and validation
  • Use CAPTCHA or similar bot protection
  • Monitor and log all requests for suspicious activity
  • Accept full responsibility for any abuse or attacks

Understanding the API Endpoint

Endpoint Details

  • Method: POST
  • Content-Type: application/json
  • Authentication: Configured via IP restrictions or CORS origins (see configuration below)

Request Body

Send the following fields as JSON:

  • name (required): Lead’s name
  • phone (required): Lead’s phone number
  • email (required): Lead’s email address
  • message (optional): Additional message from the lead
  • lead_type_name (optional): Name of the lead type. Falls back to first lead type if not provided

Response

On success, you’ll receive a response with the created lead details.

Step-by-Step Setup Guide

Step 1: Access Lead Generation Configuration

  1. Log in to your Stagewise account
  2. In the left navigation menu, click on Integration
  3. Select Stagewise API from the integration options
  4. You’ll see your public API endpoint URL
  5. Configure security settings (see Step 2)

Step 2: Configure Security Settings

  1. Disable “Allow from all IPs” checkbox
  2. Add your server’s IP address to the allowed IPs list
  3. This ensures only requests from your server are accepted
  4. Your server’s IP is the public IP address where your backend code runs

How to find your server IP:

  • Check your hosting provider’s dashboard
  • Use services like curl ifconfig.me from your server
  • Contact your hosting provider if unsure

If you absolutely must use client-side:

  1. Enable “Allow from all IPs” checkbox
  2. Add your website’s origin to the allowed CORS origins list
    • Example: https://yoursite.com
    • Example: https://www.yoursite.com
    • Add both with and without www if needed
  3. Leave empty to allow all origins (NOT RECOMMENDED)

⚠️ Remember: With client-side implementation, you’re responsible for all security measures and abuse prevention.

Step 3: Configure Rate Limiting

Stagewise provides built-in rate limiting to protect your API from abuse:

  1. Set Maximum Leads Per IP - Enter a number in the “Rate Limiting” section

    • Example: Set to 5 to allow 5 leads per IP address per 24 hours
    • Example: Set to 10 to allow 10 leads per IP address per 24 hours
    • Leave empty for no rate limiting (not recommended for public APIs)

  2. How it works:

    • The system tracks leads created from each IP address
    • Counts are reset every 24 hours
    • If an IP exceeds the limit, requests return a “Too Many Requests” error
    • This helps prevent spam, bot attacks, and abuse

  3. Recommended settings:

    • Server-side implementation: Set to 10 or 20 leads per IP per day
    • Client-side implementation: Set to 5 or 10 leads per IP per day (more restrictive)
    • High-traffic sites: Adjust based on your expected legitimate traffic

Note: Rate limiting applies per IP address. If multiple users share the same IP (like in an office), they’ll share the same limit.

Step 4: Save Configuration

Click “Save Config” to apply your settings. Changes take effect immediately.

Implementation Guidelines

✅ Recommended: Server-Side Implementation

When implementing server-side, ensure you:

  1. Create an endpoint on your server that receives form submissions from your website
  2. Validate all input before processing (check required fields, validate email format, etc.)
  3. Implement security measures like CAPTCHA validation and rate limiting
  4. Make the API call to Stagewise from your server code, not from the browser
  5. Handle errors gracefully and return appropriate responses to your frontend

Your server acts as a secure proxy between your website and the Stagewise API, keeping your endpoint URL and configuration private.

Only use this if you absolutely cannot implement server-side code and accept full responsibility for security.

If you must use client-side implementation:

  1. Configure CORS origins in Stagewise settings to restrict which domains can call your API
  2. Implement client-side validation to check required fields before submission
  3. Add CAPTCHA protection (reCAPTCHA, hCaptcha, etc.) to prevent bot submissions
  4. Implement rate limiting on the client side to prevent abuse
  5. Monitor for suspicious activity and log all requests

⚠️ If using client-side, you MUST:

  1. Configure CORS origins in Stagewise settings
  2. Implement CAPTCHA (reCAPTCHA, hCaptcha, etc.)
  3. Implement rate limiting on the client
  4. Monitor for suspicious activity
  5. Accept responsibility for any abuse

Security Best Practices

1. Always Use Server-Side Implementation

This is the #1 security best practice. Your server acts as a secure proxy between your website and Stagewise API.

2. Restrict by IP Address

When using server-side:

  • Add only your server’s IP address to the allowed IPs list
  • This ensures only your server can make API calls
  • Even if someone discovers your endpoint URL, they cannot call it from their own IP

3. Validate All Input

Always validate and sanitize user input before sending to Stagewise:

  • Check required fields are present
  • Validate email format
  • Validate phone number format
  • Sanitize message content
  • Check for malicious content

4. Use Built-In Rate Limiting

Stagewise provides built-in rate limiting that you can configure:

  • Set maximum leads per IP in the Stagewise API configuration
  • The system automatically tracks and limits requests per IP address
  • Limits are enforced over a 24-hour rolling window
  • When exceeded, requests return a “Too Many Requests” error
  • Leave empty to disable rate limiting (not recommended)

Recommended: Set a reasonable limit (5-20 leads per IP per day) based on your expected traffic. This protects against spam and bot attacks without blocking legitimate users.

5. Use CAPTCHA

Add CAPTCHA to your forms to prevent bot submissions:

  • Google reCAPTCHA
  • hCaptcha
  • Cloudflare Turnstile

6. Monitor and Log

Keep logs of all API calls:

  • Log successful submissions
  • Log failed attempts
  • Monitor for suspicious patterns
  • Set up alerts for unusual activity

7. Error Handling

Never expose internal errors to users:

  • Return generic error messages to clients
  • Log detailed errors server-side
  • Don’t expose API endpoint URLs in error messages

Testing Your Integration

Test Checklist

  1. ✅ Test with valid data - Ensure leads are created successfully
  2. ✅ Test with missing fields - Verify validation works
  3. ✅ Test with invalid email - Check email validation
  4. ✅ Test rate limiting - Ensure abuse prevention works
  5. ✅ Test from different IPs - Verify IP restrictions work (server-side)
  6. ✅ Test CORS - Verify origin restrictions work (client-side)
  7. ✅ Test error handling - Ensure graceful error messages

Testing Your Implementation

Test your server endpoint using your preferred HTTP client (Postman, curl, etc.) or by submitting forms through your website. Ensure all validation and error handling works correctly.

Troubleshooting

Issue: “Request blocked” or “IP not allowed”

Solution:

  • Check that your server’s IP is added to allowed IPs list
  • Verify you’re making the request from the correct server
  • Check Stagewise configuration settings

Issue: “CORS error” (client-side)

Solution:

  • Add your website’s origin to allowed CORS origins
  • Ensure origin matches exactly (including protocol and domain)
  • Check browser console for exact error message

Issue: “Too Many Requests” or Rate Limit Exceeded

Solution:

  • Check your rate limiting configuration in Stagewise API settings
  • Verify the limit is appropriate for your traffic (may need to increase)
  • If legitimate users are being blocked, consider increasing the limit
  • If using server-side, ensure you’re not making excessive requests
  • Rate limits reset every 24 hours automatically
  • Multiple users behind the same IP (like shared office network) share the same limit

Issue: “Invalid request” or “Missing fields”

Solution:

  • Verify all required fields are being sent: name, email, phone
  • Check JSON format is correct
  • Ensure Content-Type header is application/json

Issue: Leads not appearing in Stagewise

Solution:

  • Check API response for errors
  • Verify lead_type_name matches an existing lead type
  • Check Stagewise logs for any issues
  • Verify API endpoint URL is correct

FAQ

Can I use this API from multiple websites?

Yes, but you should:

  • Use server-side implementation for each website
  • Add each server’s IP to the allowed IPs list
  • Or use CORS origins if client-side (not recommended)

What happens if I exceed rate limits?

If you’ve configured rate limiting in Stagewise API settings and an IP address exceeds the limit:

  • Requests from that IP will return a “Too Many Requests” error
  • The limit resets automatically after 24 hours
  • You can adjust the limit in your API configuration settings
  • If legitimate users are being blocked, increase the limit accordingly

How does rate limiting work?

Rate limiting tracks the number of leads created from each IP address over a 24-hour period. When the configured limit is reached, further requests from that IP are blocked until the 24-hour window resets. This helps prevent spam and abuse while allowing legitimate traffic.

Can I customize the lead type?

Yes, include lead_type_name in your request. If not provided, it defaults to your first lead type.

Is the API endpoint secure?

The endpoint itself is secure, but security depends on your implementation:

  • Server-side with IP restriction: Very secure ✅
  • Client-side with CORS: Less secure ⚠️
  • Client-side without restrictions: Not secure ❌

Can I test without affecting production data?

Check with Stagewise support about test/staging environments or test lead types.

Summary: Key Takeaways

  1. ✅ ALWAYS use server-side implementation - This is the most secure approach
  2. 🔒 Restrict by IP address - Add only your server’s IP to allowed IPs
  3. ⚠️ Avoid client-side - If you must use it, accept full responsibility for security
  4. 🛡️ Implement security measures - Rate limiting, CAPTCHA, validation
  5. 📊 Monitor your integration - Log requests and watch for abuse
  6. ✅ Test thoroughly - Verify all scenarios before going live

Need Help?

Our support team is here to help you integrate the lead generation API securely.

Get in touch:

Remember: Security is your responsibility. Always use server-side implementation and restrict access by IP address for the best security posture.