Create a Deal

About IQM Deals

The Inventory API allows you to create and manage advertising deals. IQM offers two kinds of private deals:

• Private Marketplace (PMP) deals are a type of programmatic advertising arrangement that allows Advertisers to purchase ad Inventory through a private, invitation-only auction.
• Programmatic Gauranteed (PG) deals are a direct negotiation between one publisher and one Advertiser that offer budget predictability and avoid auction volatility by ensuring a fixed amount of ad Inventory at a pre-negotiated price.

More Resources

• Inventory API Guidelines
• Optimize Your Inventory Tutorial
• Ad Inventory and Placements Help Center article

Before You Begin

To create a deal, the following are required:

• An Account On the IQM platform
  • See Getting Started section to create an account and request a Client ID and Client Secret
• A Campaign
  • See Create a Campaign Quickstart Guide
  • See Create a PG Campaign Tutorial
  • Required for assigning a deal to a Campaign

Log In

POST /api/v3/ua/login

To log in, the Authentication: Basic header is required. The Login API returns an OAuth-compliant response with an Organization Workspace ID (owId), a unique identifier for each Organization. This ID will be used for any further API communications.

For further information see the complete Login API Documentation.

Headers
Authentication string required	Authentication bearer token See Authentication Guide

Request Schema
grantType string required	OAuth Grant Types
email string required	User account email
password string required	User account password

JSON

Request Sample

{
   "grantType": "password",
   "email": "pratik.t+ihp@iqm.com",
   "password": "123456"
}

Response 200

{
   "success": true,
   "data":
   {
      "access_token": "106adb25-37b0-4cab-8381-d682fe7cc3c8",
      "refresh_token": "eac4c1f6-781e-4b04-baff-9c2e415d1f64",
      "scope": "read write",
      "token_type": "bearer",
      "expires_in": 35999,
      "owId": 200001
   }
}

More Responses

Response 400

{
   "success": false,
   "data":
   {
      "status": "On Hold",
      "reason": "The particular account is kept on hold due to missed payment dates for last 3 months.",
      "supportEmail": "support@iqm.com"
   },
   "errorObjects":
   [
      {
         "error": "User is not allowed to access provided customer",
         "reason": "User is not associated with any active organization."
      }
   ]
}

Response 403

{
   "success": false,
   "errorObjects":
   [
      {
         "error": "User doesn't exist or user is not allowed to provided workspace."
      }
   ]
}

TypeScript

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          access_token: string;
          refresh_token: string;
          scope: string;
          token_type: string;
          expires_in: number;
          owId: number;
        };
      };
    };
  };
  400: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          status: string;
          reason: string;
          supportEmail: string;
        };
        errorObjects: {
          error: string;
          reason: string;
        }[];
      };
    };
  };
  403: {
    content: {
      "application/json": {
        success: boolean;
        errorObjects: {
          error: string;
        }[];
      };
    };
  };
};

