IDX API Overview

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

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

Ancillary Keys

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.

  1. Increased hourly access limits. Three times the normal limit.
  2. Output preference override. The partner's output preferences override any settings that the client may have.
  3. Version preference override. Regardless of the API version selected in the client account the version used will be the preference set on the partner's account.

Request Headers

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
    • The value should always be application/x-www-form-urlencoded
    • This is a standard HTTP header and may be included automatically by some REST clients.
    • This is not strictly required for GET requests but is for PUT, POST, and DELETE requests. Including it for GET is considered a best practice.
  • accesskey required
    • As described above, this is the method of access control for the API.
    • This is a 22 character string that can be created in your account control panel.
  • ancillarykey optional
    • As described above, this allows development partners some additional options when accessing the API on behalf of their clients.
    • This is the same 22 character string that serves as the partner's access key.
    • Use is optional but there is no reason not to include it.
  • outputformat optional
    • Serves the same purpose as the output preference available in your account control panel.
    • Use ensures that output is always as expected in cases where the output preferences may change on the client or partner API key control page.
  • apiversion optional
    • Overrides the version preference set in your account control panel.
    • Use ensures that output is always as expected in cases where the output preferences may change on the client or partner API key control page.
    • Also useful when testing your code with different versions of the API.
    • If the specifed value is not a valid API version or if the version specified has been sunsetted then the API response will be made with the most current active version. As such, when using the apiversion header, it is always a good idea to compare the version you specify with the version given in the response header.

Response Headers

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.

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.

Choosing a Version

There are two ways to choose what version of the API will respond to your request.

  • Through preference.
    • As with the output format you can set the version that will be used via the API Key management page of your account profile.
    • If you are a development partner using your key as an ancillary key when accessing the API on behalf of one of your clients, then your version preference will supercede the version preference set in the client's account.
  • Through header.
    • You can optionally specify a version in your request header. This will override any version preference stored in a client or partner account.
    • This can be very useful when testing updates to your code when migrating to a new version of the API.
    • As noted elsewhere, if the specified value is not a valid API version, or if the version specified has been sunsetted, then the most current active version of the API will be used to respond. As such, when using the apiversion header it is always a good idea to compare the version you specify with the version given in the response header.

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.

New Versions

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:

https://api.idxbroker.com/component/method/primary request ID/secondary request ID?query string

  • component required
    • This is the main section of the API that is being accessed.
    • Current components include: partners, clients, mls, and leads
  • method required
    • This is a function of the component that is being accessed. For example you might access the cities method of the mls component in order to get a list of cities that currently have properties in them for a given MLS.
    • All components have the following two methods: listcomponents and listmethods
  • primary request ID conditional
    • This is required in certain circumstances to view or set specific information.
    • For example if you want to get information about a lead you would send the ID of the lead to view.
  • secondary request ID conditional
    • Similar to the primary request ID, there are methods that require two IDs to be passed in order to function.
    • For example to view a single search for a lead you would need to pass the lead ID as the primary request ID and the search ID as the secondary request ID.
  • query string conditional
    • Many GET requests offer filtering or specific views based on information passed in a standard, browser type, ampersand delineated query string following the URL.

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
						

General

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 outputformat headers.

Empty PUT/POST requests

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:

  • [field name] - The name of the field, i.e. the key in your key value pair that you will send via PUT or POST. E.g. firstName
    • explanitoryText - Very short (one to three words) decription of the field. If this were an HTML form this would be the content of the <label> tag.
    • required - If the value is required to be passed. 0 if no 1 for yes
    • maxLength - The maximum number of characters allowed.
    • dataType - The type of data allowed. Generally string or int
    • allowedCharacters - If blank this means no characters are restricted. Otherwise it will show allowed characters in a regex format. E.g. 0-9 means only integers are allowed.
    • defaultValue - What the default value should be if no further input is given.
    • choices - In the event that there are a set number of valid values this will contain all that are accepted. Otherwise it will be an empty object.
    • description - A One to Two sentence description of the field populated when the explainitoryText is ambiguous.

