1. API REFERENCE
  2. >
  3. API Reference

Overview

iQmetrix APIs are simple but powerful HTTP interfaces that are inspired by the REST architectural style. These are the same APIs that our internal development teams use to build products.

We are passionate about creating a great developer experience for you so please don’t hesitate to contact our API Support Team with any feedback related to API design, usability, or features that you are interested to see.

What’s New

Non-breaking changes, developer portal upgrades, and bugfixes are communicated through the Changelog.

API List

Partner API List

These APIs are primarily used by iQmetrix Partners as part of the iQmetrix Dropship or Vendor Inventory programs.

Onboarding Package

As part of the onboarding process, you will receive an onboarding package from the iQmetrix API team. This package provides you with credentials required to access iQmetrix APIs.

Authentication

iQmetrix APIs use OAuth2 for authentication, and all requests must be made over HTTPS . When using our APIs, your account must be authenticated by including an AccessToken in the header of all API requests. Requests made over plain HTTP or without authentication will fail.

To learn more about authentication, see Obtaining an Access Token.

API Status

Most iQmetrix APIs provide a convenience “ping” endpoint you can use to determine the status of an API. This endpoint will be located at either {URL}/v1/ping or {URL}/ping.

Example Request
GET https://catalogsrc.iqmetrix.net/ping 
Authorization: Bearer (Access Token)
Example Response
HTTP 200
{
  "ApplicationVersion": "2.0.0.1155",
  "DbVersion": 17
}

Environments

iQmetrix APIs are provisioned into environments that let you start developing and testing integrated solutions quickly and easily.

Production

The production environment allows you to use your integrated solutions once deployed.

Sandbox

The sandbox environment allows you to develop and test integrated solutions or try out new features of iQmetrix APIs without compromising data in your production environment. API calls in the Sandbox environment are free of charge and will not affect your billing. Sandbox environments will be provisioned with tenant-specific test data.

Rate Limiting

Requests to the iQmetrix APIs are limited to help to manage server load, ensuring that high API request volumes do not impact overall performance. They also help to protect from deliberate or accidental denial of service as a result of APIs being flooded with requests.

Rate Limit Policies

All rate limits are applied per service, not aggregated across all services. Three rate limit policies are applied to the APIs:

Authenticated Limit

The Authenticated Limit policy determines how many Authenticated Requests can be made during the Rate Limit Window. Authenticated Requests are made to iQmetrix APIs that require authentication, and include an AccessToken in the HTTP Header. To determine the limit, make an Authenticated Request to an iQmetrix API, then check the X-RateLimit-Limit HTTP Header of the response.

Anonymous Limit

The Anonymous Limit policy determines how many Anonymous Requests can be made during the Rate Limit Window. Anonymous Requests are made to iQmetrix APIs that do not require authentication. To determine the limit, make an Anonymous Request to an iQmetrix API, then check the X-RateLimit-Limit HTTP Header of the response.

Rate Limit Window

The Rate Limit Window policy determines when the current rate limit will be reset. To determine the limit, make a request to an iQmetrix API, then check the X-RateLimit-Reset HTTP Header of the response.

HTTP Headers

All responses from the iQmetrix API’s have the following headers, which provide information about how many requests are remaining.

Header Name Description
X-RateLimit-Limit The maximum number of requests allowed in the current rate limit window
X-RateLimit-Remaining The number of requests remaining in the current rate limit window
X-RateLimit-Reset The time when the rate limit window will reset in UTC
X-RateLimit-ResetSeconds The number of seconds until the rate limit resets

Checking a Rate Limit

To determine the Authenticated Rate Limit for an API, make an authenticated request to the API and check the HTTP headers in the response.

In the example below, a request is made to the Customers API with a valid AccessToken in the Authorization header.

Example Request
GET https://crmrc.iqmetrix.net/v1/Companies(14146)/Customers
Authorization: Bearer (Access Token)
Accept: application/json
Example Response
HTTP 200 Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 2016-02-25T13:00:00.0000000Z
X-RateLimit-ResetSeconds: 59
{
    ...
}

Looking at the HTTP headers in the response, we can determine:

Exceeding Rate Limit

If the rate limit is exceeded, the response will be 429 Too Many Requests and the service will not be able to make further requests until the quota resets.

Example
HTTP/1.1 429 Too Many Requests
Content-Type: text/plain
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2015-04-16T17:46:00.0000000Z
X-RateLimit-ResetSeconds: 59
  
rate limit exceeded

Supported Response Formats

Most iQmetrix APIs support the json and hal+json response formats depending on the type of request. Documentation for each individual API will explicitly state which response formats are supported.

When sending an API request, you can select the format to return by defining the value in the HTTP Accept header, using the syntax Accept: {ResponseFormat}.

Example
Accept: application/json

Versioning

The API version is shown in the endpoint’s URL (e.g. /v1). Newer API versions will be highlighted in their respective API reference documentation.

Should there be a breaking change to an existing API, iQmetrix will trigger a release of a newer version and notify stakeholders. Please take note that not all API versions will be backward compatible.