function Login(): Promise < Responses > {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ua/login',
    requestBody: {
      content: {
        "application/json": {
          email: `string`,
          password: `string`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Authentication

Use the following header parameters for all requests after logging in:

Headers
Authentication string required	Authentication bearer token See Authentication Guide
X-IAA-OW-ID integer required	Organization Workspace ID Header

Request Exchange List

GET /api/v3/master/exchanges

To create a PG or PMP deal, an exchange must be provided. Use the master exchange endpoint to get a list of available exchanges.

Query Parameters
pageNo integer	Page number for the required data, default: 1
noOfEntries integer	The maximum number of returned results per page, default: 300
sortBy string	Sort the result set by specific field. For ascending use plus(+) sign and for descending use minus(-) sign, default: +id
searchField string	Search the result by provided keyword in the searchField, search country records by name
ids array of integers	Selected country ID List, countries with provided IDs will be returned first compared to other records
exchangeIds array of integers	Filters for Exchange IDs

JSON

Response 200

{
  "success": true,
  "data": {
    "data": [
      {
        "id": 90,
        "name": "Aniview",
        "urlName": "aniview"
      },
      {
        "id": 89,
        "name": "LoopMe",
        "urlName": "loopme"
      },
      {
        "id": 88,
        "name": "One Tag",
        "urlName": "onetag"
      },
      {
        "id": 87,
        "name": "Share Through",
        "urlName": "sharethrough"
      },
      {
        "id": 84,
        "name": "Vidazoo",
        "urlName": "vidazoo"
      },
      {
        "id": 80,
        "name": "Equativ",
        "urlName": "equativ"
      },
      {
        "id": 78,
        "name": "Magnite",
        "urlName": "magnite"
      },
      {
        "id": 77,
        "name": "Verve",
        "urlName": "verve"
      },
      {
        "id": 76,
        "name": "Infolink",
        "urlName": "infolink"
      },
      {
        "id": 75,
        "name": "Beachfront",
        "urlName": "beachfront"
      },
      {
        "id": 74,
        "name": "Teads",
        "urlName": "teads"
      },
      {
        "id": 73,
        "name": "Outbrain",
        "urlName": "outbrain"
      },
      {
        "id": 72,
        "name": "Telaria",
        "urlName": "telaria"
      },
      {
        "id": 71,
        "name": "33 Across",
        "urlName": "ttacross"
      },
      {
        "id": 69,
        "name": "Media.net",
        "urlName": "mnet"
      },
      {
        "id": 66,
        "name": "Unruly",
        "urlName": "unruly"
      },
      {
        "id": 47,
        "name": "Index Exchange",
        "urlName": "indexch"
      },
      {
        "id": 46,
        "name": "Triton Digital",
        "urlName": "tdigital"
      },
      {
        "id": 45,
        "name": "Publisher Direct",
        "urlName": "pbd"
      },
      {
        "id": 41,
        "name": "Column6",
        "urlName": "adigital"
      },
      {
        "id": 39,
        "name": "Google DoubleClick",
        "urlName": "adx"
      },
      {
        "id": 37,
        "name": "SpotXchange",
        "urlName": "spotx"
      },
      {
        "id": 19,
        "name": "OpenX",
        "urlName": "openx"
      },
      {
        "id": 16,
        "name": "Pubmatic",
        "urlName": "pubmatic"
      },
      {
        "id": 11,
        "name": "Smaato",
        "urlName": "smaato"
      },
      {
        "id": 1,
        "name": "iQM",
        "urlName": "test"
      }
    ],
    "totalRecords": 26,
    "filteredRecords": 26
  }
}

TypeScript

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          data: {
            id: number;
            name: string;
            urlName: string;
          }[];
          totalRecords: number;
          filteredRecords: number;
        }
      }
    };
  };
};

function getExchanges(): Promise < Responses > {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/master/exchanges',
    params: {
      query?: {
        exchangeIds?: `string`,
        ids?: `string`,
        pageNo?: `number`,
        noOfEntries?: `number`,
        sortBy?: `string`,
        order?: `string`,
        searchField?: `string`,
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Create a PG Deal

POST /api/v3/inv/pg/deals/add

Once an exchange id is selected, pass it in the exchangeId field to create a PG deal.

Request Schema
dealId string	PG deal ID
dealName string	PG deal name
exchangeId integer	Exchange ID associated with PG deal
cpm integer	Cost Per Mille (CPM) value
statusId integer	Status ID of PG deal Active: 1 Inactive: 2
description string	Description or notes about the deal
paymentTypeId integer	Payment type ID 2: platform-based payment

JSON

Request Sample

{
    "dealId": "YT-Test-1234",
    "dealName": "Test deal YT31",
    "exchangeId": 11,
    "statusId": 2,
    "paymentTypeId": 1,
    "description": "Test Deal"
}

Response 200

{
    "success": true,
    "data": {
        "message": "Deal Test deal YT31 created successfully",
        "id": 2
    }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          message: string;
          id: number;
        }
      }
    };
  };
}

