API Request and Response Headers

Every API call will need to use a few required request headers to successfully connect to the IDX Broker API. Each successful call will send back some useful information in the response headers.

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.

  • 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.
  • accesskey REQUIRED
    • The method of access control for the API.
    • This is a 22 character string that can be created in your Client account dashboard.
  • ancillarykey OPTIONAL
    • This allows Developer 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 found in the Developer Partner dashboard.
  • outputtype 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 specified 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.

PHP Example with all header required and optional headers:

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 accesses 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.

Status Codes:

Status codes are returned with every API call. They can quickly tell you if the call was a success or was in error.

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 – IP blocked
  • 403.4 – URL provided is not using SSL (HTTPS).
  • 404 – Invalid API component specified.
  • 405 – Method requested is invalid. 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 – Duplicate unique data detected.
  • 412 – Account is over it’s hourly access limit.
  • 413 – Requested entity too large.
  • 416 – Requested time range not satisfiable.
  • 417 – There are more saved links in the account than allowed through the API.
  • 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.