Skip to main content

Inventory API

The Inventory API also allows you to create and manage advertising deals and inventory groups.

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 Advertisers a way to organize collections or groups based on criteria such as ad format, placement type, targeting options, and other properties. These are the main entities:

  • 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 Guaranteed (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.
  • Inventory groups are a collection or grouping of inventory sources categorized by specific criteria such as ad format, placement type, targeting options, or other properties. There are four types of inventory group: Open Exchange, PMP deals, Contextual inventory, and CTV.
  • CTV inventories are app-based inventory sources available on smart TVs and streaming devices, and can be filtered or grouped by streaming device.

This page will cover common methods and endpoints associated with the Inventory API.

More resources​

Authentication​

Use the following header parameters for all requests:

Headers
Authentication
string required		Authentication bearer token.
See Sign up and authenticate.
X-IAA-OW-ID
integer required		Organization Workspace ID header.

Get inventory details​

Use the following endpoints to get details for inventories, filtered by query parameters:

Query parameters
keywords
string		Keywords to search inventory list.
countries
string		Filter by country ID.
categories
string		Filter by IAB category ID.
inventoryTypes
string		Filter by inventory group type.
creativeSizes
string		Filter by creative size ID.
creativeTypes
string		Filter by creative type ID.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
creativeDurations
string		Filter by creative duration ID.
trafficTypes
string		Filter by traffic type ID.
Supported values
11App
14CTV
13OTT
12Web
deviceTypes
string		Filter by device type ID.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
exchanges
string		Filter by exchange ID.
videoPlayerSizes
string		Filter by video player size ID.
noOfEntries
integer		Number of entries returned per page.
pageNo
integer		Page number of retrieved data.
groupId
integer		Filter by group ID.

Get list of inventories​

GET

Get a list of inventories available to the user.

An inventory id can be used to perform various actions in Inventory management endpoints.

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": 3510,
        "name": "Test Inv 1234",
        "publisher": "UNKNOWN",
        "appId": "INVENTORY",
        "inventoryType": "Other App",
        "impressions": 7397885,
        "reach": 5257,
        "videoPercentage": 100,
        "displayPercentage": 0
      },
      {
        "id": 4746,
        "name": "Test Old TV 345",
        "publisher": "UNKNOWN",
        "appId": "INVENTORY",
        "inventoryType": "Other App",
        "impressions": 428882,
        "reach": 31291,
        "videoPercentage": 100,
        "displayPercentage": 0
      }
    ]
  }
}

Get inventory distribution​

GET

Get distributions of inventory available for the user across country and other parameters.

Response properties
countries
object		List of countries and distribution values.
trafficTypes
object		List of traffic type IDs and distribution values.
Supported values
11App
14CTV
13OTT
12Web
creativeTypes
object		List of creative types and distribution values.
deviceTypes
object		List of device types and distribution values.
object properties
label
string		Label.
value
integer		Value.
Response 200
{
  "success": true,
  "data": {
    "countries": [
      {
        "label": "United States",
        "value": 90.58
      },
      {
        "label": "Brazil",
        "value": 1.23
      },
      {
        "label": "Germany",
        "value": 0.79
      },
      {
        "label": "France",
        "value": 0.75
      },
      {
        "label": "United Kingdom",
        "value": 0.62
      }
    ],
    "trafficTypes": [
      {
        "label": "App",
        "value": 62.85
      },
      {
        "label": "Web",
        "value": 37.15
      }
    ],
    "creativeTypes": [
      {
        "label": "Video",
        "value": 47.47
      },
      {
        "label": "Banner",
        "value": 40.96
      },
      {
        "label": "Native",
        "value": 6.38
      },
      {
        "label": "Audio",
        "value": 5.19
      }
    ],
    "deviceTypes": [
      {
        "label": "Mobile",
        "value": 43.53
      },
      {
        "label": "Connected TV",
        "value": 37.69
      },
      {
        "label": "Desktop",
        "value": 15.08
      },
      {
        "label": "Tablet",
        "value": 3.57
      },
      {
        "label": "Unknown",
        "value": 0.13
      }
    ]
  }
}

Get inventories count​

GET

Get count of unique inventories, unique publishers, total number of impressions, and total reach of all inventories.

Response properties
reach
integer		The number of unique individuals reached by an inventory, does not count repeat views.
publishers
integer		Publishers count.
impressions
object		Impressions count.
inventories
object		Inventories count.
Response 200
{
  "success": true,
  "data": {
    "reach": 7983863253,
    "publishers": 2010,
    "impressions": 119273056646,
    "inventories": 1387184
  }
}
More responses
Response 403
{
  "success": false,
  "errorObjects": [
    {
      "error": "User is not allowed to access provided Inventory group."
    }
  ]
}

Get inventory group types​

GET

Get list of inventory group types.

Response properties
inventoryGroupTypeList
integer		Inventory group type list details.
inventoryGroupTypeList object properties
name
string		Inventory group name.
id
integer		Inventory group ID.
order
integer		Order.
Response 200
{
    "success": true,
    "data": {
        "inventoryGroupTypeList": [
            {
                "name": "Open Exchange",
                "id": 1,
                "order": 1
            },
            {
                "name": "CTV",
                "id": 4,
                "order": 2
            },
            {
                "name": "PMP",
                "id": 2,
                "order": 3
            },
            {
                "name": "Contextual",
                "id": 3,
                "order": 4
            }
        ],
        "totalRecords": 4,
        "filteredRecords": 4
    }
}

Inventory management​

Optimize inventories for specific campaigns, or download detailed inventory files.

Campaign inventory targeting​

POST

Include or exclude inventories for campaign targeting.

Request schema
campaignId
integer		Campaign ID to target for optimization.
ids
string		Comma separated strings of inventory IDs to include in or exclude from specified campaign.
isExcluded
integer		Include in campaign: 0.
Exclude from campaign: 1.
Response properties
message
string		Success message.
Request sample
{
    "campaignId": 168622,
    "ids": "1,2,3,4",
    "isExcluded": 0
}
Response 200
{
    "statusCode": 200,
    "responseObject": {
        "message": "Inventories Included."
    }
}

Download CSV inventory list​

POST

Get a CSV inventory list based on desired filters.

Query parameters
keywords
string		Filters by list of keywords.
countries
string		Filter by country ID.
categories
string		Filter by IAB category ID.
inventoryTypes
string		Filter by inventory group type.
creativeSizes
string		Filters by creative Size IDs.
creativeDurations
string		Filters by creative duration ID.
trafficTypes
string		Filters by traffic type ID.
Supported values
11App
14CTV
13OTT
12Web
deviceTypes
string		Filters by device type ID.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
exchanges
string		Filters by exchange IDs.
videoPlayerSizes
string		Filters by video player size ID.
isCsvSearch
boolean		true if CSV file uploaded for query, otherwise false.
fileType
string		File type to download: csv or xlsx.
Response properties
data
string		Download URL.
Request sample
{
  "multipartFile": "string"
}
Response 200
{
  "success": true,
  "data": "https://iqm-ephemeral-2aca615e13f8-stage.s3.amazonaws.com/inventory/download/csv/Yash%20org%202_1720435555550.csv?response-expires-Amz-Credential"
}

Get inventory based on CSV file​

POST

Get a paginated list of inventory based on provided CSV file.

Response properties
matchedInventories
object		Matched inventories list.
globalBlockedInventoryData 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.
Request sample
{
  "domainsFile": "string"
}
Response 200
{
  "success": true,
  "data": {
    "matchedInventories": [
      {
        "id": 3510,
        "name": "Test Inv 1234",
        "publisher": "UNKNOWN",
        "appId": "INVENTORY",
        "inventoryType": "Other App",
        "impressions": 7397885,
        "reach": 5257,
        "videoPercentage": 100,
        "displayPercentage": 0
      },
      {
        "id": 4746,
        "name": "Test Old TV 345",
        "publisher": "UNKNOWN",
        "appId": "INVENTORY",
        "inventoryType": "Other App",
        "impressions": 428882,
        "reach": 31291,
        "videoPercentage": 100,
        "displayPercentage": 0
      }
    ]
  }
}

Get distribution of inventory based on CSV file​

POST

Get distribution of inventory available to the user across countries, creative types, device types, traffic types, based on provided CSV file.

Response properties
countries
object		List of countries and distribution values.
trafficTypes
object		List of traffic type IDs and distribution values.
Supported values
11App
14CTV
13OTT
12Web
creativeTypes
object		List of creative types and distribution values.
deviceTypes
object		List of device types and distribution values.
object properties
label
string		Label.
value
integer		Value.
Request sample
{
  "domainsFile": "string"
}
Response 200
{
  "success": true,
  "data": {
    "countries": [
      {
        "label": "United States",
        "value": 90.58
      },
      {
        "label": "Brazil",
        "value": 1.23
      },
      {
        "label": "Germany",
        "value": 0.79
      },
      {
        "label": "France",
        "value": 0.75
      },
      {
        "label": "United Kingdom",
        "value": 0.62
      }
    ],
    "trafficTypes": [
      {
        "label": "App",
        "value": 62.85
      },
      {
        "label": "Web",
        "value": 37.15
      }
    ],
    "creativeTypes": [
      {
        "label": "Video",
        "value": 47.47
      },
      {
        "label": "Banner",
        "value": 40.96
      },
      {
        "label": "Native",
        "value": 6.38
      },
      {
        "label": "Audio",
        "value": 5.19
      }
    ],
    "deviceTypes": [
      {
        "label": "Mobile",
        "value": 43.53
      },
      {
        "label": "Connected TV",
        "value": 37.69
      },
      {
        "label": "Desktop",
        "value": 15.08
      },
      {
        "label": "Tablet",
        "value": 3.57
      },
      {
        "label": "Unknown",
        "value": 0.13
      }
    ]
  }
}

