Bid Model API

Overview

The Bid Model API allows you to optimize advertising Campaigns for better performance. You can fine-tune metrics such as where ads appear (Include/Exclude), manage Campaign priority, and dimensions by which a Campaign is subdivided. This page covers the common endpoints and methods associated with the Bid Model API.

Bid Modeling comprises the following tools:

• Spend Ratio: determines how the Campaign budget is distributed across various dimensions, expressed as a percentage in two types
  1. Strict: budget is allocated up to its specified percentage as able, but will underspend if unable to meet that ratio
  2. Flexible: budget will reallocate if unable to fulfill its specified percentage
• Dimension Priority: dictates the sequence of bidding for specified targeting Dimensions, expressed as a range of 1-10
• Bid Modifier: adjusts the base bid of a Campaign for the specified Dimension that is modified, expressed as a multiplier in a range of 0.1-100

NOTE

IQM's Bid Model currently supports applying bid modifiers to the following dimensions:

• Creative: Creative ID
• Location: State, City, Zip Code
• Inventory: Open Exchange, Publisher Category*, Deal ID**

*Spend Ratios are not supported for the Publisher Category dimension subcategory. Refer to Spend Ratio Overview Help Center article for more information.

**Bid Modifiers are not supported for the Deal ID dimension subcategory. Refer to the Bid Modifier Overview Help Center article for more information.

More resources

• Create a Bid Model Tutorial
• Campaign Delivery and Optimization Help Center article

Authentication

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

Bid Modeling Details

Get List of Bid Model Bundles

GET /api/v3/bm/campaigns/{campaignId}/bundles

Get a list of Bid Model bundles for a given Campaign ID and dimension.

A bundleId can be used in various Bid Model Management endpoints to add, update, or delete Bid Modeling attributes.

Path Parameter
campaignId integer	Campaign ID

Query Parameter
dimensionId integer	Dimension ID
searchField string	Filter results by name or ID

Response Properties

bundleId integer	Bundle ID
bundleName string	Bundle name
dimensionId integer	Dimension ID
entityIds array of integers	List of entity IDs in the bundle
modellingApplied boolean	Indicates if modeling is applied to the bundle: true

JSON

Response 200

{
  "success": true,
  "data": [
    {
      "bundleId": 12,
      "bundleName": "bundle#1",
      "dimensionId": 1,
      "entityIds": [
        7,
        8,
        9
      ],
      "modellingApplied": false
    },
    {
      "bundleId": 13,
      "bundleName": "bundle#2",
      "dimensionId": 2,
      "entityIds": [
        1,
        2,
        3
      ],
      "modellingApplied": true
    }
  ]
}

TypeScript

See TypeScript Prerequisites for usage.

---

Get Modeled Entities

POST /api/v3/bm/bid-models/dimension/entity

Get a list of modeled entities and their associated modeling data for the provided Dimension ID and entity IDs.

Request Schema
dimensionId integer required	Dimension ID
entityIds array of integers required	List of entity IDs
includeCampaignInfo boolean	Indicates if Campaign info is to be included in the response, default: false
groupIdBased boolean	Indicates if entity IDs are group IDs, default: false

Response Properties

modelledEntityIds array of integers	List of modeled entity IDs
modelledCampaignDetails array of objects	List of objects containing entity ID and associated Campaign IDs

JSON

Request Sample

{
  "dimensionId": 10,
  "entityIds": [
    30200036,
    30200031,
    30200105,
    4695
  ],
  "includeCampaignInfo": true,
  "groupIdBased": true
}

Response 200

{
  "success": true,
  "data": {
    "modelledEntityIds": [
      30200036,
      30200031,
      30200105
    ],
    "modelledCampaignDetails": [
      {
        "entityId": 30200036,
        "campaignIds": [
          555804,
          556956,
          556891,
          557141,
          560100
        ]
      },
      {
        "entityId": 30200031,
        "campaignIds": [
          556979,
          555927,
          555926,
          560102,
          555925,
          555748
        ]
      },
      {
        "entityId": 30200105,
        "campaignIds": [
          555787
        ]
      },
      {
        "entityId": 4695,
        "campaignIds": []
      }
    ]
  }
}

TypeScript

See TypeScript Prerequisites for usage.

Get Campaign Dimension Statistics

GET /api/v3/bm/campaign/{campaignId}/dimensions/bid-models/count

Get dimension statistics for a given Campaign ID.

Path Parameter
campaignId integer	Campaign ID

Query Parameters
startDate integer	Unix epoch timestamp (in milliseconds) for the total count
endDate integer	Unix epoch timestamp (in milliseconds) for the total count
attributes string	List of statistics to return Supported values: totalCount, modelledCount, modelledIds

Response Properties

data object	Name-Value pairs of dimensionId and attributes object
totalCount integer	Total count of entities in a dimension
modelledCount integer	Number of entities modeled in a dimension
modelledIds object	List of modeled entity IDs

JSON

Response 200

{
  "success": true,
  "data": {
    "1": {
      "totalCount": 5,
      "modelledCount": 3,
      "modelledIds": [
        1,
        2,
        3
      ]
    },
    "3": {
      "totalCount": 0,
      "modelledCount": 0,
      "modelledIds": null
    },
    "4": {
      "totalCount": 10,
      "modelledCount": 5,
      "modelledIds": [
        1,
        2,
        3,
        4,
        5
      ]
    },
    "5": {
      "totalCount": 0,
      "modelledCount": 0,
      "modelledIds": null
    },
    "11": {
      "totalCount": 0,
      "modelledCount": 0,
      "modelledIds": null
    },
    "12": {
      "totalCount": 0,
      "modelledCount": 0,
      "modelledIds": null
    },
    "13": {
      "totalCount": 0,
      "modelledCount": 0,
      "modelledIds": null
    }
  }
}

TypeScript

See TypeScript Prerequisites for usage.

---

Get Dimension Specific Spending for a Campaign

GET /api/v3/bm/campaigns/{campaignId}/dimension/{dimensionId}/spent

Get details on total spent by dimension for a Campaign.

Path Parameters
campaignId integer	Campaign ID
dimensionId integer	Dimension ID

Response Properties

entityWiseSpent object

Name-Value pairs of dimensionId and amount spent

JSON

Response 200

{
  "success": true,
  "data": {
    "entityWiseSpent": {
      "1": 5.1,
      "2": 5.76,
      "3": 5.34
    }
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          entityWiseSpent: {
            dimensionId: number
          }
        }
      }
    }
  }
};

function getDimensionWiseEntitySpentForCampaign(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/bm/campaigns/{campaignId}/dimension/{dimensionId}/spent',
    params: {
      path: {
        campaignId: `number`,
        dimensionId: `number`
      }
    }
  };

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

---

Get List of Modeled Entities for a Campaign

POST /api/v3/bm/campaigns/{campaignId}/bid-models/dimensions/{dimensionId}

Get a list of modeled entities and their associated modeling data for the provided Campaign ID.

A Bid Model data id can be used in various Bid Model Management endpoints to update or delete Bid Modeling attributes.

Path Parameters
campaignId integer	Campaign ID
dimensionId integer	Dimension ID

