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
PUTrequest 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:
| Field | Description |
|---|---|
firstName | Lead first name |
lastName | Lead last name |
email | Lead email address |
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
apiversionheader.