Skip to main content

Optimize Your Inventory

IQM’s REST API enables you to interact with most of our platform's applications.

The following endpoints will be used to search Inventory, assign Campaign targeting, and create an Inventory group:

POST /api/v3/ua/login
GET /api/v3/inv/inventories/list
POST /api/v3/inv/groups
POST /api/v3/inv/group/addMappings
POST /api/v3/cmp/inventorygroups/{groupId}/includeExclude
GET /api/v3/inv/groups/api/v3/group/{groupId}/shared/campaigns/list

About IQM Inventory​

IQM's advanced algorithm determines the most relevant ads to display to a user based on their activity and the content of a given page. Inventories provide you a way to organize collections or groups based on criteria such as ad format, placement type, targeting options, and other properties.

Before You Begin​

To upload Matched Audience, the following are required:

  1. An Account On the IQM platform
    • See Getting Started section to create an account and request a Client ID and Client Secret
  2. A Campaign

Optimize Your Inventory Using the IQM API​

This Quickstart Guide will cover how to create and manage Inventory groups and target Inventory with Campaigns.

The minimum requirements to perform this task are: logging in with authentication credentials, selecting Inventory, assigning it to a Campaign, and creating an Inventory group. Once these steps are accomplished, more can be learned about IQM's API through the Guidelines pages.

  1. Log In
    • Optional if you have already logged in and have a token
  2. Search Inventory
    • Optional if you already have pre-selected Inventory to use
  3. Create an Inventory Group
    • Optional if you already have an existing Inventory group to use, skip to next step
  4. Update an Inventory Group
  5. Campaign Inventory Group Targeting
  6. Get Inventory Group Campaign Details

Step 1: 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), which is 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
X-IAA-HOST
string required		Workspace URL
Request Schema
grantType
string required		OAuth Grant Types
email
string required		User account email
password
string required		User account password
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."
      }
   ]
}

Step 2: Search Inventory List​

GET /api/v3/inv/inventories/list

Using a number of query fields, you can search the Inventory database. Try passing IAB22-4 as a categories query string. You should see results similar to the response sample code block on the right.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Query Parameters
keywords
string		Keywords to search Inventory list
countries
string		Filter by country
categories
string		Filter by category
inventoryTypes
string		Filter by Inventory type
creativeSizes
string		Filter by Creative size
creativeTypes
string		Filter by Creative type
creativeDurations
string		Filter by Creative duration
trafficTypes
string		Filter by traffic type
deviceTypes
string		Filter by device type
exchanges
string		Filter by exchange
videoPlayerSizes
string		Filter by video player size
noOfEntries
integer		Maximum number of entries per page
pageNo
integer		Number of pages for retrieved data
groupId
integer		Group ID

Response Properties
inventoryDataList
object		Inventory data details list
inventoryDataList object properties
id
integer		Inventory ID
name
string		Inventory name
publisher
string		Publisher
appId
string		The bundle ID (for app request) or domain (for web request)
inventoryType
string		Inventory type
impressions
integer		Impressions count
reach
integer		The number of unique individuals reached by an Inventory, does not count repeat views
videoPercentage
integer		Percentage of total ad impressions that are video-based
Response 200
{
  "success": true,
  "data": {
    "inventoryDataList": [
      {
        "id": 11593184,
        "name": "Baseball Clash: Real-time game iOS",
        "publisher": "UNKNOWN",
        "appId": "1491129492",
        "inventoryType": "IOS App",
        "impressions": 3123,
        "reach": 208,
        "videoPercentage": 5.891771,
        "displayPercentage": 94.108229
      },
      {
        "id": 11840144,
        "name": "Snake Clash.io",
        "publisher": "UNKNOWN",
        "appId": "6449243946",
        "inventoryType": "IOS App",
        "impressions": 2022,
        "reach": 133,
        "videoPercentage": 45.499505,
        "displayPercentage": 54.500495
      },
      ...
    ]
  }
}

Step 3: Create an Inventory Group​

POST /api/v3/inv/groups

[If you have an existing Inventory group and you want to update it, skip to Step 4]

The IQM API also allows you to create custom groupings of Inventories with several methods. In this example, we can take the Inventory ids used in Step 2 and pass it in the inventoryIds array, along with a groupName and groupTypeId to create a new group.