Request Schema
startDate integer	Unix epoch timestamp (in milliseconds)
endDate integer	Unix epoch timestamp (in milliseconds)
timezoneId integer	Timezone ID
sortBy string	Sort the result set by specific field. For ascending use plus(+) sign and for descending use minus(-) sign, default: +priority
pageNo integer	Page number for the retrieved data, default: 1
searchField string	Search the result by provided keyword
noOfEntries integer	The maximum number of returned results per page, default: 10
skipReporting boolean	Indicates the reporting data is to be skipped, e.g. impressions and clicks will be skipped, and only Bid Modeling data will be returned

JSON

Request Sample

{
  "startDate": 1700758597000,
  "endDate": 1708194599000,
  "timezoneId": 105,
  "sortBy": "+priority",
  "pageNo": 1,
  "searchField": "ad",
  "noOfEntries": 10,
  "skipReporting": false
}

Response 200

{
  "success": true,
  "data": {
    "total": {
      "totalCount": 5,
      "impressions": 1,
      "winRate": 25,
      "clicks": 0,
      "eCPM": 4,
      "eCPC": 0,
      "dataCost": 0,
      "mediaSpent": 0.004,
      "CTR": 0,
      "spent": 0.004,
      "conversionCount": 0,
      "conversionValue": 0,
      "attributedClickThroughConversions": 0,
      "attributedViewThroughConversions": 0,
      "costPerAttributedConversions": 0,
      "attributedConversionsRate": 0,
      "returnOnAdSpend": 0,
      "VCR": 0,
      "eCPV": 0.004,
      "eCPCV": 0,
      "startCount": 0,
      "firstCount": 0,
      "midCount": 0,
      "thirdCount": 0,
      "completeCount": 0,
      "bidImpressions": 4,
      "audioVideoViewed": 0,
      "prebidCost": 0
    },
    "data": [
      {
        "bidModelData": {
          "id": 1,
          "priority": 5,
          "bidMultiplier": 1.5,
          "spendRatio": 0.8,
          "spendRatioTypeId": 2
        },
        "id": 604676,
        "name": "ad-60s",
        "isExcluded": 0,
        "modelled": false,
        "targeted": true,
        "impressions": 0,
        "winRate": 0,
        "clicks": 0,
        "eCPM": 0,
        "eCPC": 0,
        "dataCost": 0,
        "mediaSpent": 0,
        "CTR": 0,
        "spent": 0,
        "conversionCount": 0,
        "conversionValue": 0,
        "attributedClickThroughConversions": 0,
        "attributedViewThroughConversions": 0,
        "costPerAttributedConversions": 0,
        "attributedConversionsRate": 0,
        "returnOnAdSpend": 0,
        "VCR": 0,
        "eCPV": 0,
        "eCPCV": 0,
        "startCount": 0,
        "firstCount": 0,
        "midCount": 0,
        "thirdCount": 0,
        "completeCount": 0,
        "bidImpressions": 0,
        "audioVideoViewed": 0,
        "prebidCost": 0,
        "creativeStatus": "Deleted",
        "creativeThumbnailSource": "https://i.gifer.com/g2vO.gif",
        "creativeCardSource": "https://i.gifer.com/g2vO.gif",
        "creativeType": "Video",
        "spentDistribution": 0
      },
      {
        "bidModelData": {
          "id": 1,
          "priority": 5,
          "bidMultiplier": 1.5,
          "spendRatio": 0.8,
          "spendRatioTypeId": 2
        },
        "id": 604675,
        "name": "ad-45s",
        "isExcluded": 1,
        "modelled": false,
        "targeted": true,
        "impressions": 1,
        "winRate": 100,
        "clicks": 0,
        "eCPM": 4,
        "eCPC": 0,
        "dataCost": 0,
        "mediaSpent": 0.004,
        "CTR": 0,
        "spent": 0.004,
        "conversionCount": 0,
        "conversionValue": 0,
        "attributedClickThroughConversions": 0,
        "attributedViewThroughConversions": 0,
        "costPerAttributedConversions": 0,
        "attributedConversionsRate": 0,
        "returnOnAdSpend": 0,
        "VCR": 0,
        "eCPV": 0.004,
        "eCPCV": 0,
        "startCount": 0,
        "firstCount": 0,
        "midCount": 0,
        "thirdCount": 0,
        "completeCount": 0,
        "bidImpressions": 1,
        "audioVideoViewed": 0,
        "prebidCost": 0,
        "creativeStatus": "Running",
        "creativeThumbnailSource": "https://i.gifer.com/g2vO.gif",
        "creativeCardSource": "https://i.gifer.com/g2vO.gif",
        "creativeType": "Video",
        "spentDistribution": 0
      }
    ],
    "totalRecords": 5,
    "filteredRecords": 2,
    "campaignBidDetails": {
      "baseBid": 20,
      "maxBid": 20,
      "currentPriority": 1,
      "nextPerformanceCheck": 1740736800000
    }
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          totalCount: number;
          dimensionWiseCount: {
            dimensionId: number;
            count: number
          }[]
        }
      }
    }
  }
};

function getModelledItemsCount(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/bm/campaigns/{campaignId}/bid-models/count',
    params: {
      query: {
        dimensionId: `number`
      },
      path: {
        campaignId: `number`,
      }
    }
  };

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

Response Properties

bidModelData object	Object containing Bid Model Data properties
bidModelData object properties id integer Bid Model data ID priority integer Assigned priority: [ 1 .. 10 ] bidMultiplier integer Bid Multiplier [ 0.1 .. 100 ] spendRatio integer Spend ratio [ 0 .. 100 ] spendRatioTypeId integer Spend ratio type ID Flexible: 1 Strict: 2
id integer	Campaign ID
name string	Campaign name
isExcluded integer	Indicates the entity is excluded from the Bid Model: true
modelled boolean	Indicates entity is modeled: true
targeted boolean	Indicates entity is targeted in the Campaign or served via other targeting parameter: true
totalCount integer	Count of total records
impressions integer	Impressions count
winRate integer	Percentage of impressions bid on and won
clicks integer	The number of times a user clicked on an ad
eCPM integer	Effective cost per mille
eCPC integer	Effective cost per click
dataCost integer	Data cost applied on Campaigns of given Customer
mediaSpent integer	Media spent
CTR integer	Click-through rate
spent integer	Amount spent
conversionCount integer	Conversion count
conversionValue integer	Conversion value
attributedClickThroughConversion integer	The number of Conversions that occurred after a user clicked on an ad
attributedViewThroughConversion integer	The number of Conversions that occurred after a user viewed an ad but did not click on it
costPerAttributedConversions integer	Cost per attributed Conversion
attributedConversionsRate integer	Total attributed Conversion rate
returnOnAdSpend integer	Return on ad spend
VCR integer	Video completion rate
eCPV integer	Effective cost per visit
eCPCV integer	Effective cost per completed view
startCount integer	Ad viewing metric, video start
firstCount integer	Ad viewing metric, video first quarter
midCount integer	Ad viewing metric, video midpoint
thirdCount integer	Ad viewing metric, video last quarter
completeCount integer	Ad viewing metric, video completed
bidImpressions integer	Bid on impressions count
audioVideoViewed integer	Audio/video viewed
prebidCost integer	Data cost of Pre-bid Audiences

