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
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.
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.
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.
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.
Following the release of a new version 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 versions of the API are developed they will be available in a preview state for one month prior to being made the current active version. Minor changes to input and output may occur while the version is in this state. At no 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.
There is a standard URL structure for all API accesses. The stucture is as follows:
primary request ID/
secondary request ID?
citiesmethod of the
mlscomponent in order to get a list of cities that currently have properties in them for a given MLS.
primary request IDconditional
secondary request IDconditional
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
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:
0-9means 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 efficent 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 (750). Also note that this is a per accesskey limit, meaning that partners who service multiple client accounts have use of 750 accesses per hour per client. Any client or partner who runs up against this limit can contact IDX support to see about having their limit increased or 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
412: Precondition Failed error from the API indicates that you have gone over your hourly limit.
aggregatedlistingstatusmethod to the partners api component. This method allows a partner to gather a listing status for all listings for all their clients including those in an unknown status not normally available to other sold/pending listing methods.
apiversionrequest header now supported to override preference setting
Api-Versionto show which version of the API responded to your request.