Response Codes

Below you find a list of all status codes currently returned by the API.

  • 200 - OK
  • 204 - OK, nothing returned. This is most common for DELETE requests.
  • 400 - Required parameter missing or invalid.
  • 401 - accesskey not valid or revoked.
  • 403.4 - URL provided is not using SSL (HTTPS).
  • 405 - Method requested is invlid. This usually indicates a typo or that you may be requested a method that is part of a different API component.
  • 406 - accesskey not provided
  • 409 - Invalid API component specified.
  • 412 - Account is over it's hourly access limit.
  • 500 - General system error. Please try again later or contact IDX support.
  • 503 - Scheduled or emergency API maintenance will result in 503 errors.
  • 521 - Temporary error. There is a possibility that not all API methods are affected.

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.

  • GET - Gets information from the IDX system. May accept output modifiers, such as filters, via query string.
  • PUT - Add a new record to the IDX system. Accepts record data via request body.
  • POST - Update an existing record in the IDX system. Accepts record data via request body.
  • DELETE - Remove a record from the IDX system.

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:

250 accesses per hour per accesskey

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 Hourly-Access-Key-Usage. A 412: Precondition Failed error from the API indicates that you have gone over your hourly limit.

The current API components are:
  • partners - used by development partner level accounts
  • clients - used by client level accounts
  • leads - used by client level accounts
  • mls - used by client level accounts
In each of the other component/api specific documents in this documentation you will find assorted code examples. These examples represent a minimum amount of code needed to work with each method. They may also require a different version of the given language from what you may have. To build a successful and robust client you will need to expand on this code.
Sept 16, 2013 - Version 1.0.4
Added aggregatedlistingstatus method 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.
Aug 8, 2013 - Version 1.0.4
Brought the property method in the leads API component up to spec with the search method by adding output of the created and lastEdited timestamps for saved properties.
July 8, 2013 - Version 1.0.4
Fixed bug that was not setting a page name for saved lead searches entered via the API. Input and output unchanged.
July 8, 2013 - Documentation
Fixed url in PHP example for PUTing saved searches in the leads component.
July 2, 2013 - Documentation
Removed extra call to urlencode in PHP examples on methods in the leads class which, if used verbatum, would result in double escaping and invalid email errors.
June 9, 2013 - Version 1.0.4
A change was made to correct a typo on saved map links URLs. Given that the data being returned was incorrect and the format of the data is not changed by this update it was decided that this patch would be made without creating a new version of the API.
  • Corrected URL output for saved map links in the savedlinks method of the clients component.
May 8, 2013 - Version 1.0.4
Support for API versioning is now in place. See the docs section on versions for details. There is currently only one version of the API version so you do not need to worry about changing any settings. Future development will lead to additional versions being available. No existing methods were altered in a way that changes input or output formats so no change in your code should be needed.
  • First verion set at 1.0.4
  • Version preference added to the middlewate API Key management page for clients and partners.
  • apiversion request header now supported to override preference setting
  • Headers returned as part of an API response now include Api-Version to show which version of the API responded to your request.
  • Enabled the aggregatedsupplemental method in the partners API method.
  • Fix: Bug causing the agent and office methods in the client API component to sometimes return no values.
  • Fix: Incorrectly labeled method in the navigation of the documentation for the mls API component. Read "price" when it should have read "prices".
  • Fix: Bug causing the age method of the mls component to error.
  • Fix: Added note to the docs for the age method that all dates and times are UTC.
  • Fix: Bug that was causing the default interval on the aggregatedleads, aggregatedsearches, and aggregatedproperties methods in the partners API component to say it was outside the allowed interval length.
Apr 3, 2013
Fixed JSON formatting bug that was causing arrays to be returned as objects in all output.