Use the IDX Broker API to create a new lead by sending lead information to the leads/lead endpoint with a PUT request.

Important: The email address submitted for the lead must be correctly formatted and have valid MX records. Invalid email addresses may cause the request to fail.

Developer Notes

This example is intended for developers familiar with:

• PHP
• cURL
• URL-encoded request data
• IDX Broker API keys
• API response codes

The legacy example included an older hardcoded API version and disabled SSL verification. Review API version requirements before hardcoding an apiversion header; IDX Broker has released newer API versions since older examples were written. (IDX Broker Developer)

Example PHP Script

<?php

$url = 'https://api.idxbroker.com/leads/lead';
$apiKey = 'YourAPIKey';
$method = 'PUT';

$data = [
    'firstName' => 'IDX',
    'lastName'  => 'Robot',
    'email'     => 'IDXRobot@example.com'
];

$data = http_build_query($data);

$headers = [
    'Content-Type: application/x-www-form-urlencoded',
    'accesskey: ' . $apiKey,
    'outputtype: json'
];

$handle = curl_init();

curl_setopt($handle, CURLOPT_URL, $url);
curl_setopt($handle, CURLOPT_HTTPHEADER, $headers);
curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($handle, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($handle, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($handle);
$code = curl_getinfo($handle, CURLINFO_HTTP_CODE);

curl_close($handle);

if ($code >= 200 && $code < 300) {
    $response = json_decode($response, true);
} else {
    $error = $code;
}

?>

What This Script Does

This script:

• Sends a PUT request to the IDX Broker lead endpoint
• Creates a lead using first name, last name, and email
• URL-encodes the request data
• Returns the API response as JSON
• Stores the HTTP response code for troubleshooting

Required Fields

At minimum, include:

Email Validation Requirement

The lead email must:

• Be correctly formatted
• Use a domain with valid MX records

If the email address is invalid or the domain cannot receive mail, the API request may fail.

Common Troubleshooting Notes

500 Errors

A 500 response may be caused by an invalid email address or an email domain without valid MX records.

The legacy note states that the API may not clearly differentiate between a server error and a lead rejected because of a bad email address.

Best Practices

• Keep API keys server-side.
• Do not expose API keys in browser JavaScript.
• Validate email addresses before submitting leads.
• Do not disable SSL verification in production.
• Log response codes for troubleshooting.
• Confirm current API version requirements before adding an apiversion header.