Get inventory count based on CSV file​

POST

Get inventory count based on provided CSV file.

Response properties
reach
integer		The number of unique individuals reached by an inventory, does not count repeat views.
publishers
integer		Publishers count.
impressions
object		Impressions count.
inventories
object		Inventories count.
Request sample
{
  "domainsFile": "string"
}
Response 200
{
  "success": true,
  "data": {
    "reach": 7983863253,
    "publishers": 2010,
    "impressions": 119273056646,
    "inventories": 1387184
  }
}

Fetch Contextual inventories​

GET

Retrieve a paginated list of Contextual inventories.

Query parameters
searchField
string		Search filter (default: empty string).
noOfEntries
integer		Number of entries per page (default: 10).
pageNo
integer		Page number (default: 1).
Response properties
id
integer		Contextual inventory ID.
inventory
string		Inventory name or URL.
contextualType
integer		Contextual type identifier.
Response 200
{
    "success": true,
    "data": {
        "data": [
            {
                "id": 1,
                "inventory": "example.com",
                "contextualType": 2
            }
        ],
        "totalRecords": 50,
        "filteredRecords": 10
    }
}

Add Contextual inventories​

POST

Create new Contextual inventories by providing a group name with associated keywords and/or URLs.

Request schema
groupName
string		Name for the Contextual inventory group.
keywords
array of strings		List of keywords to associate.
urls
array of strings		List of URLs to associate.
Response properties
data
string		Success message.
Request sample
{
    "groupName": "Sports Contextual",
    "keywords": ["basketball", "football"],
    "urls": ["https://espn.com", "https://sports.yahoo.com"]
}
Response 200
{
    "success": true,
    "data": "Contextual inventories added successfully."
}

Remove Contextual inventories​

DELETE

Permanently delete Contextual inventories from the user's global Contextual inventory pool.

Request schema
contextualInventoryIds
array of integers		IDs of Contextual inventories to remove.
Response properties
data
string		Success message.
Request sample
{
    "contextualInventoryIds": [101, 102, 103]
}
Response 200
{
    "success": true,
    "data": "Contextual inventories removed successfully."
}

Add Contextual inventories to inventory groups​

POST

Associate Contextual inventories with one or more inventory groups. The authenticated user must be authorized to access all provided group IDs.

Request schema
groupIds
array of integers		Inventory group IDs to add Contextual inventories to.
contextualIds
array of integers		Contextual inventory IDs to associate.
Response properties
data
string		Success message.
Request sample
{
  "groupIds": [
    170800,
    170801
  ],
  "contextualIds": [
    42386,
    42387
  ]
}
Response 200
{
  "success": true,
  "data": "Contextual Inventories added to groups successfully."
}
Response 403
{
  "success": false,
  "errorObjects": [
    {
      "error": "Unauthorized"
    }
  ]
}

Blocked inventories​

Blocklisted inventories refer to digital media placements or websites that are deemed inappropriate (adult content, hate speech, misleading information) or of low quality (low engagement, poor user experience).

Get list of blocked inventories​

GET

Get a list of blocked inventories and blocked subdomain (wildcard) groups.

Query parameters
searchField
string		Filter results by search field.
noOfEntries
integer		Number of entries returned per page, default: 200.
pageNo
integer		Page number of retrieved data, default: 1.
Response properties
id
integer		Inventory ID, or subdomain group ID on wildcard entries (invGroupSubType: 2).
name
string		Inventory name, or the *.-prefixed wildcard domain on subdomain entries.
appId
string		The bundle ID (for app request) or domain (for web request), not present on subdomain entries.
inventoryType
string		Inventory type (always Site on subdomain entries).
comment
string		Comment associated with this inventory, if one was added via Add comment for blocked inventory.
impressions
integer		Impressions count.
reach
integer		Reach count.
invGroupSubType
integer		Blocked inventory group sub-type: regular inventory entry (1) or an account-level blocked subdomain (wildcard) group entry (2).
Response 200
{
    "success": true,
    "data": {
        "totalRecords": 2,
        "filteredRecords": 2,
        "globalBlockedInventoryData": [
            {
                "id": 2793823,
                "name": "Watchfree (Vizio)",
                "appId": "vizio.watchfree",
                "inventoryType": "Other App",
                "impressions": 0,
                "reach": 0,
                "comment": "live test comment with id",
                "invGroupSubType": 1
            },
            {
                "id": 1280,
                "name": "nypost.com",
                "appId": "nypost.com",
                "inventoryType": "Site",
                "impressions": 0,
                "reach": 0,
                "invGroupSubType": 1
            }
        ]
    }
}

Block inventories​

POST

Inventories can be blocked at the account level by ID or search field.

Request schema
inventoryIds
array of integers		Inventory IDs to block.
searchField
string		Block inventories by search field.
Response properties
data
string		Success message.
Request sample
{
    "inventoryIds": [
        0,
        1,
        5
    ]
}
Response 200
{
    "success": true,
    "data": "Inventories blocked successfully."
}

Unblock inventories​

POST

Remove inventories from the blocked list by ID, subdomain group ID, or search field. If neither inventoryIds nor subdomainInventoryIds is provided, all currently blocked inventories and blocked subdomain groups matching searchField are unblocked.

Request schema
inventoryIds
array of integers		Inventory IDs to unblock.
subdomainInventoryIds
array of integers		IDs of blocked subdomain/wildcard groups to unblock — see the invGroupSubType entries returned by Get list of blocked inventories.
searchField
string		Unblock inventories by search field.
Response properties
data
string		Success message.
Request sample
{
    "inventoryIds": [
        1,
        2,
        3
    ],
    "subdomainInventoryIds": [
        101
    ]
}
Response 200
{
    "success": true,
    "data": "Inventories unblocked successfully."
}

Add comment for blocked inventory​

POST

Add a comment to a blocked inventory item.

Request schema
inventoryId
integer		The inventory ID to add a comment to (minimum: 1).
comment
string		Comment text (required).
Response properties
data
string		Success message.
Request sample
{
    "inventoryId": 1234,
    "comment": "Blocking due to brand safety concerns"
}
Response 200
{
    "success": true,
    "data": "Comment added successfully."
}

Block inventory file​

POST

Block inventories by uploading a CSV file containing inventory IDs. The CSV file should have domains and bundles as columns.

Prefix a domain with *. (e.g. *.example.com) to block that domain and all of its subdomains as a single wildcard entry, instead of blocking one domain at a time. The value after *. must be the domain's registrable root (*.example.com is valid, but *.blog.example.com is not, since blog.example.com isn't itself a root domain).

Wildcard entries appear in Get list of blocked inventories with invGroupSubType set, and count toward the same message/Error totals below as regular domain and bundle rows.

CSV columns must be named exactly Domains and Bundles, no more than these two columns are allowed. Leave a column empty to block by only the other. See the example below.

Query parameters
blocklistFile
file		CSV file containing inventory IDs to block.
fileTypeId
integer		File type ID: 1 for CSV.
Request schema
blocklistFile
file		CSV file containing inventory IDs to block.
CSV example

This example blocks example.com by itself, *.example.com and all of its subdomains as one wildcard entry, com.example.app by bundle ID, and example.org together with com.another.app in a single row.

Domains,Bundles
example.com,
*.example.com,
,com.example.app
example.org,com.another.app

Response properties
message
string		Success message with the number of inventories blocked. Present only when every row in the file was valid.
Error
string		Error message with the number of rows that could not be uploaded. Present instead of message when one or more rows in the file are invalid -- the request still returns 200.
errorFileUrl
string		Download URL for a file listing the invalid rows. Present alongside Error.
Request sample
{
  "blocklistFile": "string",
  "fileTypeId": 1
}
Response 200 (all rows valid)
{
    "success": true,
    "data": {
        "message": "5 inventories blocked successfully"
    }
}
Response 200 (some rows invalid)
{
    "success": true,
    "data": {
        "Error": "2 Entries could not be uploaded. Download the error file and retry",
        "errorFileUrl": "https://iqm-ephemeral-2aca615e13f8-stage.s3.amazonaws.com/inventory/block-file/errors/invalid_rows_1720435555550.csv?response-expires-Amz-Credential"
    }
}

CTV inventories​

Connected TV (CTV) inventories are app-based inventory sources available on smart TVs and streaming devices.

Get CTV inventory list​

GET

Get a paginated list of CTV inventories available to the authenticated user.

