External Leads Integration

Import leads from your website forms and chatbots directly into Readybuild. This integration allows web forms to automatically create external leads when potential customers submit their information.

Choosing a Lead Capture Method

Readybuild offers three ways to capture leads from your website. See Lead Intake Forms for a full comparison.

Method	Best For
External Lead Forms	Visual form builder with built-in spam protection. Recommended for most users.
External Leads API (this page)	Developers needing complete control over form design
Zapier	No-code automation from other apps

Audience

These instructions are intended for the web developer implementing the integration on your company website.

Overview

The External Leads API supports:

• Website contact forms - Capture leads from any HTML form
• Chatbots - Integrate conversational lead capture
• Source and campaign tracking - Marketing attribution
• Custom field capture - Additional data stored in lead metadata

Prerequisites

Before implementing the integration, you need:

• Your Company ID - Contact Readybuild to obtain this
• Your Authorization Token - Found in Settings > Integrations > External Leads > Configure
• Access to your website's server-side code

Keep Your Token Secure

Your authorization token authenticates requests to Readybuild. Never expose it in client-side JavaScript.

API Specification

Endpoint

POST https://project.readybuild.com/remote/lead_form.php

Required Header

Authorization: YOUR_AUTH_TOKEN

Form Fields

Required Fields

Field	Type	Description
company_id	string	Your Readybuild company ID (contact Readybuild to obtain)
email	string	Lead's email address

Name Fields (one option required)

Field	Type	Description
full_name	string	Lead's full name
first_name	string	Lead's first name (use with last_name)
last_name	string	Lead's last name (use with first_name)

Contact Information

Field	Type	Description
phone_number	string	Lead's phone number
address	string	House number and street name
city	string	City name
state	string	Two-letter state code (e.g., "CA", "TX")
zip	string	ZIP code

Additional Fields

Field	Type	Description
notes	string	Free-form notes or message from the lead
return_url	string	URL to redirect user after submission (required if redirecting)
preferred_contact_method	string	Either Email or Phone
bucket	string	Category/group name for organizing leads (max 90 characters)
source	string	Lead source - must match exactly a source name in Readybuild
campaign	string	Campaign name - must match exactly a campaign name in Readybuild

Lead Buckets

The bucket field allows you to categorize leads from different sources (e.g., "Kitchen Remodel Form", "Bathroom Quote", "General Inquiry"). In Readybuild, users can filter the External Leads list by bucket. Leads without a bucket appear under "No Bucket (General Leads)".

Custom Fields

Any additional fields included in the POST request will be stored in the External Lead Metadata and viewable when reviewing the lead in Readybuild.

Response Handling

If a return_url is provided, Readybuild returns a redirect with query parameters:

Success:

{return_url}?success=true

Error:

{return_url}?error=ErrorMessageHere

Example Implementation

HTML Form

<form action="https://your-server.com/submit-lead.php" method="POST">
  <input type="text" name="first_name" required>
  <input type="text" name="last_name" required>
  <input type="email" name="email" required>
  <input type="tel" name="phone_number">
  <input type="text" name="address">
  <input type="text" name="city">
  <input type="text" name="state" maxlength="2">
  <input type="text" name="zip">
  <textarea name="notes"></textarea>
  <select name="preferred_contact_method">
    <option value="Email">Email</option>
    <option value="Phone">Phone</option>
  </select>
  <button type="submit">Submit</button>
</form>

Server-Side Handler

PHP

<?php
// submit-lead.php

$authToken = 'YOUR_AUTH_TOKEN';
$companyId = 'YOUR_COMPANY_ID';

$postData = [
    'company_id' => $companyId,
    'first_name' => $_POST['first_name'],
    'last_name' => $_POST['last_name'],
    'email' => $_POST['email'],
    'phone_number' => $_POST['phone_number'] ?? '',
    'address' => $_POST['address'] ?? '',
    'city' => $_POST['city'] ?? '',
    'state' => $_POST['state'] ?? '',
    'zip' => $_POST['zip'] ?? '',
    'notes' => $_POST['notes'] ?? '',
    'preferred_contact_method' => $_POST['preferred_contact_method'] ?? '',
    'bucket' => 'Contact Form',
    'return_url' => 'https://your-website.com/thank-you',
    'source' => 'Website',
    'campaign' => 'Spring 2024'
];

$ch = curl_init('https://project.readybuild.com/remote/lead_form.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $authToken
]);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

Node.js

// submit-lead.js
const https = require('https');
const querystring = require('querystring');

const AUTH_TOKEN = 'YOUR_AUTH_TOKEN';
const COMPANY_ID = 'YOUR_COMPANY_ID';

function submitLead(formData) {
    const postData = querystring.stringify({
        company_id: COMPANY_ID,
        first_name: formData.first_name,
        last_name: formData.last_name,
        email: formData.email,
        phone_number: formData.phone_number || '',
        address: formData.address || '',
        city: formData.city || '',
        state: formData.state || '',
        zip: formData.zip || '',
        notes: formData.notes || '',
        preferred_contact_method: formData.preferred_contact_method || '',
        bucket: 'Contact Form',
        return_url: 'https://your-website.com/thank-you',
        source: 'Website',
        campaign: 'Spring 2024'
    });

    const options = {
        hostname: 'project.readybuild.com',
        path: '/remote/lead_form.php',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': AUTH_TOKEN
        }
    };

    const req = https.request(options, (res) => {
        console.log(`Status: ${res.statusCode}`);
    });

    req.write(postData);
    req.end();
}