Include/Exclude Management

Devices, Exchanges, Traffic

POST /api/v2/cmp/deviceType/includeExclude
POST /api/v2/cmp/exchange/includeExclude
POST /api/v2/cmp/trafficsource/includeExclude

The Include and Exclude options allow the you to control where ads appear.

For IDs see endpoint documentation for Device Type, Exchanges, and Traffic Source in the Master API.

See the Allowlist and Blocklist Overview Help Center article for more information.

Request Schema
ids string	ID of entity
isExcluded integer	Allow targeted entity: 0 Block targeted entity: 1
campaignId integer	Campaign ID

Response Properties

message string

Success message

JSON

Request Sample

{
  "ids": "15",
  "isExcluded": 0,
  "campaignId": 214269
}

Response 200 (device type)

{
  "statusCode": 200,
  "responseObject": {
    "message": "The Device Types have been allowed."
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json;charset=UTF-8": {
        statusCode: number;
        responseObject: {
          message: string;
        };
      };
    };
  };
};

function DeviceType-includeExclude(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v2/cmp/deviceType/includeExclude',
    params: {
      header: {
        "X-IAA-HOST": `string`
      }
    },
    requestBody: {
      content: {
        "application/json": {
          ids: `string`,
          isExcluded: `number`,
          campaignId: `number`,
        }
      }
    }
  };

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

---

Include/Exclude Entities From a Campaign

POST /api/v3/bm/campaigns/{campaignId}/include-Exclude/dimensions/{dimensionId}

Optimize a Campaign by updating the status of specified entities to be either included or excluded with path parameters campaignId and dimensionId.

Path
campaignId integer	Campaign ID
dimensionId integer	Dimension ID

Request Schema
ids string	Entity ID(s) to target or block
isExcluded integer	Target entity: 0 Block entity: 1

Response Properties

data string

Success message

JSON

Request Sample (Creatives)

{
  "ids": "604675,604084",
  "isExcluded": 0
}

Response 200 (Creatives)

