Overview

The IDX Broker API allows developers to securely interact with IDX Broker account data using RESTful API requests.

This guide introduces:

• Making your first API call
• Understanding RESTful methods
• API authentication
• API limitations
• API consumption best practices

If you are new to APIs, this lesson is designed to help you successfully complete your first IDX Broker API request.

What Is the IDX Broker API?

An API (Application Programming Interface) allows applications to communicate and exchange data programmatically.

The IDX Broker API follows a RESTful architecture using standard HTTP request methods.

Supported Request Methods

Not every API endpoint supports all four methods.

Important API Limitations

The IDX Broker API does not provide:

• MLS-wide property details
• MLS search querying
• Raw MLS database exports
• Property retrieval by MLS ID

The only listing data available through the API is:

• Featured Listings
• Listings belonging to the agent(s) on the IDX Broker account

These restrictions exist to maintain MLS compliance and data security.

API Rate Limits

API usage is rate limited.

Some API lessons reference older limits of:

• 250 requests/hour
• 125 requests/hour for Lite accounts

Developers should always budget API usage carefully.

Authentication

IDX Broker uses API keys for authentication.

API keys are passed in the request headers.

API keys can be found within active IDX Broker accounts.

Making Your First API Call

Example Endpoint

The following endpoint retrieves available API components:

https://api.idxbroker.com/clients/listcomponents

Example PHP cURL Request

<?php

// access URL and request method
$url = 'https://api.idxbroker.com/clients/listcomponents';
$method = 'GET';

// headers
$headers = array(
    'Content-Type: application/x-www-form-urlencoded',
    'accesskey: abcdefghijklmnopqrstuvwx',
    'outputtype: json'
);

// set up cURL
$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_SSL_VERIFYHOST, false);
curl_setopt($handle, CURLOPT_SSL_VERIFYPEER, false);

// execute request
$response = curl_exec($handle);

$code = curl_getinfo($handle, CURLINFO_HTTP_CODE);

if ($code >= 200 || $code < 300) {

    //$response = json_decode($response, true);

} else {

    $error = $code;

}

print_r($response);

?>

Expected JSON Response

[
  {
    "component": "clients",
    "level": "client",
    "enabled": "y"
  },
  {
    "component": "leads",
    "level": "client",
    "enabled": "y"
  },
  {
    "component": "mls",
    "level": "client",
    "enabled": "y"
  }
]

Key API Requirements

HTTPS Is Required

All IDX Broker API requests must use HTTPS.

If your hosting environment does not support HTTPS, API calls will fail.

Store API Responses

API calls should not occur on every page load.

Recommended storage methods include:

• Databases
• Cached files
• JSON files
• TXT files

Caching responses reduces API usage and improves performance.

Consuming Lead Data

Overview

Lead data contains visitor information captured by IDX Broker websites.

This may include:

• Contact information
• Registration data
• Saved searches
• Traffic history
• Property activity

Lead data is commonly integrated into CRMs and marketing systems.

Lead API Endpoint

https://api.idxbroker.com/leads/lead

Recent leads are returned by default.

Example Lead Response

[
  {
    "id": "216",
    "firstName": "Bruce",
    "lastName": "Wayne",
    "email": "bats@test.com",
    "phone": "555-bat-phone",
    "city": "Gotham",
    "country": "USA"
  }
]

Retrieve a Specific Lead

Append the lead ID to the endpoint.

Example

https://api.idxbroker.com/leads/lead/3

Lead IDs are also used when retrieving:

• Saved properties
• Saved searches
• Traffic history

Lead Polling Best Practices

Polling the API every second is discouraged.

Recommended behavior:

• Poll every 5 minutes
• Trigger polling after lead notification emails
• Budget API usage carefully

Filtering Leads by Time Interval

Example

https://api.idxbroker.com/leads/lead?interval=1

This returns leads created within the last hour.

Adding Leads via PUT Requests

Important Email Requirement

Lead email addresses must:

• Be properly formatted
• Have valid MX records

Invalid email addresses commonly trigger server errors.

Example PUT Lead Request

<?php

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

$data = array(
  'firstName' => 'IDX',
  'lastName' => 'Robot',
  'email' => 'IDXRobot@example.com'
);

$data = http_build_query($data);

$headers = array(
  'Content-Type: application/x-www-form-urlencoded',
  'accesskey: ' . $apiKey,
  'outputtype: json',
  'apiversion: 1.4.0'
);

$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_SSL_VERIFYHOST, false);
curl_setopt($handle, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($handle, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($handle, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($handle);

$code = curl_getinfo($handle, CURLINFO_HTTP_CODE);

if ($code >= 200 || $code < 300) {

    $response = json_decode($response, true);

} else {

    $error = $code;

}

?>

Consuming Featured Listing Data

Overview

Featured Listings are listings belonging to agents associated with the IDX Broker account.

Featured data may include:

• Addresses
• Photos
• Latitude/Longitude
• Remarks
• Property details
• Open house information

Featured data is often consumed by:

• CRMs
• WordPress integrations
• Marketing systems
• Listing syndication tools

Featured Listings Endpoint

https://api.idxbroker.com/clients/featured

Common Featured Listing Fields

API Versioning

Semantic Versioning

IDX Broker uses semantic versioning.

Version Structure

MAJOR.MINOR.PATCH

Breaking Changes

Minor version updates may contain breaking changes.

Example:

• 1.0.4
• 1.1.1

may return different default outputs for identical API calls.

Patch versions generally contain non-breaking updates.

API Version Preview Period

New API versions are placed into preview status for approximately one month before becoming the default version.

During preview:

• Minor adjustments may occur
• Existing integrations are not automatically updated

Deprecated Versions

Older versions remain available unless:

• They create unreasonable system overhead
• MLS rule changes require deprecation

IDX Broker provides a minimum of 3 months notice before sunsetting versions whenever possible.

Retrieving the Current API Version

Available as of API version 1.2.0.

Endpoint

https://api.idxbroker.com/clients/apiversion

Request Headers

Required Headers

All API requests must include:

Required Content-Type

application/x-www-form-urlencoded

Optional Headers

Ancillary Key Benefits

Using a Partner-level ancillarykey with a client API key increases API limits to:

• 750 requests/hour

Response Headers

Example response headers:

HTTP/1.1 200 OK
Api-Version: 1.2.1
Content-Type: text/html
Hourly-Access-Key-Usage: 2

Useful Response Information

Common HTTP Status Codes

API Best Practices

Recommended Practices

• Use HTTPS for all requests
• Cache API responses
• Budget API calls carefully
• Poll APIs responsibly
• Test API version changes before deployment
• Specify output type explicitly
• Avoid excessive real-time polling

Key Takeaways

• IDX Broker uses a RESTful API architecture.
• MLS-wide listing data is not exposed via the API.
• Featured Listings are the only listing data available.
• HTTPS is required for all API requests.
• Authentication is handled through request headers.
• API rate limits should always be considered during development.
• Semantic versioning may introduce breaking changes between minor versions.