End-user documentation for the IDX RESTful API.
Access to the IDX API is handled through keys. These keys can be easily created, changed, and revoked in your IDX Control Panel. This is a measure of security that ensures that your account credentials and sensitive information are never exposed by the API.
Access keys grant access to API components. Different components are available to different account levels. These are detailed in the documentation for each component.
The key for the header is accesskey
When accessing APIs on behalf of their clients, Development Partners can use their own API keys as ancillary keys. Use of ancillary keys is completely optional but it grants the following extra functionality.
These are the headers sent by your client to the API. There are two required headers and three optional headers that must be sent with all requests. Exactly how these headers are sent depends on the programs and languages used in connecting to the API. Examples of header syntax are included in most code examples.
Content-Type required
application/x-www-form-urlencoded unless specified differently on the method.application/json.accesskey required
ancillarykey optional
outputtype optional
apiversion optional
These are the headers sent by the API to your client when a request has been completed. Not listed are the normal headers sent by the webserver such as Content-Length, Cache-Control, etc. For explanations of these headers please look up the HTTP specification for each.
Hourly-Access-Key-Usage
Shows the number of API access made by the current accesskey within the last hour. This value can be useful in making sure your systems do not go over the hourly access limit.
Api-Version
Shows the version number of the API that responded. This can be useful when used in conjunction with the version response header to insure your request was processed by the version requested.
Any API changes that have an effect on input or output will be made in discreet versions; methods used by your code will remain the same unless you explicitly change the version of the API that your system uses.
Versions will be semver style (e.g. 1.1.0) where the first digit represents the major release, the second digit represents the minor release, and the 3rd number represents bug fixes and new method additions which do not alter or break the output of any existing methods.
Following the full release of new versions of the API, previous versions will remain available in a deprecated state, although no new development will occur on them. A previous version will only be made unavailable (sunsetted) if it proves to be an unreasonable drain on resources, or if it violates MLS rules. If a version needs to be sunsetted, a minimum of 3 months notice will be given; specific functions may need to be altered or removed with less notice in instances of MLS rule violations.
There are two ways to choose what version of the API will respond to your request.
If you do not change API version with one of these options then the version that responds to your request will be the version that was default when your account was created.
When new major and minor releases of the API are developed, they will be available in a preview state for one month prior to being made the default version. Bug fixes and new (non-breaking) method additions will be represented by the 3rd digit in the version number without a preview period.
During the preview period the 3rd digit of the version number may change as bugs are fixed. Clients or partners using a preview version will be automatically upgraded to the new version and the previous preview version will cease to exist. At no other time will a client or partner's version preference be changed automatically, so you will only need to update your code if you choose to move to a new version of the API or choose to use a version in preview.
There is a standard URL structure for all API accesses. The structure is as follows:
https://api.idxbroker.com/component/method/primary request ID/secondary request ID?query string
component required
method required
cities method of the
mls component in order to get a list of cities that currently have properties in them for a given MLS.primary request ID conditional
secondary request ID conditional
query string conditional
All API inputs, whether in the query string or request body, must be in the form of an ampersand (&) delineated and URL encoded string.
idxID=a001&listingID=1234
or
note=this+is+a+url+enocoded+note+%26+string+with+%3Ctags%3E
Users can select between the default JSON encoded output and simple XML output. This can be set in the API Key management page of your account
control panel or by passing the optional outputtype headers.
Empty PUT and POST requests (on methods that support those actions) will return a description of the fields accepted by those methods and actions. The output is as follows:
<label> tag.0 if no 1 for yesstring or int0-9 means only integers are allowed.Below you find a list of all status codes currently returned by the API.
Each method inside an API component supports some or all of the following actions (verbs). The documentation of each
method will show which actions are supported. The listmethods method available in each component will also return
booleans indicating which actions are supported.
PUT and POST actions, when supported, will return a list of acceptable criteria/fields when a request is made without any data in the body. For specifics on what input is supported by each method please refer to the documentation specific to said method.
To encourage efficient API calls and to prevent abuse the API imposes an hourly limit on accesses. Based on existing web service usage patterns none of our current partners or developers would hit this limit under normal usage. By default this limit is:
Additionally, development partners using their API key as an ancillary key have triple this limit. Also note that this is a per accesskey limit, meaning that partners who service multiple client accounts have use of this limit per hour per client. Any client or partner who runs up against this limit can contact IDX support for tips on how to use the API fewer times per hour.
The current number of accesses in the current hour is sent in the response header of each request with the key Hourly-Access-Key-Usage.
A 412: Precondition Failed error from the API indicates that you have gone over your hourly limit.
// access URL and request method
$url = 'https://api.idxbroker.com/component/method/primary request ID/secondary request ID?query string'
Example:
'https://api.idxbroker.com/clients/savedlinks/1'
$method = (GET|PUT|POST|DELETE);
if ($method == 'PUT' || $method == 'POST') {
$data = array(fields to insert/update)
Example:
$data = array(
'linkName' => 'Good_side_of_tracks', // the link's url
'queryString' => array('idxID' => 'a001', 'hp' => 200000)
);
$data = http_build_query($data); // encode and & delineate
}
// headers (required and optional)
$headers = array(
'Content-Type: application/x-www-form-urlencoded', // required
'accesskey: abcdefghijklmnopqrstuvwx', // required - replace with your own
'outputtype: json' // optional - overrides the preferences in our API control page
);
// 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);
if ($method != 'GET') {
curl_setopt($handle, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($handle, CURLOPT_POSTFIELDS, $data);
}
// exec the cURL request and returned information. Store the returned HTTP code in $code for later reference
$response = curl_exec($handle);
$code = curl_getinfo($handle, CURLINFO_HTTP_CODE);
if ($code >= 200 || $code < 300) {
$response = json_decode($response,true);
} else {
$error = $code;
}