function addPGDeal(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/inv/pg/deals/add',
    requestBody: {
      content: {
        "application/json": {
          dealId: `string`
          dealName: `string`,
          exchangeId: `number`,
          statusId: `number`,
          description?: `string`,
          paymentTypeId?: `number`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Create a PMP Deal

POST api/v3/inv/pmp/deals/add

Once an exchange id is selected, pass it in the exchangeId field to create a PMP deal.

tip

Consider creating a PMP Inventory group if you plan to target or block the same group of PMP deals across multiple Campaigns. See the Optimize Your Inventory Tutorial for step-by-step instructions.

Properties
dealId string	PMP deal ID
dealName string	PMP deal name
description string	PMP deal description
cpm integer	PMP deal Cost Per Mille (CPM) value
dealCurationTypeId integer	Curation Type ID
creativeTypes array of integers	Creative type IDs
exchangeId integer	Exchange associated with PMP deal
assignToCustomers array of integers	Customer Organization Workspace IDs
active boolean	Deal status, active (true) or inactive (false)

Response Properties

id integer	PMP deal ID
message string	Success message

JSON

Request Sample

{
    "dealId": "DIewkFZALX1taoLjQg6Gge1dD6YvZYO4RChUKmOLk",
    "dealName": "Deal test123",
    "description": "test deal description",
    "cpm": 10,
    "creativeTypes": [
        11,
        12
    ],
    "exchangeId": 39,
    "active": true
}

Response 200

{
    "success": true,
    "data": {
        "id": 461,
        "message": "Deal test123 created successfully"
    }
}

More Responses

Response 400

{
    "success": false,
    "errorObjects": [
        {
            "error": "Deal id can not be longer than 500 characters",
            "field": "dealId"
        }
    ]
}

Response 422

{
    "success": false,
    "errorObjects": [
        {
            "error": "Invalid exchange id/ids provided"
        }
    ]
}

Response 500

{
    "success": false,
    "errorObjects": [
        {
            "error": "server encountered an error !"
        }
    ]
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          id: number;
          message: string;
        }
      }
    };
  };
  400: {
    content: {
      "application/json": {
        success: boolean;
        errorObjects: {
          error: string;
          field: string;
        }[];
      }
    };
  };
  422: {
    content: {
      "application/json": {
        success: boolean;
        errorObjects: {
          error: string;
        }[];
      }
    };
  };
  500: {
    content: {
      "application/json": {
        success: boolean;
        errorObjects: {
          error: string;
        }[];
      }
    };
  };
}