To review all the methods, see the Create a New Inventory Group endpoint documentation.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Request Schema
groupName
integer		Desired name for group
groupTypeId
integer		Group type. Supported values:
Open Exchange: 1
PMP: 2
Contextual: 3
inventoryIds
array of integers		Inventory IDs to include in group
Response Properties
groupTypeId
integer		Inventory Group Type ID
created
integer		Unix epoch creation date, in milliseconds
modifiedDate
integer		Modified date
owID
integer		Organization Workspace ID
impressions
integer		Impressions count
isAccountLevelExcluded
boolean		Indicates that account-level excluded group is included
whiteListedCampaignIds
array of integers		Campaign IDs where this Inventory group is whitelisted
blackListedCampaignIds
array of integers		Campaign IDs where this Inventory group is blacklisted
publishers
integer		Publishers count
uniques
integer		Total number of unique impressions of the Inventories in a group
reach
integer		The number of unique individuals reached by an Inventory group, does not count repeat views
deals
integer		Deals count
contextualInventories
integer		Contextual Inventories count
count
integer		Inventories count
id
integer		Inventory group ID
name
integer		Inventory group name
isShared
boolean		Indicates the Inventory group is shared from the Workspace: true
Request Sample
{
    "groupName": "Inventory Group - Open exchange",
    "groupTypeId": 1,
    "inventoryIds": [
        11593184,
        11840144
    ]
}
Response 200
{
    "success": true,
    "data": {
        "groupTypeId": 1,
        "created": 1719836234,
        "modifiedDate": "2024-07-01T12:17:20.295+0000",
        "owId": 201427,
        "impressions": 2334725782,
        "isAccountLevelExcluded": false,
        "campaignWhitelistCount": 0,
        "campaignBlacklistCount": 0,
        "whiteListedCampaignIds": [],
        "blackListedCampaignIds": [],
        "publishers": 56,
        "sharedCount": 0,
        "uniques": 0,
        "reach": 154976228,
        "inventories": 0,
        "deals": 0,
        "contextualInventories": 0,
        "count": 2,
        "id": 174594,
        "name": "Inventory Group - Open exchange",
        "isShared": false
    }
}

Step 4: Update an Inventory Group​

POST /api/v3/inv/group/addMappings

Add or Remove Inventories (Open Exchange, Private Deals, Contextual) to a group or multiple groups.

Inventories can be added/removed by filtering for results, inputting dealIds, contextual details, or inventoryIds.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Add/Remove by Inventory ID
Request Schema
groupIds
array of integers		Group IDs to add/remove mappings to/from
inventoryIds
array of integers		Inventory IDs to add/remove to/from group

Response Properties
groupTypeId
integer		Inventory Group Type ID
created
integer		Unix epoch creation date, in milliseconds
modifiedDate
integer		Modified date
owID
integer		Organization Workspace ID
impressions
integer		Impressions count
isAccountLevelExcluded
boolean		Indicates that account-level excluded group is included
whiteListedCampaignIds
array of integers		Campaign IDs where this Inventory group is whitelisted
blackListedCampaignIds
array of integers		Campaign IDs where this Inventory group is blacklisted
publishers
integer		Publishers count
uniques
integer		Total number of unique impressions of the Inventories in a group
reach
integer		The number of unique individuals reached by an Inventory group, does not count repeat views
deals
integer		Deals count
contextualInventories
integer		Contextual Inventories count
count
integer		Inventories count after add/remove mapping
id
integer		Inventory group ID
name
integer		Inventory group name
isShared
boolean		Indicates the Inventory group is shared from the Workspace: true
Response 200
{
    "success": true,
    "data": [
        {
            "groupTypeId": 1,
            "created": 1719983099,
            "modifiedDate": "2024-07-03T07:35:45.800+0000",
            "owId": 202017,
            "impressions": 7927783118,
            "isAccountLevelExcluded": false,
            "whiteListedCampaignIds": null,
            "blackListedCampaignIds": null,
            "publishers": 59,
            "sharedCount": 1,
            "uniques": 0,
            "reach": 558137549,
            "inventories": 0,
            "deals": 0,
            "contextualInventories": 0,
            "count": 2,
            "id": 176130,
            "name": "Open Exchange Inventories Group",
            "isShared": true
        }
    ]
}

Step 5: Campaign Inventory Group Targeting​

POST /api/v3/cmp/inventorygroups/{groupId}/includeExclude

Once an Inventory group has been created, you can attach it to a Campaign for targeting. Pass the Inventory groupId in the endpoint's path and the desired Campaign ID in the includedCampaigns field.

Path Parameter
groupId
integer		Inventory group ID
Request Schema
excludedCampaigns
string		Comma separated Campaign IDs to exclude targeting
includedCampaigns
string		Comma separated Campaign IDs to include targeting
Request Sample
{
  "campaignIds": "168622",
  "isExcluded": 0
}
Response 200
{
  "statusCode": 200,
  "responseObject": {
    "message": "Inventory Group excluded successfully."
  }
}

Step 6: Get List of Groups by Campaign​

GET /api/v3/inv/groups/api/v3/group/{groupId}/shared/campaigns/list

Once you have attached an Inventory group ID to a Campaign for targeting you can check that Inventory groupId with this endpoint. You should see the campaignId in the response.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Path Parameter
groupIdGroup ID
Response Properties
data
array of integers		List of Campaign IDs
Response 200
{
  "success": true,
  "data": [
    168622,
    286107,
    284229,
    287201,
    287202
  ]
}