Query parameters
searchField
string		Search term matching publisher name or inventory name.
countries
string		Filter by country ID.
categories
string		Filter by IAB category.
creativeTypes
string		Filter by creative type ID.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
creativeDurations
string		Filter by creative duration ID (video/audio).
exchanges
string		Filter by exchange ID.
videoPlayerSizes
string		Filter by video player size ID.
streamingDevices
string		Filter by streaming device ID.
Supported values
1Samsung
2Roku TV
noOfEntries
integer		Number of entries per page (default: 10).
pageNo
integer		Page number (default: 1).
Response properties
inventoryDataList
array		List of CTV inventory objects.
inventoryDataList object properties
bunchId
integer		CTV inventory (bunch) ID.
appName
string		App name.
publisherName
string		Publisher name.
impressions
integer		Impressions count.
reach
integer		Unique individuals reached.
videoPercentage
number		Percentage of video impressions.
displayPercentage
number		Percentage of display impressions.
inventoryLogoUrl
string		URL of the inventory logo.
streamingDevices
array of objects		Streaming devices this CTV inventory is available on.
streamingDevices object properties
deviceName
string		Streaming device name.
logoUrl
string		URL of the streaming device logo.
totalRecords
integer		Total number of records.
filteredRecords
integer		Number of records matching the current filter.
Response 200
{
  "success": true,
  "data": {
    "filteredRecords": 2,
    "totalRecords": 100,
    "inventoryDataList": [
      {
        "bunchId": 100129,
        "appName": "HISTORY Vault",
        "publisherName": "A&E (A+E Networks)",
        "impressions": 120,
        "reach": 180,
        "videoPercentage": 100.0,
        "displayPercentage": 0.0,
        "inventoryLogoUrl": "https://cdn.com/adhoc/ctv-logos/1003514129",
        "streamingDevices": [
          {
            "deviceName": "Amazon Fire TV",
            "logoUrl": "https://iqm-data-lake-stage.s3.us-east-1.amazonaws.com/adhoc/ctv-logos/streaming-devices-logos/FireTV.png"
          },
          {
            "deviceName": "Android TV",
            "logoUrl": "https://iqm-data-lake-stage.s3.us-east-1.amazonaws.com/adhoc/ctv-logos/streaming-devices-logos/AndoidTV.png"
          }
        ]
      },
      {
        "bunchId": 100132,
        "appName": "FYI",
        "publisherName": "ATC",
        "impressions": 1100,
        "reach": 1079,
        "videoPercentage": 100.0,
        "displayPercentage": 0.0,
        "inventoryLogoUrl": "https://cdn.com/adhoc/ctv-logos/1003514132",
        "streamingDevices": [
          {
            "deviceName": "Amazon Fire TV",
            "logoUrl": "https://iqm-data-lake-stage.s3.us-east-1.amazonaws.com/adhoc/ctv-logos/streaming-devices-logos/FireTV.png"
          },
          {
            "deviceName": "Android TV",
            "logoUrl": "https://iqm-data-lake-stage.s3.us-east-1.amazonaws.com/adhoc/ctv-logos/streaming-devices-logos/AndoidTV.png"
          }
        ]
      }
    ]
  }
}
Response 403
{
  "success": false,
  "errorObjects": [
    {
      "error": "User is not allowed to access provided inventory group."
    }
  ]
}

Get CTV inventories count​

GET

Get the count of unique CTV inventories, total impressions, and total reach available to the authenticated user.

Query parameters
searchField
string		Search term matching publisher name or inventory name.
countries
string		Filter by country ID.
categories
string		Filter by IAB category ID.
creativeTypes
string		Filter by creative type ID.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
creativeDurations
string		Filter by creative duration ID (video/audio).
exchanges
string		Filter by exchange ID.
videoPlayerSizes
string		Filter by video player size ID.
streamingDevices
string		Filter by streaming device ID.
Supported values
1Samsung
2Roku TV
Response properties
reach
integer		Total unique individuals reached.
impressions
integer		Total impressions count.
inventories
integer		Count of unique CTV inventories.
Response 200
{
  "success": true,
  "data": {
    "reach": 7983253,
    "impressions": 119256646,
    "inventories": 13870
  }
}

Get CTV inventories distribution​

GET

Get the distribution of CTV inventories across countries, creative types, and traffic types.

Query parameters
searchField
string		Search term matching publisher name or inventory name.
countries
string		Filter by country ID.
categories
string		Filter by IAB category ID.
creativeTypes
string		Filter by creative type ID.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
creativeDurations
string		Filter by creative duration ID (video/audio).
exchanges
string		Filter by exchange ID.
videoPlayerSizes
string		Filter by video player size ID.
streamingDevices
string		Filter by streaming device ID.
Supported values
1Samsung
2Roku TV
Response properties
countries
object		Distribution across countries.
creativeTypes
object		Distribution across creative types.
streamingDevices
object		Distribution across streaming devices.
object properties
label
string		Label.
value
number		Percentage value.
Response 200
{
  "success": true,
  "data": {
    "countries": [
      { "label": "United States", "value": 99.06 },
      { "label": "Dominican Republic", "value": 0.27 },
      { "label": "Canada", "value": 0.26 },
      { "label": "Mexico", "value": 0.12 },
      { "label": "France", "value": 0.04 }
    ],
    "creativeTypes": [
      { "label": "Video", "value": 98.19 },
      { "label": "Audio", "value": 1.81 },
      { "label": "Banner", "value": 0.0 },
      { "label": "Native", "value": 0.0 }
    ],
    "streamingDevices": [
      { "label": "Roku", "value": 33.89 },
      { "label": "Samsung TV", "value": 27.82 },
      { "label": "Android TV", "value": 16.62 },
      { "label": "Amazon Fire TV", "value": 8.31 },
      { "label": "Other", "value": 7.85 },
      { "label": "Apple TV", "value": 2.49 },
      { "label": "Vizio", "value": 1.6 },
      { "label": "LG TV", "value": 1.44 }
    ]
  }
}

Download CTV inventory list​

POST

Download a CSV or XLSX file of the CTV inventory list based on requested filters.

Query parameters
searchField
string		Search term matching publisher name or inventory name.
countries
string		Filter by country ID.
categories
string		Filter by IAB category ID.
creativeTypes
string		Filter by creative type ID.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
creativeDurations
string		Filter by creative duration ID.
exchanges
string		Filter by exchange ID.
videoPlayerSizes
string		Filter by video player size ID.
streamingDevices
string		Filter by streaming device ID.
Supported values
1Samsung
2Roku TV
fileType
string required		Output file format: csv or xlsx.
Response properties
data
string		Download URL for the generated file.
Response 200
{
  "success": true,
  "data": "https://sample-download-url.com/CTVInventories_ctv.csv"
}

Get list of streaming devices​

GET

Get the static list of streaming devices available for CTV inventories, sorted in ascending order by display order.

Query parameters
searchField
string		Search term matching streaming device name.
Response properties
id
integer		Streaming device ID.
displayName
string		Streaming device name.
logoUrl
string		URL of the streaming device logo.
Response 200
{
  "success": true,
  "data": [
    {
      "id": 1,
      "displayName": "Samsung",
      "logoUrl": "https://samsunglogo.com"
    },
    {
      "id": 2,
      "displayName": "Roku TV",
      "logoUrl": "https://rokuTV.com"
    }
  ]
}

Inventory groups​

Get list of inventory groups​

GET

Get a list of inventory groups based on various filters and parameters.

An inventory group id can be used to perform various actions in Inventory group management endpoints.

Query parameters
groupFilterId
integer		Filters groups list. Supported values:
All Groups [default]: 0.
Share by Admin: 1.
Own Groups: 2.
groupTypeIds
string		Filters groups list. Supported values:
Open Exchange: 1.
PMP: 2.
Contextual: 3.
CTV: 4.
ids
string		Comma separated IDs.
provideAccountLevelExcludedGroup
boolean		Flag to indicate whether to include account-level excluded group in response or not, default: false.
includeStatistics
boolean		Flag to indicate whether to include statistics in response or not, default: true.
excludeEmptyGroups
boolean		Flag to indicate whether to include empty groups in response or not, default: false.
searchField
string		Filter results by search field.
pageSize
integer		Number of entries returned per page.
pageNo
integer		Page number of retrieved data.
owId
integer		Organization Workspace ID.
sortBy
string		Sort entries by ascending (+) or descending (-).
Response properties
inventoryGroupList
integer		Inventory group type list details.
inventoryGroupList object 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.
Response 200
{
    "success": true,
    "data": {
        "totalRecords": 371,
        "filteredRecords": 6,
        "inventoryGroupList": [
        {
            "groupTypeId": 1,
            "created": 1720032375,
            "modifiedDate": "2024-07-03T13:18:26.935+0000",
            "owId": 201427,
            "impressions": 0,
            "isAccountLevelExcluded": null,
            "campaignWhitelistCount": 0,
            "campaignBlacklistCount": 0,
            "whiteListedCampaignIds": [
                503885,
                486112,
                478890
            ],
            "blackListedCampaignIds": [],
            "publishers": 0,
            "sharedCount": 0,
            "uniques": 0,
            "reach": 0,
            "inventories": 0,
            "deals": 0,
            "contextualInventories": 0,
            "count": 0,
            "id": 176178,
            "name": "Inventory Group - Open exchange - 3 campaign",
            "isShared": false
        }
        ]
    }
}

Get list of shared group Customer details​