function addPMPDeal(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/inv/pmp/deals/add',
    requestBody: {
      content: {
        "application/json": {
          dealId: `string`,
          dealName: `string`,
          description?: `string`,
          cpm?: `number`,
          dealCurationTypeId?: `number`,
          creativeTypes?: `array of numbers`,
          exchangeId: `number`,
          assignToCustomers?: `array of numbers`,
          active: `boolean`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Assign Deals to a Campaign

PATCH /api/v3/cmp/pg/campaigns/mappings
PATCH /api/v3/cmp/pmp/campaigns/mappings

Deals can be assigned or removed to/from Camapaigns. PG deals may only be assigned to PG Campaigns; and PMP deals may only be assigned to Advanced Campaigns.

Request Schema
operations array	Operations specifying the action, Campaign IDs and PMP deal IDs
action string	Action to perform: assign or deassign
campaignIds array of integers	Campaign IDs to assign deals or remove deals from
pmpDealIds array of integers	PMP deal IDs to assign/remove to/from Campaigns
pgDealIds array of integers	PG deal IDs to assign/remove to/from Campaigns

Response Properties

success boolean	Indicates Deals were assigned succesfully: true
data string	Success message

JSON

Request Sample

{
  "operations": [
     {
      "action": "assign",
      "campaignIds": [
        201,
        203
      ],
      "pmpDealIds": [
        101,
        102
      ]
    },
    {
      "action": "deassign",
      "campaignIds": [
        202
      ],
      "pmpDealIds": [
        102
      ]
    }
  ]
}

Response 200

{
  "success": true,
  "data": "PMP deal campaign mappings updated successfully"
}

More Responses

Response 403

{
  "success": false,
  "errorObjects": [
    {
      "error": "Forbidden!"
    }
  ]
}

Response 422

{
  "success": false,
  "errorObjects": [
    {
      "error": "PMP deal id/s is/are invalid or not accessible for logged-in user"
    }
  ]
}

TypeScript

See TypeScript Prerequisites for usage.

PMP–Campaign mapping

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success?: boolean;
        errorObjects?: {
          error?: string;
          reason?: string;
          field?: string;
        }[];
        data?: Record<string, never>;
      };
    };
  };
  403: {
    content: {
      "application/json": {
        success?: boolean;
        errorObjects?: {
          error?: string;
          reason?: string;
          field?: string;
        }[];
        data?: Record<string, never>;
      };
    };
  };
  422: {
    content: {
      "application/json": {
        success?: boolean;
        errorObjects?: {
          error?: string;
          reason?: string;
          field?: string;
        }[];
        data?: Record<string, never>;
      };
    };
  };
}

function managePMPDealCampaignMappings(): Promise<Responses> {
  const options = {
    method: 'PATCH',
    url: 'https://app.iqm.com/api/v3/cmp/pmp/campaigns/mappings',
    requestBody: {
      content: {
        "application/json": {
          operations: [
            {
              action: `string`,
              campaignIds: `array of numbers`,
              pmpDealIds: `array of numbers`,
            }
          ]
        }
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

PG–Campaign mapping

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success?: boolean;
        errorObjects?: {
          error?: string;
          reason?: string;
          field?: string;
        }[];
        data?: Record<string, never>;
      };
    };
  };
  403: {
    content: {
      "application/json": {
        success: boolean;
        errorObjects: {
          error: string
        }
      }
    };
  };
  422: {
    content: {
      "application/json": {
        success?: boolean;
        errorObjects?: {
          error?: string;
          reason?: string;
          field?: string;
        }[];
        data?: Record<string, never>;
      };
    };
  };
}

function managePgDealCampaignMappings(): Promise<Responses> {
  const options = {
    method: 'PATCH',
    url: 'https://app.iqm.com/api/v3/cmp/pg/campaigns/mappings',
    requestBody: {
      content: {
        "application/json": {
          operations: [
            {
              action: `string`,
              campaignIds: `array of numbers`,
              pmpDealIds: `array of numbers`,
            }
          ]
        }
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Get List of Deals Associated with Campaigns

GET /api/v3/cmp/campaigns/{campaignTypeId}/deals

Get a list of Campaigns and their associated deal IDs by Campaign Type ID.

Path Parameter
campaignTypeId integer	Campaign Type ID 1: Advanced 2: PG

Response Properties

data object

Name-Value pairs of campaignId and an array of deal IDs

JSON

Response 200

{
  "success": true,
  "data": {
    "503584": [
      468,
      469,
      23
    ],
    "503947": [
      468,
      469
    ],
    "504447": [
      468,
      469
    ],
    "504448": [
      589,
      588
    ],
    "505743": [
      468,
      469
    ],
    "505753": [
      468,
      469
    ],
    "505754": [
      468,
      469
    ],
    "505755": [
      588,
      589
    ],
    "505758": [
      468,
      469
    ]
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success?: boolean;
        errorObjects?: {
          error?: string;
          reason?: string;
          field?: string;
        }[];
        data?: Record<string, never>;
      };
    };
  };
}

function getDealsPerCampaign(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/cmp/campaigns/{campaignTypeId}/deals',
    params: {
      path: {
        campaignTypeId: `number`
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}