Python

# submit_lead.py
import requests

AUTH_TOKEN = 'YOUR_AUTH_TOKEN'
COMPANY_ID = 'YOUR_COMPANY_ID'

def submit_lead(form_data):
    post_data = {
        'company_id': COMPANY_ID,
        'first_name': form_data.get('first_name'),
        'last_name': form_data.get('last_name'),
        'email': form_data.get('email'),
        'phone_number': form_data.get('phone_number', ''),
        'address': form_data.get('address', ''),
        'city': form_data.get('city', ''),
        'state': form_data.get('state', ''),
        'zip': form_data.get('zip', ''),
        'notes': form_data.get('notes', ''),
        'preferred_contact_method': form_data.get('preferred_contact_method', ''),
        'bucket': 'Contact Form',
        'return_url': 'https://your-website.com/thank-you',
        'source': 'Website',
        'campaign': 'Spring 2024'
    }

    response = requests.post(
        'https://project.readybuild.com/remote/lead_form.php',
        data=post_data,
        headers={'Authorization': AUTH_TOKEN},
        allow_redirects=False
    )

    return response

C#

// SubmitLead.cs
using System.Net.Http;

public class LeadSubmitter
{
    private const string AuthToken = "YOUR_AUTH_TOKEN";
    private const string CompanyId = "YOUR_COMPANY_ID";

    public async Task SubmitLead(Dictionary<string, string> formData)
    {
        var postData = new Dictionary<string, string>
        {
            { "company_id", CompanyId },
            { "first_name", formData["first_name"] },
            { "last_name", formData["last_name"] },
            { "email", formData["email"] },
            { "phone_number", formData.GetValueOrDefault("phone_number", "") },
            { "address", formData.GetValueOrDefault("address", "") },
            { "city", formData.GetValueOrDefault("city", "") },
            { "state", formData.GetValueOrDefault("state", "") },
            { "zip", formData.GetValueOrDefault("zip", "") },
            { "notes", formData.GetValueOrDefault("notes", "") },
            { "preferred_contact_method", formData.GetValueOrDefault("preferred_contact_method", "") },
            { "bucket", "Contact Form" },
            { "return_url", "https://your-website.com/thank-you" },
            { "source", "Website" },
            { "campaign", "Spring 2024" }
        };

        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", AuthToken);

        var content = new FormUrlEncodedContent(postData);
        var response = await client.PostAsync(
            "https://project.readybuild.com/remote/lead_form.php",
            content
        );
    }
}

Ruby

# submit_lead.rb
require 'net/http'
require 'uri'

AUTH_TOKEN = 'YOUR_AUTH_TOKEN'
COMPANY_ID = 'YOUR_COMPANY_ID'

def submit_lead(form_data)
  uri = URI('https://project.readybuild.com/remote/lead_form.php')

  post_data = {
    'company_id' => COMPANY_ID,
    'first_name' => form_data[:first_name],
    'last_name' => form_data[:last_name],
    'email' => form_data[:email],
    'phone_number' => form_data[:phone_number] || '',
    'address' => form_data[:address] || '',
    'city' => form_data[:city] || '',
    'state' => form_data[:state] || '',
    'zip' => form_data[:zip] || '',
    'notes' => form_data[:notes] || '',
    'preferred_contact_method' => form_data[:preferred_contact_method] || '',
    'bucket' => 'Contact Form',
    'return_url' => 'https://your-website.com/thank-you',
    'source' => 'Website',
    'campaign' => 'Spring 2024'
  }

  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri.path)
  request['Authorization'] = AUTH_TOKEN
  request.set_form_data(post_data)

  response = http.request(request)
end

Source and Campaign Mapping

For proper marketing attribution, the source and campaign field values must exactly match the names configured in Readybuild:

1. Coordinate with your Marketing representative to get the exact names
2. Go to Settings > Marketing in Readybuild to view available sources and campaigns
3. Use the exact spelling and capitalization in your form submission

Testing the Integration

Readybuild recommends:

1. Developer + Marketing collaboration - Work together to test the integration
2. Submit test leads - Verify all fields appear correctly in Readybuild
3. Check metadata - Confirm custom fields are captured in External Lead Metadata
4. Test error handling - Verify your return URL receives error parameters correctly
5. Verify source/campaign mapping - Ensure leads convert with proper attribution

Troubleshooting

Leads Not Appearing

1. Verify the company_id is correct
2. Check the authorization token matches what's in Settings
3. Ensure required fields (email, name fields) are provided
4. Check your server logs for the response from Readybuild

Source/Campaign Not Mapping

1. Verify the field values exactly match names in Readybuild (case-sensitive)
2. Coordinate with your Marketing representative to confirm the correct names
3. Check for extra spaces or special characters

Authorization Errors

1. Copy the token again from Settings > Integrations > External Leads > Configure
2. Ensure no extra spaces or line breaks in the token
3. Verify the Authorization header is being sent correctly

Configuration in Readybuild

Administrators can configure the integration at Settings > Integrations > External Leads:

• View and copy the authorization token
• Regenerate the token if compromised
• View incoming lead activity

Related Documentation

• Lead Intake Forms Overview - Compare all lead capture methods
• Zapier Integration - No-code lead capture from other apps
• Contacts Management
• External Leads Overview
• Sources
• Campaigns