{
  "success": true,
  "data": "Creatives successfully targeted for the campaign."
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function toggleCampaignDimensionStatus(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/bm/campaigns/{campaignId}/include-exclude/dimensions/{dimensionId}',
    params: {
      path: {
        campaignId: `number`,
        dimensionId: `number`
      }
    },
    requestBody: {
      content: {
        "application/json": {
          advertiserId: `number`,
          dspId: `number`,
          owId: `number`,
          uowId: `number`,
          campaignId: `number`,
          ids: `string`,
          isExcluded: `number`
        }
      }
    }
  };

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

Bid Modeling Management

Bid Modeling Criteria

• Bid Multiplier & Dimension Priority
  • Campaign must be at least 3 days long
  • Campaign's daily budget must be at least $100
  • Base bid and max bid price must be defined for the Campaign
• Spend Ratio
  • Strict spend ratios must equal 100% across all allocated dimensions
  • Flexible spend ratios require a dimension priority

NOTE

IQM currently supports Bid Modeling for the following dimensions:

• Creative: Creative ID
• Location: State, City, Zip Code
• Inventory: Open Exchange, Publisher Category*, Deal ID**

*Note that Spend Ratios are not supported for the Publisher Category dimension subcategory. Refer to Spend Ratio Overview Help Center article for more information.

**Not that Bid Modifiers are not supported for the Deal ID dimension subcategory. Refer to the Bid Modifier Overview Help Center article for more information.

Manage Bid Modeling

PUT /api/v3/bm/campaigns/{campaignId}/bid-models/{dimensionId}

Manage Bid Modeling configurations for a given Campaign and Dimension. Supports operations for adding, updating, and deleting Bid Modeling attributes for single entities or entity bundles.

See the request examples in the right-hand code block to see how to structure requests for each operation. Be sure to review Bid Modeling Criteria before applying Bid Modeling to a Campaign.

ADD: Create new Bid Modeling for a single entity or entity bundles.

• Create a bundle: set entityTypeId to bundle (2), and entityId to any negative number, this will create a new bundle with the provided bundleName and entityIds.
• Existing bundle: set entityTypeId to bundle (2), and entityId to the existing bundle ID to add Bid Modeling to the existing bundle.

UPDATE: Update existing Bid Modeling attributes for a single entity or entity bundles.

DELETE: Remove Bid Modeling or unbundle a bundle.

INCLUDE/EXCLUDE Map: Defines which entity IDs are explicitly included or excluded in bid modeling.

Path Parameters
campaignId integer	Campaign ID
dimensionId integer	Dimension ID

Request Schema
actionWiseBidModelEntities object	Object containing Bid Model entity details mapped to operations ADD, UPDATE, DELETE
actionWiseBidModelEntities object properties bidModelEntityDetails object Object containing Bid Model entity details, for ADD and UPDATE operations bidModelEntityDetails object properties entityId integer required Bid Model entity ID entityTypeId integer required Bid Model entity type ID 1: Individual entity 2: Bundle entity 3: Other entity priority integer required Assigned priority: [ 1 .. 10 ] bidMultiplier integer required Bid Multiplier [ 0.1 .. 100 ] spendRatio integer required Spend ratio [ 0 .. 100 ] spendRatioTypeId integer required Spend ratio type ID Flexible: 1 Strict: 2 bundleName string required Bundle name, required when entityTypeId is set to bundle entity entityIds array of integers required Entity IDs, required when entityTypeId is set to bundle entity bidModelDataId array of integers Array of Bid Model Data IDs for DELETE operation bundleIds array of integers Array of Bundle IDs for DELETE operation
inclusionExclusionEntityMap object	Object containing entity mappings
inclusionExclusionEntityMap object properties INCLUDE array of integers Entity IDs to include EXCLUDE array of integers Entity IDs to exclude
baseBid integer	Base bid amount

JSON

Request ExamplesFull Bid Modeling UpdateAdd Bid Modeling (initial setup)Update Existing Bid ModelingUpdate Bid Modeling AttributesRemove Bid Modeling EntitiesDelete BundlesUnbundle EntitiesSet Include/Exclude EntitiesUpdate Base Bid With Include/Exclude

{
  "actionWiseBidModelEntities": {
    "ADD": {
      "bidModelEntityDetails": [
        {
          "entityId": 50,
          "entityTypeId": 1,
          "priority": 1,
          "bidMultiplier": 2,
          "spendRatio": 100,
          "spendRatioTypeId": 1
        },
        {
          "entityId": -2,
          "entityTypeId": 2,
          "priority": 1,
          "bidMultiplier": 2,
          "spendRatio": 100,
          "spendRatioTypeId": 1,
          "bundleName": "bundle-1",
          "entityIds": [
            1,
            2,
            3
          ]
        },
        {
          "entityId": 232,
          "entityTypeId": 2,
          "priority": 1,
          "bidMultiplier": 2,
          "spendRatio": 100,
          "spendRatioTypeId": 1,
          "bundleName": "bundle-1",
          "entityIds": [
            1,
            2,
            3
          ]
        }
      ]
    },
    "DELETE": {
      "bidModelDataId": [
        1,
        2,
        3,
        4
      ],
      "bundleIds": [
        1,
        2,
        3
      ]
    },
    "UPDATE": {
      "bidModelEntityDetails": [
        {
          "bidModelDataId": 50,
          "priority": 1,
          "bidMultiplier": 2,
          "spendRatio": 100,
          "spendRatioTypeId": 1,
          "bundleName": "Bundle-1",
          "entityIds": [
            1,
            2,
            3,
            4,
            5
          ]
        },
        {
          "bidModelDataId": 51,
          "priority": 1,
          "bidMultiplier": 2,
          "spendRatio": 100,
          "spendRatioTypeId": 1
        },
        {
          "bidModelDataId": 52,
          "priority": 1,
          "spendRatio": 100
        },
        {
          "bidModelDataId": 53,
          "bundleName": "Bundle-1",
          "entityIds": [
            1,
            2,
            3,
            4,
            5
          ]
        }
      ]
    }
  },
  "inclusionExclusionEntityMap": {
    "INCLUDE": [
      1
    ],
    "EXCLUDE": [
      2,
      3,
      4
    ]
  },
  "baseBid": 3
}

{
  "actionWiseBidModelEntities": {
    "ADD": {
      "bidModelEntityDetails": [
        {
          "entityId": 50,
          "entityTypeId": 1,
          "priority": 1,
          "bidMultiplier": 2,
          "spendRatio": 100,
          "spendRatioTypeId": 1
        },
        {
          "entityId": -2,
          "entityTypeId": 2,
          "priority": 1,
          "bidMultiplier": 2,
          "spendRatio": 100,
          "spendRatioTypeId": 1,
          "bundleName": "bundle-1",
          "entityIds": [
            1,
            2,
            3
          ]
        },
        {
          "entityId": 232,
          "entityTypeId": 2,
          "priority": 1,
          "bidMultiplier": 2,
          "spendRatio": 100,
          "spendRatioTypeId": 1,
          "bundleName": "bundle-1",
          "entityIds": [
            1,
            2,
            3
          ]
        }
      ]
    }
  }
}

{
  "actionWiseBidModelEntities": {
    "UPDATE": {
      "bidModelEntityDetails": [
        {
          "bidModelDataId": 50,
          "priority": 1,
          "bidMultiplier": 2,
          "spendRatio": 100,
          "spendRatioTypeId": 1,
          "bundleName": "Bundle-1",
          "bundleId": 52,
          "entityIds": [
            1,
            2,
            3,
            4,
            5
          ]
        },
        {
          "bidModelDataId": 51,
          "priority": 1,
          "bidMultiplier": 2,
          "spendRatio": 100,
          "spendRatioTypeId": 1
        },
        {
          "bidModelDataId": 52,
          "priority": 1,
          "spendRatio": 100
        },
        {
          "bidModelDataId": 53,
          "bundleName": "Bundle-1",
          "entityIds": [
            1,
            2,
            3,
            4,
            5
          ]
        }
      ]
    }
  }
}

{
  "actionWiseBidModelEntities": {
    "UPDATE": {
      "bidModelEntityDetails": [
        {
          "bidModelDataId": 50,
          "priority": 1
        },
        {
          "bidModelDataId": 51,
          "bidMultiplier": 2
        },
        {
          "bidModelDataId": 52,
          "priority": 1,
          "spendRatio": 100
        },
        {
          "bidModelDataId": 53,
          "bundleName": "Bundle-1",
          "entityIds": [
            1,
            2,
            3,
            4,
            5
          ]
        },
        {
          "bidModelDataId": 51,
          "priority": 1,
          "bidMultiplier": 2,
          "spendRatio": 100,
          "spendRatioTypeId": 1
        },
        {
          "bidModelDataId": 51,
          "priority": 1,
          "bidMultiplier": 2,
          "spendRatio": 100,
          "spendRatioTypeId": 1,
          "bundleName": "Bundle-1",
          "entityIds": [
            1,
            2,
            3,
            4,
            5
          ]
        }
      ]
    }
  }
}

{
  "actionWiseBidModelEntities": {
    "DELETE": {
      "bidModelDataId": [
        1,
        2,
        3,
        4
      ]
    }
  }
}

{
  "actionWiseBidModelEntities": {
    "DELETE": {
      "bundleIds": [
        1,
        2,
        3,
        4
      ]
    }
  }
}

{
  "actionWiseBidModelEntities": {
    "ADD": {
      "bidModelEntityDetails": [
        {
          "entityId": 50,
          "entityTypeId": 1,
          "priority": 1,
          "bidMultiplier": 2,
          "spendRatio": 100,
          "spendRatioTypeId": 1
        },
        {
          "entityId": 51,
          "entityTypeId": 1,
          "priority": 1,
          "bidMultiplier": 2,
          "spendRatio": 100,
          "spendRatioTypeId": 1
        },
        {
          "entityId": -1,
          "entityTypeId": 3,
          "priority": 1,
          "bidMultiplier": 2,
          "spendRatio": 100,
          "spendRatioTypeId": 1
        }
      ]
    },
    "DELETE": {
      "bundleIds": [
        1
      ]
    }
  }
}

{
  "inclusionExclusionEntityMap": {
    "INCLUDE": [
      1
    ],
    "EXCLUDE": [
      2,
      3,
      4
    ]
  }
}

{
  "inclusionExclusionEntityMap": {
    "INCLUDE": [
      1
    ],
    "EXCLUDE": [
      2,
      3,
      4
    ]
  },
  "baseBid": 3
}

Response 200

{
  "success": true,
  "data": "Bid Model updated successfully"
}

TypeScript

See TypeScript Prerequisites for usage.

---

Create Bid Model Bundle

POST /api/v3/bm/campaigns/{campaignId}/dimensions/{dimensionId}/bundles

Create a Bid Model bundle for the specified Campaign and Dimension IDs. A Bid Model Bundle allows you to group multiple dimension entities and apply bid modeling rules at the bundle level with the Manage Bid Modeling endpoint.

Path Parameters
campaignId integer	Campaign ID
dimensionId integer	Dimension ID

Request Schema
bundleName string	Bundle name
entityIds array of integers	Entity IDs to include in the bundle

Response Properties

data string

Success message

JSON

Request Sample

{
  "bundleName": "Bundle for campaign 1",
  "entityIds": [
    10895823
  ]
}

Response 200

{
  "success": true,
  "data": {
    "message": "Bundle created successfully",
    "id": 5
  }
}

TypeScript

See TypeScript Prerequisites for usage.

---

Update Bid Model Bundle

PATCH /api/v3/bm/campaigns/{campaignId}/dimensions/{dimensionId}/bundles

Update a Bid Model bundle for the specified Campaign and Dimension IDs.

Path Parameters
campaignId integer	Campaign ID
dimensionId integer	Dimension ID

Request Schema
bundleDetailList array of objects	Array of objects containing bundle details to update
bundleDetailList object properties bundleId integer required Bundle ID bundleName string required Bundle name entityIds array of integers Entity IDs to include in the bundle

JSON

Request Sample

{
  "bundleDetailList": [
    {
      "bundleId": 3,
      "bundleName": "Bundle#3",
      "entityIds": [
        30,
        31
      ]
    },
    {
      "bundleId": 4,
      "bundleName": "Bundle#4"
    },
    {
      "bundleId": 5,
      "entityIds": [
        13,
        14
      ]
    }
  ]
}

Response 200

{
  "success": true,
  "data": "Bundle updated successfully"
}

TypeScript

See TypeScript Prerequisites for usage.

---

Delete Bid Model Bundle

DELETE /api/v3/bm/campaigns/{campaignId}/dimensions{dimensionId}/bundles

Delete a Bid Model bundle for the specified Campaign and Dimension IDs.

Path Parameters
campaignId integer	Campaign ID
dimensionIds string	Comma separated Dimension IDs to delete Bid Modeling data for

Request Schema
bundleIds array of integers	Bundle IDs to delete

Response Properties

data string

Success message

JSON

Response 200

{
  "success": true,
  "data": "Bid Modelling deleted successfully!"
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function deleteBidModelling(): Promise<Responses> {
  const options = {
    method: 'DELETE',
    url: 'https://api.iqm.com/api/v3/bm/campaigns/{campaignId}/bid-models',
    params: {
      query?: {
        dimensionIds?: `string`,
        bidModelDataIds?: `string`,
        campaignId?: `number`,
      },
      path: {
        campaignId: `number`
      }
    },
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Manage Insertion Order Bid Modeling

PUT /api/v3/bm/io/{ioId}/bid-models

Add, update, or remove Bid Modeling at the Insertion Order level. Changes will be applied to all Campaigns associated with specified Insertion Order.

Path
ioId integer	Insertion Order ID

Request Schema
bidModelRequests array of objects required	Objects containing Bid Model actions
bidModelRequests object properties action string Supported values specifying Bid Model action: ADD, UPDATE, DELETE bidModelData object Object containing Bid Model data bidModelData object properties id integer Bid Model data ID priority integer Assigned priority: [ 1 .. 10 ] bidMultiplier integer Bid Multiplier [ 0.1 .. 100 ] spendRatio integer Spend ratio [ 0 .. 100 ] spendRatioTypeId integer Spend ratio type ID Flexible: 1 Strict: 2 dimensionEntityMappings object Object containing entity mappings dimensionEntityMappings object properties dimensionId integer Dimension ID entityId integer Entity ID bidModelDataIds array of integers Bid Model Data IDs
baseBid integer required	Base value on which bid modifiers are applied. For example, if base bid is 2, and bid modifier is 2, then bid price is: 2x2=4
excludeDimensionEntityMappings object required	Object containing dimension entity mappings to exclude
excludeDimensionEntityMappings object properties advertiserId integer Advertiser ID dspId integer DSP ID owId integer Organization Workspace ID uowId integer User Organization Workspace ID campaignId integer Campaign ID ids string Comma separated IDs isExcluded boolean Indicates the entity is excluded from the Bid Model: true dimensionId integer Dimension ID

Response Properties

data string

Success message

JSON

Request Sample

{
  "bidModelRequests": [
    {
      "action": "ADD",
      "bidModelData": {
        "priority": 1
      },
      "dimensionEntityMappings": [
        {
          "campaignId": 1
        }
      ]
    },
    {
      "action": "UPDATE",
      "bidModelData": {
        "id": 3677,
        "priority": 2
      }
    },
    {
      "action": "DELETE",
      "bidModelDataIds": [
        893
      ]
    }
  ]
}

Response 200

{
  "success": true,
  "data": "Priority Updated Successfully"
}

More Responses

Response 403

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

Response 422

{
  "success": false,
  "errorObjects": [
    {
      "error": "Cannot assign priority as campaign is in invalid status"
    }
  ]
}

Response 500

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

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: string
      }
    };
  };
  403: {
    content: {
      "application/json": {
        success: boolean;
        errorObjects: {
          error: string
        }[]
      }
    };
  };
  422: {
    content: {
      "application/json": {
        success: boolean;
        errorObjects: {
          error: string
        }[]
      }
    };
  };
  500: {
    content: {
      "application/json": {
        success: boolean;
        errorObjects: {
          error: string
        }[]
      }
    };
  };
};