GET
Path parameter
groupIdGroup ID.
Response properties
owId
integer		Organization Workspace ID.
organizationName
string		Organization name.
status
string		Customer status.
ownerUserEmail
string		Owner user email.
logoUrl
string		Organization logo URL.
campaignCount
integer		Total campaign count.
runningCampaignCount
integer		Running campaign count.
Response 200
{
  "success": true,
  "data": [
    {
      "owId": 201427,
      "organizationName": "Acme Advertising",
      "status": "active",
      "ownerUserEmail": "owner@example.com",
      "logoUrl": "https://example.com/logo.png",
      "campaignCount": 5,
      "runningCampaignCount": 2
    }
  ]
}

Get list of inventory groups statistics​

GET
Response properties
totalInventoryGroups
integer		Inventory groups count.
includedGroups
integer		Included groups count.
excludedGroups
integer		Excluded groups count.
unUsedGroups
integer		Unused groups count.
Response 200
{
  "success": true,
  "data": {
    "totalInventoryGroups": 371,
    "includedGroups": 296,
    "excludedGroups": 92,
    "unUsedGroups": 75
  }
}

Get list of PMP deals in an inventory group​

GET
Path parameter
groupIdGroup ID.
Query parameter
searchFieldFilter inventory by group name.
noOfEntriesNumber of entries returned per page, default: 50.
pageNoPage number of retrieved data.
sortBySorts by ascending (+) or descending (-).
Response properties
pmpDealData
integer		PMP deals list details.
pmpDealData object properties
id
integer		PMP deal ID.
dealId
string		Deal ID.
dealName
string		PMP deal name.
description
string		Deal description.
cpm
integer		Cost per mille.
dealTypeId
integer		Deal type ID.
Supported values
1PMP deal
2PG deal
creativeTypes
array of string		List of creative types.
exchanges
array of strings		List of exchanges.
active
boolean		Indicates that deal is active: true.
created
integer		Unix epoch creation date, in milliseconds.
modifiedDate
string		Modified date.
applicableTo
array of integers		Customer OW IDs to whom this deal is assigned and have access rights.
userName
string		User name.
isPublic
boolean		Indicates that this deal is shared, not private: true.
Response 200
{
  "success": true,
  "data": {
    "pmpDealData": [
      {
        "id": 345,
        "dealId": "070621-Test Deal-MS@15",
        "dealName": "0670621 Test Deal 15",
        "description": "test desc",
        "cpm": 2,
        "dealTypeId": 2,
        "creativeTypes": [
          "HTML",
          "Audio"
        ],
        "exchanges": [
          "Rubicon"
        ],
        "active": true,
        "created": 1623076958,
        "modifiedDate": "2021-06-08T11:27:30.549+0000",
        "applicableTo": [],
        "userName": null,
        "isPublic": true
      }
    ],
    "totalRecords": 6,
    "filteredRecords": 6
  }
}

Get CSV list of PMP deals in an inventory group​

GET
Path parameter
groupIdGroup ID.
Query parameter
searchFieldFilter inventory by group name.
sortOrderSorts by ascending (asc) or, default: descending (desc).
sortBySort by parameter, default: created.

See TypeScript prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": unknown;
    };
  };
}

function generateGroupPMPDealsFile(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/inv/group/{groupId}/pmp-deals/csv',
    params: {
      path: {
        groupId: `number`
      },
      query: {
        searchField?: `string`,
        sortOrder?: `string`,
        sortBy?: `string`
      }
    }
  };

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

Get list of Open Exchange inventories in an inventory group​

GET
Path parameter
groupIdGroup ID.
Query parameter
searchFieldFilter inventory by group name.
noOfEntriesNumber of entries returned per page, default: 50.
pageNoPage number of retrieved data.
Response properties
openExchangeInventoryData
object		Open Exchange inventory data details list.
openExchangeInventoryData 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 group, does not count repeat views.
videoPercentage
integer		Percentage of total ad impressions that are video-based.
Response 200
{
  "success": true,
  "data": {
    "totalRecords": 3,
    "filteredRecords": 3,
    "openExchangeInventoryData": [
      {
        "id": 52982,
        "name": "gazeta.pl",
        "publisher": "UNKNOWN",
        "appId": "INVENTORY",
        "inventoryType": "Site",
        "impressions": 25738,
        "reach": 2128,
        "videoPercentage": 18.29979,
        "displayPercentage": 77.989743
      },
      {
        "id": 52983,
        "name": "protopage.com",
        "publisher": "UNKNOWN",
        "appId": "INVENTORY",
        "inventoryType": "Site",
        "impressions": 4315,
        "reach": 322,
        "videoPercentage": 0,
        "displayPercentage": 100
      },
      {
        "id": 52986,
        "name": "gwiazdy.wp.pl",
        "publisher": "UNKNOWN",
        "appId": "INVENTORY",
        "inventoryType": "Site",
        "impressions": 516,
        "reach": 58,
        "videoPercentage": 4.651163,
        "displayPercentage": 87.596899
      }
    ],
    "uniqueRecords": 3
  }
}

Get distributions of Open Exchange inventories in an inventory group​

GET
Path parameter
groupIdGroup ID.
Query parameter
searchFieldFilter inventory by group name.
Response properties
countries
object		List of countries and distribution values.
trafficTypes
object		List of traffic type IDs and distribution values.
Supported values
11App
14CTV
13OTT
12Web
creativeTypes
object		List of creative types and distribution values.
deviceTypes
object		List of device types and distribution values.
object properties
label
string		Label.
value
integer		Value.
Response 200
{
  "success": true,
  "data": {
    "trafficTypes": [
      {
        "label": "Web",
        "value": 100
      }
    ],
    "countries": [
      {
        "label": "United States",
        "value": 98.86
      },
      {
        "label": "Netherlands",
        "value": 0.98
      },
      {
        "label": "Canada",
        "value": 0.08
      },
      {
        "label": "Ecuador",
        "value": 0.03
      },
      {
        "label": "Virgin Islands, U.S.",
        "value": 0.03
      }
    ],
    "deviceTypes": [
      {
        "label": "Desktop",
        "value": 87.68
      },
      {
        "label": "Mobile",
        "value": 9.27
      },
      {
        "label": "Tablet",
        "value": 3.06
      }
    ],
    "creativeTypes": [
      {
        "label": "Banner",
        "value": 81.26
      },
      {
        "label": "Video",
        "value": 15.49
      },
      {
        "label": "Native",
        "value": 3.25
      }
    ]
  }
}

Get count of Open Exchange inventories in an inventory group​

GET
Path parameter
groupIdGroup ID.
Query parameter
searchFieldFilter inventory by group name.
Response properties
reach
integer		The number of unique individuals reached by an inventory group, does not count repeat views.
publishers
integer		Publishers count.
impressions
object		Impressions count.
inventories
object		Inventories count.
Response 200
{
  "success": true,
  "data": {
    "inventories": 3,
    "reach": 2689,
    "publishers": 1,
    "impressions": 30569
  }
}

Get list of Contextual inventories for an inventory group​

GET
Path parameter
groupIdGroup ID.
Query parameter
searchFieldFilter inventory by group name.
noOfEntriesNumber of entries returned per page, default: 50.
pageNoPage number of retrieved data.
Response properties
id
integer		Inventory ID.
inventory
string		Inventory name.
contextualType
integer		Contextual type ID.
1: keyword.
2: URL.
Response 200
{
  "success": true,
  "data": {
    "data": [
      {
        "id": 42486,
        "inventory": "law business",
        "contextualType": 1
      }
    ],
    "totalRecords": 2,
    "filteredRecords": 1
  }
}

Get count of Contextual inventories for an inventory group​

GET
Path parameter
groupIdGroup ID.
Query parameter
searchFieldFilter inventory by group name.
Response properties
contextualUrlCount
integer		Contextual URL count.
contextualKeywordCount
integer		Contextual keyword count.
Response 200
{
  "success": true,
  "data": {
    "contextualUrlCount": 0,
    "contextualKeywordCount": 1
  }
}

Get CSV file of Contextual inventories for an inventory group​

GET
Path parameter
groupIdGroup ID.
Query parameter
searchFieldFilter inventory by group name.

See TypeScript prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": unknown;
    };
  };
}

function generateGroupContextualInventoriesFile(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/inv/group/{groupId}/contextual/inventories/csv',
    params: {
      path: {
        groupId: `number`
      },
      query: {
        searchField?: `string`,
      }
    }
  };

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

Contextual inventory​

GET
GET

Get recommended keywords or autocompleted keywords.

Query parameters
keyword
string		Suggestion or recommendation will be made based on this keyword.
Response properties
data
array of strings		Contextual keywords list.
Response 200
{
    "success": true,
    "data": [
        "sport",
        "business",
        "play"
    ]
}

Get inventory groups count​

GET

Get the total count of inventory groups for the authenticated user.

Response properties
data
object		Count data.
data.inventoryGroupsCount
integer		Total number of inventory groups.
Response 200
{
    "success": true,
    "data": {
        "inventoryGroupsCount": 26
    }
}

Download Open Exchange inventories for group​

POST

Download Open Exchange inventory details for a specific group as a file.

