REST API Overview

The IQM platform uses standard REST API calls and responses for its applications. Our API has URLs organized by resource, supports form-encoded requests, returns JSON-encoded responses, and uses standard HTTP response codes.

Base URL

https://app.iqm.com

Review the following sections for the basic information on API specifications to avoid errors and workflow interruptions.

Prerequisites

The minimum requirements are: creating an account with IQM, running at least one Campaign, and attaining authentication to use the platform. Review the Getting Started page for details on these requirements before using the IQM API.

Once these steps are completed see the other Quickstart Guides and the Guidelines pages for a comprehensive overview of the IQM platform's API.

Authentication

The IQM API uses bearer authentication tokens to authenticate as well as an Organization Workspace ID (owId). Authentication is obtained on sign up and log in.

Refer to the Sign Up and Authenticate Quickstart Guide for more information.

HTTP Request Methods

Data resources are accessed via standard HTTP requests in UTF-8 format to an API endpoint. Refer to MDN Documentation on methods for more information.

The IQM API uses the following HTTP methods:

HTTP Methods
GET	Retrieves Resources
POST	Creates Resources
PUT	Changes or replaces resources
DEL	Deletes Resources
PATCH	Applies partial modification to a resource

GET Method

The GET method allows you to retrieve resources with the IQM API. Within each API you can retrieve details of individual objects, usually by querying their ID, lists of objects with filters, or static entities.

Many GET endpoints support queries to filter and sort the data (learn more by reviewing API Filtering and Pagination). Below are examples of common fields and a response sample for GET resources.

Common GET Fields

Fields	Description
success boolean	Indicates resource retrieval was successful: true
data object	Object containing retrieved resource data
id integer	Unique ID of entity
owId integer	Organization Workspace ID that owns the resource
name string	The name of a resource
startTime / endTime integer	The start and end times of a resource with a fixed period of activity (e.g. Campaigns, Insertion Orders), usually in unix epoch milliseconds
createdAt integer	The creation time of a resource, usually in unix epoch milliseconds
modifiedAt integer	The time of last modification of a resource, usually in unix epoch milliseconds
status string	The status of a resource, sometimes given as a type ID

GET Response Sample

Basic Campaign Details

{
  "success": true,
  "data": {
    "data": [
      {
        "campaignId": 273438,
        "name": "Campaign-1",
        "creativeTypeId": 11,
        "campaignTypeId": 1,
        "status": "deleted",
        "startTime": 1658217468,
        "endTime": 1658303868,
        "createdAt": 1658217469,
        "modifiedAt": 1661150517,
        "owId": 200002,
        "organizationName": "Organization-1",
        "organizationLogo": "https://iqm-web-assets-c92d6b6cbde1-stage.s3.amazonaws.com/avatar/SA.png",
        "ioId": 1,
        "ioStatusId": 1,
        "timezoneId": 11,
        "ioBudgetTypeId": 1,
        "ioName": "Name Insertion Order"
      }
    ]
  }
}

POST Method

The POST method allows you to create new resources with the IQM API. Every resource has a unique set of fields required to create it. These parameters are described in the API Guidelines for every endpoint.

In some cases, POST endpoints function like a GET endpoint, where the request schema takes API Filtering and Pagination parameters to sort the retrieved data.

Common POST Response Fields

Fields	Descriptions
success boolean	Indicates resource creation was successful: true
data / message string	Response message describing success or failure

POST Resource Example

POST /api/v3/ua/organization/advertiser/add

This endpoint creates a new Advertiser profile.

Request Schema
advertiserName string	Advertiser name
website string	Advertiser website
chiefName string	Name of political person, with respect to the Advertiser
contactNumber string	Advertiser phone number
address string	Advertiser address
legalInfo string	Legal info for Advertiser
links string	Associated links for Advertiser

Response Properties

success boolean	Indicates resource was created successfully: true
data string	Success message

Request Sample

{
  "advertiserName": "Nikon 1",
  "website": "http://nikonindia.com",
  "chiefName": "Nil Miles1",
  "contactNumber": "+91 9876534210",
  "address": "physical address",
  "legalInfo": "legal info for advertiser",
  "links": [
    "www.nikon1.com",
    "www.nikon1us.com"
  ]
}

Response 200

{
  "success": true,
  "data": "Advertiser profile added successfully."
}

PUT/PATCH Method

The PUT and PATCH methods allow you to update existing resources with the IQM API. Usually, PATCH endpoints partially update or modify the parameters of a resource whereas PUT endpoints change or replace a resource.

PUT/PATCH endpoints have the same common response fields as POST endpoints. Below is an example of a PATCH endpoint for a resource.

PATCH Resource Example

PATCH /api/v3/crt/creatives/groups/{creativeGroupId}

This endpoint updates a Creative group name. The path parameter is required to specify by ID which resource to update. The request schema includes the supported fields to update in that resource.

Path Parameters
creativeGroupId integer	Creative group ID

Request Schema
creativeGroupName string	Creative group name

Response Properties

success boolean	Indicates resource was updated successfully: true
message string	Success message

Request Sample

{
  "creativeGroupName": "Group1"
}

Response 200

{
  "success": true,
  "data": {
    "message": "Group1 group renamed successfully"
  }
}

DELETE Method

The DELETE method allows you to delete resources with the IQM API. DELETE endpoints have the same common response fields as POST endpoints. Below is an example of a PATCH endpoint for a resource.

DELETE Resource Example

DELETE /api/v3/ra/report/{reportId}

Delete a Report and its scheduling data by ID.

Path Parameters
reportId integer	Report ID

Response Properties

success boolean	Indicates Report was succesfully created: true
data string	Success message

Response 200

{
    "success": true,
    "data": "Report with id 123 deleted successfully"
}

Response Codes and Samples

IQM uses HTTP status codes. Please refer to MDN Documentation on status codes for more information.

API calls will return a JSON formatted response consisting of a success boolean and, often, a message, data, or error property describing the success or failure. Below is a table of common status codes and response samples.

Status Codes
200	OK
201	Created
400	Bad Request
403	Forbidden
408	Request Timeout
412	Precondition Failed
422	Unprocessable Entity
429	Too Many Requests
500	Internal Service Error

Response 200

{
  "success": true,
  "data": "PG deal Campaigns mappings updated successfully"
}

Response 422

{
  "success": false,
  "errorObjects": [
    {
      "error": "Campaign ID 506992 exceeds the maximum limit of 25 deals"
    }
  ]
}

Rate limits

The message rate limit is 20 requests per minute. Exceeding the limit will cause a 429 (too many requests) error.

The maximum data size per page is 1K rows.