function managePriorityToCampaign(): Promise<Responses> {
  const options = {
    method: 'PUT',
    url: 'https://api.iqm.com/api/v3/bm/io/{ioId}/bid-models',
    params: {
      path: {
        ioId: `number`
      }
    },
    requestBody: {
      content: {
        "application/json": {
          bidModelRequests?: [
            {
              bidModelData?: {
                id?: `number`,
                priority?: `number`,
                bidMultiplier?: `number`,
                spendRatio?: `number`,
                spendRatioTypeId?: `number`,
              },
              dimensionEntityMappings?: [
                {
                  dimensionId?: `number`,
                  entityId?: `number`,
                }
              ],
              action: [ "ADD" | "UPDATE" | "DELETE" ],
              bidModelDataIds?: `[number]`,
            }
          ],
          baseBid?: `number`,
          excludeDimensionEntityMappings?: [
            {
              advertiserId?: `number`,
              dspId?: `number`,
              owId?: `number`,
              uowId?: `number`,
              campaignId?: `number`,
              ids?: `string`,
              isExcluded?: `number`,
              dimensionId?: `number`,
            }
          ]  
        } 
      }
    }
  };

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

---

Manage Insertion Order Priority

POST /api/v3/bm/io/{ioId}/bid-models
DEL /api/v3/bm/io/{ioId}/bid-models
PATCH /api/v3/bm/io/{ioId}/bid-models

Add, update, or delete priorities at the Insertion Order level. Changes will be applied to all Campaigns associated with the Insertion Order.

Assigning priority to Campaigns allows the you to establish a sequential order of bidding to fine-tune their targeting strategy. Priority may be assigned (ranging 1 to 10) to multiple campaignIds.

Query Parameters	DELETE only
campaignIds string	Comma separated Campaign IDs

Path Parameters
ioId integer	Insertion Order ID

Request Schema
priority integer required	Assigned priority: [ 1 .. 10 ]
campaignIds array of integers required	Campaign IDs

Response Properties

data string

Success message

JSON

Request Sample

{
  "priority": 1,
  "campaignIds": [
    123456, 
    234567, 
    345678, 
    456789
  ]
}

response 200

{
  "success": true,
  "data": "Priority Updated Successfully"
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function addPriorityToCampaign(): Promise<Responses> {
  const options = {
    method: 'POST'
    url: 'https://api.iqm.com/api/v3/bm/io/{ioId}/bid-models',
    params: {
      path: {
        ioId: `number`
      }
    },
    requestBody: {
      content: {
        "application/json": {
          priority: `number`,
          campaignIds: `array of numbers`,
        }
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

function deletePriorityToCampaign(): Promise<Responses> {
  const options = {
    method: 'DELETE'
    url: 'https://api.iqm.com/api/v3/bm/io/{ioId}/bid-models',
    params: {
      path: {
        ioId: `number`
      }
    },
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

  function updatePriorityToCampaign(): Promise<Responses> {
  const options = {
    method: 'PATCH'
  url: 'https://api.iqm.com/api/v3/bm/io/{ioId}/bid-models',
    params: {
      path: {
        ioId: `number`
      }
    },
    requestBody: {
      content: {
        "application/json": {
          priority: `number`,
          campaignIds: `array of numbers`,
        }
      }
    }
  };

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

Bid Model Metrics and Dimensions

Get Metrics Report For a Given Campaign and Dimension

POST /api/v3/bm/campaigns/{campaignId}/reports/{dimensionId}

Path Parameters
campaignId integer	Campaign ID
dimensionId integer	Dimension ID

Create a Basic Report

Create a Bid Model metrics report for the specified Campaign and Dimension IDs. The report can be filtered, sorted, and paginated.

Request Schema
startDate integer	Unix epoch timestamp of Campaign start date, in milliseconds
endDate integer	Unix epoch timestamp of Campaign end date, in milliseconds
timeZoneId integer	Timezone ID
pageNo integer	Page number for the data Default: 1
searchField string	Search results by keyword
sortBy string	Sorts by ascending (+) or descending (-) Default: -impressions
bundleIds array of integer	Bundle IDs

Request ExamplesSimple ReportSimple Report with SortingReport with SearchReport with Bundle IDsAdvanced Search

{
  "startDate": 1751001600000,
  "endDate": 1753593599000,
  "timeZoneId": 29,
  "pageNo": 1
}

{
  "startDate": 1751001600000,
  "endDate": 1753593599000,
  "timeZoneId": 29,
  "pageNo": 1,
  "sortBy": "+impressions"
}

{
  "startDate": 1751001600000,
  "endDate": 1753593599000,
  "timeZoneId": 29,
  "pageNo": 1,
  "sortBy": "+impressions",
  "searchField": ".com"
}

{
  "startDate": 1751001600000,
  "endDate": 1753593599000,
  "timeZoneId": 29,
  "pageNo": 1,
  "sortBy": "+impressions",
  "searchField": ".com",
  "bundleIds": [1,2]
}

{
  "startDate": 1750651200000,
  "endDate": 1752724799000,
  "timeZoneId": 29,
  "sortBy": "+impressions",
  "pageNo": 1,
  "searchKeywords": [
    "9171361",
    "keyword 1",
    "33126",
    "keyword N"
  ]
}

Response 200 ExamplesBasic ReportReport With Bundles

{
  "success": true,
  "data": {
    "recordsTotal": {
      "totalCount": 1,
      "impressions": 25712,
      "dataCost": 0,
      "winRate": 99.4276875483372,
      "clicks": 25651,
      "eCPM": 1.0000000000000002,
      "totalECPM": 1.0000000000000002,
      "eCPC": 0.0010023780749288528,
      "totalECPC": 0.0010023780749288528,
      "mediaSpent": 25.712000000000003,
      "CTR": 99.76275668948351,
      "spent": 25.712000000000003,
      "conversionCount": 0,
      "conversionValue": 0,
      "attributedClickThroughConversions": 0,
      "attributedViewThroughConversions": 0,
      "costPerAttributedConversions": 0,
      "attributedConversionsRate": 0,
      "returnOnAdSpend": 0,
      "VCR": 0,
      "eCPV": 0,
      "eCPCV": 0,
      "startCount": 0,
      "firstCount": 0,
      "midCount": 0,
      "thirdCount": 0,
      "completeCount": 0,
      "bidImpressions": 25860,
      "audioVideoViewed": 0,
      "prebidCost": 0
    },
    "recordsList": [
      {
        "id": 1001662598,
        "name": "b.fast-stories.com",
        "isExcluded": 0,
        "modelled": false,
        "inventoryTrafficType": "web",
        "inventoryType": "Site",
        "blocked": false,
        "targeted": false,
        "impressions": 25712,
        "dataCost": 0,
        "winRate": 99.4276875483372,
        "clicks": 25651,
        "eCPM": 1.0000000000000002,
        "totalECPM": 1.0000000000000002,
        "eCPC": 0.0010023780749288528,
        "totalECPC": 0.0010023780749288528,
        "mediaSpent": 25.712000000000003,
        "CTR": 99.76275668948351,
        "spent": 25.712000000000003,
        "conversionCount": 0,
        "conversionValue": 0,
        "attributedClickThroughConversions": 0,
        "attributedViewThroughConversions": 0,
        "costPerAttributedConversions": 0,
        "attributedConversionsRate": 0,
        "returnOnAdSpend": 0,
        "VCR": 0,
        "eCPV": 0,
        "eCPCV": 0,
        "startCount": 0,
        "firstCount": 0,
        "midCount": 0,
        "thirdCount": 0,
        "completeCount": 0,
        "bidImpressions": 25860,
        "audioVideoViewed": 0,
        "prebidCost": 0
      },
      {
        "id": 1001662599,
        "name": "b.fast-stories.com",
        "isExcluded": 0,
        "modelled": false,
        "inventoryTrafficType": "web",
        "inventoryType": "Site",
        "blocked": false,
        "targeted": false,
        "impressions": 25712,
        "dataCost": 0,
        "winRate": 99.4276875483372,
        "clicks": 25651,
        "eCPM": 1.0000000000000002,
        "totalECPM": 1.0000000000000002,
        "eCPC": 0.0010023780749288528,
        "totalECPC": 0.0010023780749288528,
        "mediaSpent": 25.712000000000003,
        "CTR": 99.76275668948351,
        "spent": 25.712000000000003,
        "conversionCount": 0,
        "conversionValue": 0,
        "attributedClickThroughConversions": 0,
        "attributedViewThroughConversions": 0,
        "costPerAttributedConversions": 0,
        "attributedConversionsRate": 0,
        "returnOnAdSpend": 0,
        "VCR": 0,
        "eCPV": 0,
        "eCPCV": 0,
        "startCount": 0,
        "firstCount": 0,
        "midCount": 0,
        "thirdCount": 0,
        "completeCount": 0,
        "bidImpressions": 25860,
        "audioVideoViewed": 0,
        "prebidCost": 0
      }
    ],
    "totalRecords": 2,
    "filteredRecords": 2
  }
}

{
  "success": true,
  "data": {
    "recordsTotal": {
      "totalCount": 1,
      "impressions": 25712,
      "dataCost": 0,
      "winRate": 99.4276875483372,
      "clicks": 25651,
      "eCPM": 1.0000000000000002,
      "totalECPM": 1.0000000000000002,
      "eCPC": 0.0010023780749288528,
      "totalECPC": 0.0010023780749288528,
      "mediaSpent": 25.712000000000003,
      "CTR": 99.76275668948351,
      "spent": 25.712000000000003,
      "conversionCount": 0,
      "conversionValue": 0,
      "attributedClickThroughConversions": 0,
      "attributedViewThroughConversions": 0,
      "costPerAttributedConversions": 0,
      "attributedConversionsRate": 0,
      "returnOnAdSpend": 0,
      "VCR": 0,
      "eCPV": 0,
      "eCPCV": 0,
      "startCount": 0,
      "firstCount": 0,
      "midCount": 0,
      "thirdCount": 0,
      "completeCount": 0,
      "bidImpressions": 25860,
      "audioVideoViewed": 0,
      "prebidCost": 0
    },
    "recordsList": [
      {
        "bundleId": 1,
        "bundleName": "bundle1",
        "bundleEntityIds": [
          1,
          2,
          3
        ],
        "impressions": 25712,
        "dataCost": 0,
        "winRate": 99.4276875483372,
        "clicks": 25651,
        "eCPM": 1.0000000000000002,
        "totalECPM": 1.0000000000000002,
        "eCPC": 0.0010023780749288528,
        "totalECPC": 0.0010023780749288528,
        "mediaSpent": 25.712000000000003,
        "CTR": 99.76275668948351,
        "spent": 25.712000000000003,
        "conversionCount": 0,
        "conversionValue": 0,
        "attributedClickThroughConversions": 0,
        "attributedViewThroughConversions": 0,
        "costPerAttributedConversions": 0,
        "attributedConversionsRate": 0,
        "returnOnAdSpend": 0,
        "VCR": 0,
        "eCPV": 0,
        "eCPCV": 0,
        "startCount": 0,
        "firstCount": 0,
        "midCount": 0,
        "thirdCount": 0,
        "completeCount": 0,
        "bidImpressions": 25860,
        "audioVideoViewed": 0,
        "prebidCost": 0,
        "entityRecordsList": [
          {
            "id": 1001662596,
            "name": "b.fast-stories.com",
            "isExcluded": 0,
            "modelled": false,
            "inventoryTrafficType": "web",
            "inventoryType": "Site",
            "blocked": false,
            "targeted": false,
            "impressions": 25712,
            "dataCost": 0,
            "winRate": 99.4276875483372,
            "clicks": 25651,
            "eCPM": 1.0000000000000002,
            "totalECPM": 1.0000000000000002,
            "eCPC": 0.0010023780749288528,
            "totalECPC": 0.0010023780749288528,
            "mediaSpent": 25.712000000000003,
            "CTR": 99.76275668948351,
            "spent": 25.712000000000003,
            "conversionCount": 0,
            "conversionValue": 0,
            "attributedClickThroughConversions": 0,
            "attributedViewThroughConversions": 0,
            "costPerAttributedConversions": 0,
            "attributedConversionsRate": 0,
            "returnOnAdSpend": 0,
            "VCR": 0,
            "eCPV": 0,
            "eCPCV": 0,
            "startCount": 0,
            "firstCount": 0,
            "midCount": 0,
            "thirdCount": 0,
            "completeCount": 0,
            "bidImpressions": 25860,
            "audioVideoViewed": 0,
            "prebidCost": 0
          },
          {
            "id": 1001662597,
            "name": "b.fast-stories.com",
            "isExcluded": 0,
            "modelled": false,
            "inventoryTrafficType": "web",
            "inventoryType": "Site",
            "blocked": false,
            "targeted": false,
            "impressions": 25712,
            "dataCost": 0,
            "winRate": 99.4276875483372,
            "clicks": 25651,
            "eCPM": 1.0000000000000002,
            "totalECPM": 1.0000000000000002,
            "eCPC": 0.0010023780749288528,
            "totalECPC": 0.0010023780749288528,
            "mediaSpent": 25.712000000000003,
            "CTR": 99.76275668948351,
            "spent": 25.712000000000003,
            "conversionCount": 0,
            "conversionValue": 0,
            "attributedClickThroughConversions": 0,
            "attributedViewThroughConversions": 0,
            "costPerAttributedConversions": 0,
            "attributedConversionsRate": 0,
            "returnOnAdSpend": 0,
            "VCR": 0,
            "eCPV": 0,
            "eCPCV": 0,
            "startCount": 0,
            "firstCount": 0,
            "midCount": 0,
            "thirdCount": 0,
            "completeCount": 0,
            "bidImpressions": 25860,
            "audioVideoViewed": 0,
            "prebidCost": 0
          }
        ]
      },
      {
        "id": 1001662598,
        "name": "b.fast-stories.com",
        "isExcluded": 0,
        "modelled": false,
        "inventoryTrafficType": "web",
        "inventoryType": "Site",
        "blocked": false,
        "targeted": false,
        "impressions": 25712,
        "dataCost": 0,
        "winRate": 99.4276875483372,
        "clicks": 25651,
        "eCPM": 1.0000000000000002,
        "totalECPM": 1.0000000000000002,
        "eCPC": 0.0010023780749288528,
        "totalECPC": 0.0010023780749288528,
        "mediaSpent": 25.712000000000003,
        "CTR": 99.76275668948351,
        "spent": 25.712000000000003,
        "conversionCount": 0,
        "conversionValue": 0,
        "attributedClickThroughConversions": 0,
        "attributedViewThroughConversions": 0,
        "costPerAttributedConversions": 0,
        "attributedConversionsRate": 0,
        "returnOnAdSpend": 0,
        "VCR": 0,
        "eCPV": 0,
        "eCPCV": 0,
        "startCount": 0,
        "firstCount": 0,
        "midCount": 0,
        "thirdCount": 0,
        "completeCount": 0,
        "bidImpressions": 25860,
        "audioVideoViewed": 0,
        "prebidCost": 0
      },
      {
        "id": 1001662599,
        "name": "b.fast-stories.com",
        "isExcluded": 0,
        "modelled": false,
        "inventoryTrafficType": "web",
        "inventoryType": "Site",
        "blocked": false,
        "targeted": false,
        "impressions": 25712,
        "dataCost": 0,
        "winRate": 99.4276875483372,
        "clicks": 25651,
        "eCPM": 1.0000000000000002,
        "totalECPM": 1.0000000000000002,
        "eCPC": 0.0010023780749288528,
        "totalECPC": 0.0010023780749288528,
        "mediaSpent": 25.712000000000003,
        "CTR": 99.76275668948351,
        "spent": 25.712000000000003,
        "conversionCount": 0,
        "conversionValue": 0,
        "attributedClickThroughConversions": 0,
        "attributedViewThroughConversions": 0,
        "costPerAttributedConversions": 0,
        "attributedConversionsRate": 0,
        "returnOnAdSpend": 0,
        "VCR": 0,
        "eCPV": 0,
        "eCPCV": 0,
        "startCount": 0,
        "firstCount": 0,
        "midCount": 0,
        "thirdCount": 0,
        "completeCount": 0,
        "bidImpressions": 25860,
        "audioVideoViewed": 0,
        "prebidCost": 0
      }
    ],
    "totalRecords": 4,
    "filteredRecords": 4
  }
}

Create a Report with Performance Filters

Create a Bid Model metrics report for the specified Campaign and Dimension IDs. The report can be filtered, sorted, and paginated. Additionally, you can specify performance filters to refine the report results.

Request Schema
startDate integer	Unix epoch timestamp of Campaign start date, in milliseconds
endDate integer	Unix epoch timestamp of Campaign end date, in milliseconds
timeZoneId integer	Timezone ID
pageNo integer	Page number for the data Default: 1
performanceFilters object	Object containing performance filter criteria
performanceFilters object properties operation string Set to AND or OR conditions object array Object containing conditions details conditions object properties column string Column name condition string Condition description value integer Condition value

Request ExamplesReport With Single Performance FilterReport With Multiple Performance Filters

{
  "startDate": 1749873600000,
  "endDate": 1752551999000,
  "timeZoneId": 29,
  "sortBy": "+impressions",
  "pageNo": 1,
  "performanceFilters": {
    "conditions": [
      {
        "column": "impressions",
        "condition": "<",
        "value": 1000
      }
    ]
  }
}

{
  "startDate": 1749873600000,
  "endDate": 1752551999000,
  "timeZoneId": 29,
  "sortBy": "+impressions",
  "pageNo": 1,
  "performanceFilters": {
    "operation": "AND",
    "conditions": [
      {
        "column": "impressions",
        "condition": "<",
        "value": 1000
      },
      {
        "column": "clicks",
        "condition": "!=",
        "value": 2000
      }
    ]
  }
}

Download a Report

Create a downloadable Bid Model metrics report for the specified Campaign and Dimension IDs. The report can be filtered, sorted, and paginated. The report will be generated in either CSV or XLSX format based on the request.

Request Schema
startDate integer	Unix epoch timestamp of Campaign start date, in milliseconds
endDate integer	Unix epoch timestamp of Campaign end date, in milliseconds
timeZoneId integer	Timezone ID
pageNo integer	Page number for the data Default: 1
sortBy string	Sorts by ascending (+) or descending (-) Default: -impressions
download object	Object containing download details
download object properties fileType string File type: csv or xlsx columns object Object containing label and value columns object properties label string Serves as the header row in the downloaded CSV/XLSX file, each label corresponds to a data field, displayed as the column header in the file value string Represents the data key used to retrieve values from the result map sourced from the database, ensures each column in the CSV/XLSX file accurately reflects the relevant data, with applied formatting and timezone adjustments as needed

Request Sample

{
  "startDate": 1751001600000,
  "endDate": 1753593599000,
  "timeZoneId": 29,
  "pageNo": 1,
  "sortBy": "-impressions",
  "download": {
    "fileType": "csv",
    "columns": [
      {
        "label": "ID",
        "value": "id"
      },
      {
        "label": "Inventory Name",
        "value": "name"
      },
      {
        "label": "Type",
        "value": "inventoryType"
      },
      {
        "label": "Modeling",
        "value": "modelled"
      },
      {
        "label": "Impressions",
        "value": "impressions"
      },
      {
        "label": "Clicks",
        "value": "clicks"
      },
      {
        "label": "Win Rate",
        "value": "winRate"
      },
      {
        "label": "CTR",
        "value": "CTR"
      },
      {
        "label": "Media eCPM",
        "value": "eCPM"
      },
      {
        "label": "Total eCPM",
        "value": "totalECPM"
      },
      {
        "label": "Media eCPC",
        "value": "eCPC"
      },
      {
        "label": "Total eCPC",
        "value": "totalECPC"
      },
      {
        "label": "Media Cost",
        "value": "mediaSpent"
      },
      {
        "label": "Data Cost",
        "value": "dataCost"
      },
      {
        "label": "Pre-bid Cost",
        "value": "prebidCost"
      },
      {
        "label": "Total Spent",
        "value": "spent"
      },
      {
        "label": "Total Attributed Conversion Value",
        "value": "conversionValue"
      },
      {
        "label": "Total Attributed Conversions",
        "value": "conversionCount"
      },
      {
        "label": "Return On Ad Spend",
        "value": "returnOnAdSpend"
      },
      {
        "label": "Attributed Click Through Conversions",
        "value": "attributedClickThroughConversions"
      },
      {
        "label": "Attributed View Through Conversions",
        "value": "attributedViewThroughConversions"
      },
      {
        "label": "Cost Per Attributed Conversions",
        "value": "costPerAttributedConversions"
      },
      {
        "label": "Attributed Conversions Rate",
        "value": "attributedConversionsRate"
      }
    ]
  }
}

Response 200

{
  "success": true,
  "data": {
    "url": "DownloadURL"
  }
}

---

Get List of Bid Model Dimensions

GET /api/v3/bm/static/dimensions

This API will provide values of Bid Model dimensions and sub-dimensions.

Dimensions
1	Creative
2	Inventory
3	Deal ID
4	Open Exchange
5	Publisher Category
6	Device
7	Traffic Type
8	Device Type
9	Location
10	State
11	City
12	Zip
13	Exchange

JSON

Response 200

{
  "success": true,
  "data": {
    "totalRecords": 5,
    "filteredRecords": 5,
    "dimensions": [
      {
        "name": "creative",
        "id": 1,
        "label": "Creative",
        "order": 1,
        "modellingEnabled": true
      },
      {
        "name": "inventory",
        "id": 2,
        "label": "Inventory",
        "order": 2,
        "modellingEnabled": false,
        "subdimensions": [
          {
            "name": "deal_id",
            "id": 3,
            "label": "Deal ID",
            "order": 1,
            "modellingEnabled": false
          },
          {
            "name": "open_exchange",
            "id": 4,
            "label": "Open Exchange",
            "order": 2,
            "modellingEnabled": false
          },
          {
            "name": "publisher_category",
            "id": 5,
            "label": "Publisher Category",
            "order": 3,
            "modellingEnabled": false
          }
        ]
      },
      {
        "name": "device",
        "id": 6,
        "label": "Device",
        "order": 3,
        "modellingEnabled": false,
        "subdimensions": [
          {
            "name": "traffic_type",
            "id": 7,
            "label": "Traffic Type",
            "order": 1,
            "modellingEnabled": false
          },
          {
            "name": "device_type",
            "id": 8,
            "label": "Device Type",
            "order": 2,
            "modellingEnabled": false
          }
        ]
      },
      {
        "name": "location",
        "id": 9,
        "label": "Location",
        "order": 4,
        "modellingEnabled": false,
        "subdimensions": [
          {
            "name": "state",
            "id": 10,
            "label": "State",
            "order": 1,
            "modellingEnabled": false
          },
          {
            "name": "city",
            "id": 11,
            "label": "City",
            "order": 2,
            "modellingEnabled": false
          },
          {
            "name": "zip",
            "id": 12,
            "label": "Zip",
            "order": 3,
            "modellingEnabled": false
          }
        ]
      },
      {
        "name": "exchange",
        "id": 13,
        "label": "Exchange",
        "order": 5,
        "modellingEnabled": false
      }
    ]
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          totalRecords: number;
          filteredRecords: number;
          dimensions: {
            name: string;
            id: number;
            label: string;
            order: number;
            modellingEnabled: boolean
            subdimensions?: {
              name: string;
              id: number;
              label: string;
              order: number;
              modellingEnabled: boolean
            }[]
          }[]
        }
      }
    };
  };
}

function getDimensions(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/bm/static/dimensions',
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---