Path parameters
groupId
integer		Inventory group ID (required).
Query parameters
fileType
string		File type for download (required), e.g., csv.
searchField
string		Search filter for inventories.
Response properties
data
string		S3 download URL for the generated file.
Response 200
{
    "success": true,
    "data": "https://s3.amazonaws.com/bucket/inventories-export.csv"
}

Get CTV inventories for an inventory group​

GET

Get a paginated list of CTV inventories belonging to a specific inventory group.

Path parameter
groupId
integer required		Group ID.
Query parameters
searchField
string		Filter inventories by name.
noOfEntries
integer		Number of entries per page (default: 50).
pageNo
integer		Page number (default: 0).
Response properties
inventoryDataList
array		List of CTV inventory objects.
inventoryDataList object properties
id
integer		Inventory ID.
name
string		Inventory name.
publisherName
string		Publisher name.
appId
string		Bundle ID (app) or domain (web).
inventoryType
string		Inventory type.
impressions
integer		Impressions count.
reach
integer		Unique individuals reached.
videoPercentage
number		Percentage of video impressions.
displayPercentage
number		Percentage of display impressions.
inventoryLogoUrl
string		URL of the inventory logo.
ctv
boolean		Indicates CTV inventory: true.
totalRecords
integer		Total number of records.
filteredRecords
integer		Number of records matching the current filter.
Response 200
{
  "success": true,
  "data": {
    "totalRecords": 24397208,
    "filteredRecords": 2,
    "inventoryDataList": [
      {
        "id": 3408578,
        "name": "Tubi (Roku)",
        "publisherName": "Roku",
        "appId": "41468",
        "inventoryType": "Other App",
        "impressions": 3928807709,
        "reach": 36173425,
        "videoPercentage": 99.999869,
        "displayPercentage": 0.0,
        "inventoryLogoUrl": "https://iqm-data-lake-stage.s3.us-east-1.amazonaws.com/adhoc/ctv-logos/3408578",
        "ctv": true
      },
      {
        "id": 68028,
        "name": "NewsON (Android TV)",
        "publisherName": "NewsON",
        "appId": "com.newson.vinson",
        "inventoryType": "Android App",
        "impressions": 962565737,
        "reach": 859260,
        "videoPercentage": 100.0,
        "displayPercentage": 0.0,
        "inventoryLogoUrl": "https://iqm-data-lake-stage.s3.us-east-1.amazonaws.com/adhoc/ctv-logos/68028",
        "ctv": true
      }
    ]
  }
}

Get CTV inventories statistics for an inventory group​

GET

Get inventory count, total reach, and total impressions for CTV inventories in a specific inventory group.

Path parameter
groupId
integer required		Group ID.
Response properties
inventories
integer		Count of CTV inventories in the group.
reach
integer		Total unique individuals reached.
impressions
integer		Total impressions count.
Response 200
{
  "success": true,
  "data": {
    "inventories": 3,
    "reach": 37657018,
    "impressions": 5031212348
  }
}

Get CTV inventories distributions for an inventory group​

GET

Get the distribution of CTV inventories in a specific inventory group across countries, creative types, and streaming devices.

Path parameter
groupId
integer required		Group ID.
Response properties
countries
object		Distribution across countries.
creativeTypes
object		Distribution across creative types.
streamingDevices
object		Distribution across streaming devices.
object properties
label
string		Label.
value
number		Percentage value.
Response 200
{
  "success": true,
  "data": {
    "countries": [
      { "label": "United States", "value": 99.11 },
      { "label": "Canada", "value": 0.39 },
      { "label": "Brazil", "value": 0.11 },
      { "label": "Mexico", "value": 0.09 },
      { "label": "United Kingdom", "value": 0.05 }
    ],
    "creativeTypes": [
      { "label": "Video", "value": 99.6 },
      { "label": "Audio", "value": 0.4 }
    ],
    "streamingDevices": [
      { "label": "Roku", "value": 99.92 },
      { "label": "Samsung TV", "value": 0.08 }
    ]
  }
}

Download CTV inventories for an inventory group​

POST

Download CTV inventory details for a specific inventory group as a CSV or XLSX file.

Path parameter
groupId
integer required		Group ID.
Query parameters
fileType
string required		File type for download: csv or xlsx.
searchField
string		Filter inventories by name.
Response properties
data
string		S3 download URL for the generated file.
Response 200
{
  "success": true,
  "data": "https://iqm-ephemeral-2ach617e13f8-stage.s3.amazonaws.com/inventory/download/csv/Yash%20org%202_1720435555550.csv?response-expires-Amz-Credential"
}

Inventory group management​

Update details or delete group inventories.

Create a new inventory group​

POST

Create an Open Exchange inventory group with inventoryIds
Request schema
groupName
integer		Desired name for group.
groupTypeId
integer		Group type. Supported values:
Open Exchange: 1.
PMP: 2.
Contextual: 3.
CTV: 4.
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": [
        35132,
        4107192
    ]
}
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
    }
}
Create an Open Exchange inventory group with search filters
Request schema
groupName
integer		Desired name for group.
groupTypeId
integer		Group type. Supported values:
Open Exchange: 1.
PMP: 2.
Contextual: 3.
CTV: 4.
excludedInventoryIds
array of integers		Inventory IDs to exclude from group.
countries
array of integers		Country IDs.
categories
array of strings		IAB Categories to include in group.
inventoryTypes
array of integers		Inventory type ID.
creativeTypes
array of integers		Creative type IDs.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
trafficTypes
array of integers		Traffic type IDs.
Supported values
11App
14CTV
13OTT
12Web
deviceTypes
array of integers		Device type IDs.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
exchanges
array of integers		Exchange IDs.
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
{
  "groupTypeId": 1,
  "groupName": "Inventory Group - Open exchange - search",
  "excludedInventoryIds": [],
  "countries": [
    30100001
  ],
  "categories": [
    "IAB1-1",
    "IAB1-2",
    "IAB1-3",
    "IAB1-4",
    "IAB1-5",
    "IAB1-6"
  ],
  "inventoryTypes": [
    2,
    3
  ],
  "creativeTypes": [
    1
  ],
  "trafficTypes": [
    11
  ],
  "deviceTypes": [
    20300001
  ],
  "exchanges": [
    71,
    75,
    41,
    80,
    39,
    47,
    76,
    1,
    78,
    69,
    88,
    19,
    73
  ]
}
Response 200
{
  "success": true,
  "data": {
    "groupTypeId": 1,
    "created": 1720030003,
    "modifiedDate": "2024-07-03T18:06:45.627+0000",
    "owId": 201427,
    "impressions": 5298817,
    "isAccountLevelExcluded": false,
    "campaignWhitelistCount": 0,
    "campaignBlacklistCount": 0,
    "whiteListedCampaignIds": [],
    "blackListedCampaignIds": [],
    "publishers": 9,
    "sharedCount": 0,
    "uniques": 0,
    "reach": 458855,
    "inventories": 0,
    "deals": 0,
    "contextualInventories": 0,
    "count": 24,
    "id": 176177,
    "name": "Inventory Group - Open exchange - search",
    "isShared": false
  }
}
Create a PMP inventory group with dealIds
Request schema
groupName
integer		Desired name for group.
groupTypeId
integer		Group type. Supported values:
Open Exchange: 1.
PMP: 2.
Contextual: 3.
CTV: 4.
dealIds
array of integers		PMP Deal 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 - PMP",
  "groupTypeId": 2,
  "dealIds": [
    204
  ]
}
Response 200
{
  "success": true,
  "data": {
    "groupTypeId": 2,
    "created": 1719836290,
    "modifiedDate": "2024-07-01T12:18:10.397+0000",
    "owId": 201427,
    "impressions": 0,
    "isAccountLevelExcluded": false,
    "campaignWhitelistCount": 0,
    "campaignBlacklistCount": 0,
    "whiteListedCampaignIds": [],
    "blackListedCampaignIds": [],
    "publishers": 0,
    "sharedCount": 0,
    "uniques": 0,
    "reach": 0,
    "inventories": 0,
    "deals": 0,
    "contextualInventories": 0,
    "count": 1,
    "id": 174599,
    "name": "Inventory Group - PMP",
    "isShared": false
  }
}
Create a PMP inventory group with keywords and/or URLs
Request schema
groupName
integer		Desired name for group.
groupTypeId
integer		Group type. Supported values:
Open Exchange: 1.
PMP: 2.
Contextual: 3.
CTV: 4.
contextualUrls
array of strings		Contextual URLs to include in group.
contextualKeywords
array of strings		Contextual keywords 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 - PMP",
  "groupTypeId": 2,
  "contextualKeywords": [
    "mcd",
    "coke",
    "cola"
  ],
  "contextualUrls": [
    "https://mcdindia.com/",
    "https://www.coca-colacompany.com/"
  ]
}
Response 200
{
  "success": true,
  "data": {
    "groupTypeId": 3,
    "created": 1719836633,
    "modifiedDate": "2024-07-01T12:23:52.829+0000",
    "owId": 201427,
    "impressions": 0,
    "isAccountLevelExcluded": false,
    "campaignWhitelistCount": 0,
    "campaignBlacklistCount": 0,
    "whiteListedCampaignIds": [],
    "blackListedCampaignIds": [],
    "publishers": 0,
    "sharedCount": 0,
    "uniques": 0,
    "reach": 0,
    "inventories": 0,
    "deals": 0,
    "contextualInventories": 0,
    "count": 5,
    "id": 174880,
    "name": "Inventory Group - Contextual keywords and URLs",
    "isShared": false
  }
}
Create a CTV inventory group with bunchIds
Request schema
groupName
integer		Desired name for group.
groupTypeId
integer		Group type. Supported values:
Open Exchange: 1.
PMP: 2.
Contextual: 3.
CTV: 4.
bunchIds
array of integers		CTV inventory (bunch) IDs to include in group.
streamingDevice
array of integers		Streaming device IDs to filter the group's CTV inventories by.
Supported values
1Samsung
2Roku TV
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.
campaignWhitelistCount
integer		Number of campaigns where this inventory group is whitelisted.
campaignBlacklistCount
integer		Number of campaigns where this inventory group is blacklisted.
distribution
object		Distribution of the group's CTV inventories across countries, creative types, and streaming devices. See Get CTV inventories distributions for an inventory group.
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": "test-ctv-grp-5",
    "bunchIds": [
        101,
        201
    ],
    "groupTypeId": 4
}
Request sample
{
    "groupName": "test-ctv-grp-5",
    "bunchIds": [
        101,
        201
    ],
    "streamingDevice": [
        7001,
        8001
    ],
    "groupTypeId": 4
}
Response 200
{
    "success": true,
    "data": {
        "groupTypeId": 4,
        "created": 1783938142,
        "modifiedDate": "2026-07-13T10:22:30.809+00:00",
        "owId": 203615,
        "impressions": 344567520,
        "isAccountLevelExcluded": false,
        "distribution": {
            "countries": [
                { "label": "United States", "value": 99.11 },
                { "label": "Canada", "value": 0.39 },
                { "label": "Brazil", "value": 0.11 },
                { "label": "Mexico", "value": 0.09 },
                { "label": "United Kingdom", "value": 0.05 }
            ],
            "creativeTypes": [
                { "label": "Video", "value": 99.6 },
                { "label": "Audio", "value": 0.4 }
            ],
            "streamingDevices": [
                { "label": "Roku", "value": 99.92 },
                { "label": "Samsung TV", "value": 0.08 }
            ]
        },
        "campaignWhitelistCount": 0,
        "campaignBlacklistCount": 0,
        "publishers": 0,
        "sharedCount": 0,
        "uniques": 0,
        "reach": 2253113,
        "inventories": 0,
        "deals": 0,
        "contextualInventories": 0,
        "count": 3,
        "id": 191713,
        "name": "test-ctv-grp-1",
        "isShared": false
    }
}

Add or remove mappings to an inventory group​

POST
POST

Add or remove inventories (Open Exchange, private deals, Contextual, CTV) to a group or multiple groups.

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

Add/remove by filter
Request schema
groupIds
array of integers		Group IDs to add/remove mappings to/from.
keywords
array of strings		Filters by keyword.
countries
array of integers		Filters by country IDs.
categories
array of strings		Filter by IAB category.
inventoryTypes
array of integers		Filter by inventory types.
creativeSizes
array of strings		Filter by creative size IDs.
creativeTypes
array of integers		Filter by creative type IDs.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
trafficTypes
array of integers		Filter by traffic type IDs.
Supported values
11App
14CTV
13OTT
12Web
deviceTypes
array of integers		Filter by device type IDs.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
videoPlayerSizes
array of integers		Filter by video player size IDs.
isAllInventories
boolean		Indicates inventory IDs will be retrieved from the database instead of the UI: true.
groupTypeId
integer		Group type. Supported values:
Open Exchange: 1.
PMP: 2.
Contextual: 3.
CTV: 4.

Add/remove by deal ID
Request schema
groupIds
array of integers		Group IDs to add/remove mappings to/from.
dealIds
array of integers		Deal IDs to add/remove to/from group.
groupTypeId
integer		Group type. Supported values:
Open Exchange: 1.
PMP: 2.
Contextual: 3.
CTV: 4.

Add/remove by Contextual inventories
Request schema
groupIds
array of integers		Group IDs to add/remove mappings to/from.
contextualKeywords
array of strings		Names of Contextual inventories.
contextualUrls
array of strings		URLs of Contextual inventories.
groupTypeId
integer		Group type. Supported values:
Open Exchange: 1.
PMP: 2.
Contextual: 3.
CTV: 4.

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.
groupTypeId
integer		Group type. Supported values:
Open Exchange: 1.
PMP: 2.
Contextual: 3.
CTV: 4.

Add/remove by CTV bunch IDs
Request schema
groupIds
array of integers		Group IDs to add/remove mappings to/from.
bunchIds
array of integers		CTV inventory (bunch) IDs to add/remove to/from group.
streamingDevice
array of integers		Streaming device IDs to filter the group's CTV inventories by (add only).
Supported values
1Samsung
2Roku TV
groupTypeId
integer		Group type. Supported values:
Open Exchange: 1.
PMP: 2.
Contextual: 3.
CTV: 4.

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.
distribution
object		CTV Inventory Groups only: distribution across countries, creative types, and streaming devices. See Get CTV inventories distributions for an inventory group.
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.
{
  "groupIds": [
    100462
  ],
  "keywords": [
    "foxnews",
    "CNN",
    "com.sleeeeepfly.knife.io"
  ],
  "countries": [
    30100001,
    30100002
  ],
  "categories": [
    "IAB1",
    "IAB14"
  ],
  "inventoryTypes": [
    1,
    2,
    3
  ],
  "creativeSizes": [
    "574x323",
    "288x162"
  ],
  "creativeTypes": [
    1,
    2,
    3
  ],
  "creativeDurations": [
    1,
    2,
    -1
  ],
  "trafficTypes": [
    11,
    12
  ],
  "deviceTypes": [
    20300001
  ],
  "exchanges": [
    47,
    48
  ],
  "videoPlayerSizes": [
    1,
    3,
    4,
    -1
  ],
  "isAllInventories": true,
  "groupTypeId": 1
}
{
  "groupIds": [
    100462,
    100463
  ],
  "dealIds": [
    10
  ],
  "groupTypeId": 2
}
{
  "groupIds": [
    100462,
    100463
  ],
  "contextualKeywords": [
    "testing1",
    "testing2"
  ],
  "contextualUrls": [
    "http://google.com",
    "http://google1.com"
  ],
  "groupTypeId": 3
}
{
  "groupIds": [
    100462,
    100463
  ],
  "inventoryIds": [
    200462,
    200463
  ],
  "groupTypeId": 1
}
{
  "groupIds": [
    100462,
    100463
  ],
  "bunchIds": [
    101
  ],
  "streamingDevice": [
    1001
  ],
  "groupTypeId": 4
}
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
        }
    ]
}
Response 200 (CTV inventory group)
{
    "success": true,
    "data": [
        {
            "groupTypeId": 4,
            "created": 1783938142,
            "modifiedDate": "2026-07-13T10:22:30.809+00:00",
            "owId": 203615,
            "impressions": 344567520,
            "isAccountLevelExcluded": false,
            "distribution": {
                "countries": [
                    { "label": "United States", "value": 99.11 },
                    { "label": "Canada", "value": 0.39 },
                    { "label": "Brazil", "value": 0.11 },
                    { "label": "Mexico", "value": 0.09 },
                    { "label": "United Kingdom", "value": 0.05 }
                ],
                "creativeTypes": [
                    { "label": "Video", "value": 99.6 },
                    { "label": "Audio", "value": 0.4 }
                ],
                "streamingDevices": [
                    { "label": "Roku", "value": 99.92 },
                    { "label": "Samsung TV", "value": 0.08 }
                ]
            },
            "campaignWhitelistCount": 0,
            "campaignBlacklistCount": 0,
            "publishers": 0,
            "sharedCount": 0,
            "uniques": 0,
            "reach": 2253113,
            "inventories": 0,
            "deals": 0,
            "contextualInventories": 0,
            "count": 3,
            "id": 191713,
            "name": "test-ctv-grp-1",
            "isShared": false
        }
    ]
}

Add or remove Customers from a shared inventory group​

PATCH

Add or remove Customers from one or more inventory groups with the following endpoint:

Request schema
groupIds
array of integers required		Group IDs to update shared Customer mappings for.
addOwIds
array of integers		Organization Workspace IDs to add to inventory group.
removeOwIds
array of integers		Organization Workspace IDs to remove from inventory group.
Response properties
data
array of strings		Success message.
Request sample
{
    "groupIds": [
        191712,
        191714
    ],
    "addOWIds": [
        200425,
        200495,
        200496
    ],
    "removeOWIds": [
        200929,
        200931
    ]
}
{
    "success": true,
    "data": "Your changes have been successfully saved."
}

Edit inventory group​

PATCH

Edit an inventory group.

Path parameters
groupId
integer		Group ID.
Request schema
groupName
string		Name of 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": "Open exchange Group - updated"
}
Response 200
{
    "success": true,
    "data": {
        "groupTypeId": null,
        "created": null,
        "modifiedDate": null,
        "owId": 0,
        "impressions": 0,
        "isAccountLevelExcluded": null,
        "campaignWhitelistCount": 0,
        "campaignBlacklistCount": 0,
        "whiteListedCampaignIds": null,
        "blackListedCampaignIds": null,
        "publishers": 0,
        "sharedCount": 0,
        "uniques": 0,
        "reach": 0,
        "inventories": 0,
        "deals": 0,
        "contextualInventories": 0,
        "count": 0,
        "id": 176168,
        "name": "Open exchange Group - updated",
        "isShared": false
    }
}
More responses
Response 403
{
    "success": false,
    "errorObjects": [
        {
        "error": "Forbidden!"
        }
    ]
}
Response 422
{
    "success": false,
    "errorObjects": [
        {
            "error": "Inventory group name can not have more than 255 characters.",
            "field": "groupName"
        }
    ]
}
Response 500
{
    "success": false,
    "errorObjects": [
        {
            "error": "server encountered an error !"
        }
    ]
}

Delete inventory group​

DELETE

Delete an existing inventory group.

Path parameters
groupId
integer		Group ID.
Response properties
data
array of strings		Success message.
Response 200
{
    "success": true,
    "data": "Inventory group deleted successfully."
}

Bulk delete inventory groups​

POST

Delete multiple existing inventory groups at once by group IDs.

Request schema
groupIds
array of integers required		Group IDs to delete.
Response properties
data
string		Success message.
Request sample
{
    "groupIds": [
        191712,
        191714
    ]
}
Response 200
{
    "success": true,
    "data": "2 inventory group(s) deleted successfully."
}
More responses
Response 403
{
    "success": false,
    "errorObjects": [
        {
            "error": "Unauthorized user or invalid inventory group."
        }
    ]
}

Add Contextual inventories to group​

POST

Add Contextual inventories to one or more inventory groups.

Request schema
groupIds
array of integers		Group IDs to add Contextual inventories to (required).
contextualIds
array of integers		Contextual inventory IDs to add (required).
Response properties
data
string		Success message.
Request body
{
    "groupIds": [1, 2, 3],
    "contextualIds": [101, 102]
}
Response 200
{
    "success": true,
    "data": "Contextual Inventories added to group successfully."
}

Remove Contextual inventories from group​

DELETE

Remove Contextual inventories from an inventory group.

Request schema
groupId
integer		Group ID to remove Contextual inventories from.
contextualIds
array of integers		Contextual inventory IDs to remove (required).
Response properties
data
string		Success message.
Request body
{
    "groupId": 1,
    "contextualIds": [101, 102]
}
Response 200
{
    "success": true,
    "data": "Contextual Inventories removed from group successfully."
}

Add Contextual inventory group for campaign​

POST

Creates a new Contextual inventory group from the provided keywords/URLs and returns its generated group id, for attaching to a campaign.

Request schema
groupName
string		Name for the Contextual inventory group.
keywords
array of strings		List of keywords to associate.
urls
array of strings		List of URLs to associate.
Response properties
inventoryGroupId
integer		ID of the newly created Contextual inventory group, for attaching to a campaign.
Request sample
{
    "groupName": "Sports Keywords Group",
    "keywords": ["sports", "nfl", "basketball"],
    "urls": ["https://www.espn.com/", "https://www.nfl.com/"]
}
Response 200
{
    "success": true,
    "data": {
        "inventoryGroupId": 170800
    }
}

Validate inventory group​

POST

Validate whether the authenticated user is authorized to access the specified inventory groups.

Request schema
groupIds
array of integers		Group IDs to validate.
Response properties
data
boolean		Whether the user is authorized for the specified groups.
Request body
{
    "groupIds": [1, 2, 3]
}
Response 200
{
    "success": true,
    "data": true
}

Deals details​

List of deals​

POST

Get a list of deals based on desired filters available for user.

You can also get more detailed lists of PMP deals or PG deals, in their respective list endpoints.

Request schema
deal
object		Contains key-value pairs of PG/PMP and an array of their IDs to filter results by.
owIds
array of integers		Organization Workspace IDs.
dealStatus
array of strings		Deal statuses, allowed values: Active, Inactive.
searchField
string		Filter deals by entity specified with searchBy.
searchBy
array of strings		Search by dealId, dealName, or exchangeName.
pageNo
integer		Page number of retrieved data, default: 1.
noOfEntries
integer		Number of deals to retrieve per page, default: 50.
sortBy
string		Sort entries.
Response properties
id
integer		Deal ID.
dealId
string		Deal identifier.
dealStatus
string		Deal status.
dealName
string		Deal name.
exchangeName
string		Exchange name.
dealType
string		Deal type, either PG or PMP.
campaignCount
integer		Number of campaigns associated with the deal.
Request sample
{
  "deal": {
    "PG": [
      3
    ],
    "PMP": [
      378
    ]
  },
  "owIds": [
    201427
  ],
  "dealStatus": [
    "Active"
  ],
  "searchField": "Smaato  ",
  "searchBy": [
    "dealId",
    "dealName",
    "exchangeName"
  ],
  "pageNo": 1,
  "noOfEntries": 50,
  "sortBy": "dealId"
}
Response 200
{
  "success": true,
  "data": {
    "totalRecords": 2511,
    "filteredRecords": 2,
    "dealList": [
      {
        "id": 3,
        "dealId": "PM-Ny3ey3-2",
        "dealStatus": "Active",
        "dealName": "Test deal IV91",
        "exchangeName": "Smaato",
        "dealType": "PG",
        "campaignCount": 3
      },
      {
        "id": 378,
        "dealId": "gp8n",
        "dealStatus": "Active",
        "dealName": "Smaato CTV Deal",
        "exchangeName": "Smaato",
        "dealType": "PMP",
        "campaignCount": 22
      }
    ]
  }
}

Get list of deal types​

GET
Response properties
dealTypeList
object		Deal type details list.
dealTypeList object properties
displayName
integer		Display name.
name
string		Name.
id
string		ID.
order
string		Order.
Response 200
{
  "success": true,
  "data": {
    "totalRecords": 2,
    "filteredRecords": 2,
    "dealTypeList": [
      {
        "displayName": "PMP Deal",
        "name": "PMP deal",
        "id": 1,
        "order": 1
      },
      {
        "displayName": "PG Deal",
        "name": "PG deal",
        "id": 2,
        "order": 2
      }
    ]
  }
}

Get list of deal statuses​

GET
Response properties
dealStatuses
object		Deal type details list.
dealStatuses object properties
displayName
integer		Display name.
name
string		Name.
id
string		ID.
order
string		Order.
Response 200
{
  "success": true,
  "data": {
    "dealStatuses": [
      {
        "name": "active",
        "id": 1,
        "label": "Active",
        "order": 1
      },
      {
        "name": "inactive",
        "id": 2,
        "label": "Inactive",
        "order": 2
      }
    ],
    "totalRecords": 2,
    "filteredRecords": 2
  }
}

Private Marketplace (PMP) deals details​

Get PMP deals list​

POST

Get a list of PMP deals based on desired filters available for user.

A PMP deal id can be used in the Create a new inventory group endpoint or to perform various actions in PMP Management endpoints.

Request schema
groupId
integer		Filters PMP deals by group ID.
active
boolean		Filters for active (true) or inactive (false) deals.
searchKeywords
array of strings		Strings used to search by dealId, dealName, or description.
creativeTypes
array of integers		Creative type IDs.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
exchanges
array of integers		Exchange IDs.
ids
array of integers		PMP Deal IDs.
dealStatuses
array of strings		Deal statuses, allowed values: inUse, unUsed, and inActive.
owIds
array of integers		Organization Workspace IDs.
pageNo
integer		Page number of retrieved data, default: 1.
noOfEntries
integer		Number of deals to retrieve per page, default: 50.
sortBy
string		Sort entries by ascending (+dealId) or descending (-dealId).
Response properties
pmpDealData
integer		PMP deals list details.
pmpDealData object properties
id
integer		PMP deal ID.
dealId
string		Deal ID.
dealName
string		PMP deal name.
description
string		Deal description.
cpm
integer		Cost per mille.
dealCurationTypeId
integer		Curation type ID.
creativeTypes
array of string		List of creative types.
exchanges
array of strings		List of exchanges.
active
boolean		Indicates that deal is active: true.
shared
boolean		Indicates that this deal is shared, not private: true.
created
integer		Unix epoch creation date, in milliseconds.
assignedToCustomers
array of integers		List of Customer deal is assigned to.
assignedToCampaigns
array of integers		List of campaigns deal is assigned to.
Request sample
{
    "groupId": 1,
    "active": true,
    "searchKeywords": [
        "keyword1",
        "keyword2"
    ],
    "creativeTypes": [
        1,
        2,
        3
    ],
    "exchanges": [
        1,
        2,
        3,
        4
    ],
    "ids": [
        1,
        2,
        3,
        4
    ],
    "dealStatuses": [
        "inUse",
        "unUsed",
        "inActive"
    ],
    "sortBy": "-dealId",
    "noOfEntries": 2,
    "pageNo": 1
}
Response 200
{
    "success": true,
    "data": {
        "filteredRecords": 1,
        "filteredList": [
            {
                "id": 115,
                "dealId": "1476907757380667148",
                "dealName": "85%+ Completion",
                "description": "85%+ Completion",
                "cpm": 20,
                "dealCurationTypeId": 1,
                "creativeTypes": [
                    "video"
                ],
                "exchanges": [
                    "Oath"
                ],
                "active": true,
                "shared": false,
                "created": 1597658148,
                "assignedToCustomers": [
                    1,
                    2
                ],
                "assignedToCampaigns": [
                    11223,
                    65333
                ]
            }
        ]
    }
}
More responses
Response 422
{
    "success": false,
    "errorObjects": [
        {
            "error": "Invalid sortBy value."
        }
    ]
}
Response 500
{
    "success": false,
    "errorObjects": [
        {
            "error": "server encountered an error !"
        }
    ]
}

Get PMP deal details by IDs​

GET
Path parameters
id
integer		PMP Deal ID.
Response properties
pmpDealData
integer		PMP deals list details.
pmpDealData object properties
id
integer		PMP deal ID.
dealId
string		Deal ID.
dealName
string		PMP deal name.
description
string		Deal description.
cpm
integer		Cost per mille.
dealCurationTypeId
integer		Curation type ID.
creativeTypes
array of string		List of creative types.
exchanges
array of strings		List of exchanges.
active
boolean		Indicates that deal is active: true.
shared
boolean		Indicates that this deal is shared, not private: true.
created
integer		Unix epoch creation date, in milliseconds.
assignedToCustomers
array of integers		List of Customer deal is assigned to.
assignedToCampaigns
array of integers		List of campaigns deal is assigned to.
Response 200
{
  "success": true,
  "data": {
    "id": 459,
    "dealId": "BySuper_toAdvertiser",
    "dealName": "BySuper_toAdvertiser_stageSharedOnly",
    "description": "BySuper_toAdvertiser",
    "cpm": 10,
    "dealCurationTypeId": 2,
    "creativeTypes": [
      "html",
      "video",
      "native"
    ],
    "exchanges": [
      "Equativ"
    ],
    "active": true,
    "created": 1716877559,
    "assignedToCustomers": [
      201427
    ],
    "assignedToCampaigns": [
      2046372,
      2053221
    ]
  }
}

Get list of Customers associated with campaigns for a PMP deal​

GET
Path parameters
dealId
integer		PMP Deal ID.
Query parameters
owIds
integer		Organization Workspace IDs.
Response properties
data
array of integers		Customer OW IDs.
Response 200
{
  "success": true,
  "data": [
    201427
  ]
}

Get count of PMP deals for all statuses​

GET
Response properties
All
integer		Total count.
inActive
integer		Inactive count.
inUse
integer		In use count.
unUsed
integer		Unused count.
Response 200
{
  "success": true,
  "data": {
    "All": 351,
    "inActive": 48,
    "inUse": 266,
    "unUsed": 37
  }
}

PMP management​

Create, update, or delete PMP deals using the methods and endpoints outlined in this section.

Resource properties​

Create or update PMP deals using the following properties in the request body schema.

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

Create PMP deal​

POST

Create a new PMP deal referencing the resource properties for the request schema.

Required fields:

  • dealId
  • dealName
  • exchangeId
  • active

Response properties
id
integer		PMP deal ID.
message
string		Success message.
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 !"
        }
    ]
}

Update PMP deal​

PATCH

Update an existing PMP deal.

Path parameters
id
integer		PMP deal ID.

Response properties
id
integer		PMP deal ID.
message
string		Success message.
Request sample
{
    "dealName": "New Deal Name"
}

Response 200
{
    "success": true,
    "data": {
        "id": 461,
        "message": "New Deal Name updated successfully"
    }
}

Delete PMP deal​

DELETE

Delete an existing PMP deal.

Query parameters
ids
list of integers		PMP Deal IDs to delete.
Response properties
id
array of integers		PMP deal IDs.
message
string		Success message.
Response 200
{
    "success": true,
    "data": {
        "id": [
            470,
            471
        ],
        "message": "Deal/s deleted successfully"
    }
}

Programmatic Guaranteed (PG) deals details​

Get PG deals list​

GET

Get a list of PG deals available for the user.

A PG deal id can be used in the Get PG deals details by ID endpoint or to perform various actions in PG management endpoints.

Query parameters
searchField
string		Filter results by search field.
noOfEntries
integer		Number of deals to retrieve per page, default: 20.
pageNo
integer		Page number of retrieved data, default: 1.
sortBy
string		Sort results by ascending (+) or descending (-), supported values: id, dealName, cmp.
Default: -id.
ids
array of integers		IDs of the primary key of PG deals.
paymentTypeIds
array of integers		Payment type ID.
Supported values
1Publisher
2Platform
statusIds
array of integers		Status IDs.
exchangeIds
array of integers		Exchange IDs.
Response properties
pgDealData
integer		PG deals list details.
pgDealData object properties
id
integer		PG deal ID.
dealId
string		Deal ID.
dealName
string		PG deal name.
statusId
integer		Status ID.
description
string		Deal description.
paymentTypeId
integer		Payment type ID.
Supported values
1Publisher
2Platform
exchangeId
integer		Exchange ID.
created
integer		Unix epoch creation date, in milliseconds.
activeCampaignIds
array of integers		List of active campaigns deal is assigned to.
otherCampaignIds
array of integers		List of all other status campaigns deal is assigned to.
deleteAllowed
boolean		Indicates deal can be deleted: true.
Response 200
{
    "success": true,
    "data": {
        "totalRecords": 61,
        "filteredRecords": 4,
        "pgDealData": [
            {
                "id": 873,
                "dealId": "PM-RTY-98765",
                "dealName": "Demo Deal D4",
                "statusId": 1,
                "description": "Demo deal description D4",
                "paymentTypeId": 2,
                "exchangeId": 11,
                "created": 1719723041347,
                "activeCampaignIds": [],
                "otherCampaignIds": [
                    506172,
                    506173,
                    506174,
                    506175,
                    506176,
                    506177,
                    506178
                ],
                "deleteAllowed": true
            },
            {
                "id": 872,
                "dealId": "PM-QWE-54321",
                "dealName": "Sample Deal C3",
                "statusId": 1,
                "description": "Sample deal description C3",
                "paymentTypeId": 2,
                "exchangeId": 78,
                "created": 1719722247192,
                "activeCampaignIds": [
                    506162,
                    506161,
                    506160
                ],
                "otherCampaignIds": [
                    506163,
                    506166,
                    506165,
                    506164
                ],
                "deleteAllowed": false
            },
            ...
        ]
    }
}
More responses
Response 401
{
    "success": false,
    "errorObjects": [
        {
            "error": "Unauthorized"
        }
    ]
}
Response 422
{
    "success": false,
    "errorObjects": [
        {
            "error": "Invalid sortBy value."
        }
    ]
}
Response 500
{
    "success": false,
    "errorObjects": [
        {
            "error": "server encountered an error !"
        }
    ]
}

Get PG deals details by ID​

GET

Get PG deal details by specified ID including its associated campaign IDs.

Path parameters
id
integer		PG deal ID.
Response properties
pgDealData
integer		PG deals list details.
pgDealData object properties
id
integer		PG deal ID.
dealId
string		Deal ID.
statusId
integer		Status ID.
dealName
string		PG deal name.
description
string		Deal description.
paymentTypeId
integer		Payment type ID.
Supported values
1Publisher
2Platform
exchangeId
integer		Exchange ID.
created
integer		Unix epoch creation date, in milliseconds.
activeCampaignIds
array of integers		List of active campaigns deal is assigned to.
otherCampaignIds
array of integers		List of all other status campaigns deal is assigned to.
Response 200
{
    "success": true,
    "data": {
        "id": 872,
        "dealId": "PM-QWE-54321",
        "dealName": "Sample Deal C3",
        "statusId": 1,
        "description": "Sample deal description C3",
        "paymentTypeId": 2,
        "exchangeId": 78,
        "created": 1719722247192,
        "activeCampaignIds": [
            506160,
            506161,
            506162
        ],
        "otherCampaignIds": [
            506163,
            506164,
            506165,
            506166
        ]
    }
}

PG management​

Create, update, or delete PG deals using the methods and endpoints outlined in this section.

Resource properties​

Create or update PG deals using the following properties in the request body schema.

Properties
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.
description
string		Description or notes about the deal.
paymentTypeId
integer		Payment type ID.
Supported values
1Publisher
2Platform

Create PG deal​

POST

Create a new PG deal referencing the resource properties for the request schema.

Required fields:

  • dealId
  • dealName
  • exchangeId
  • statusId

Response properties
id
integer		PG deal ID.
message
string		Success message.
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
    }
}

Update PG deal details​

PATCH

Update a PG deal.

Path parameters
id
integer		PG deal ID.

Response properties
data
string		Success message.
Request sample
{
    "dealId": "PM-ABC-12345",
    "dealName": "Premium Advertising Package",
    "statusId": 2,
    "description": "Comprehensive advertising package including display, video, and social media placements for maximum exposure.",
    "cpm": 40,
    "paymentTypeId": 2,
    "exchangeId": 11
}
Response 200
{
    "success": true,
    "data": "PG deal updated successfully"
}

Delete PG deal​

DELETE

Delete an existing PG deal.

Query parameters
ids
integer required		Comma-separated PG deal IDs to delete.
Response properties
data
string		Success message.
Response 200
{
    "success": true,
    "data": "PG Deal deleted successfully"
}
Have a question?
Ask the community
Was this page helpful?