Bid Model API

The Bid Model API allows you to optimize advertising campaigns for better performance.

You can fine-tune metrics such as where ads appear, 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 Model settings comprise 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**
• Device: Traffic Type, Device Type
• Exchange: Exchange ID
• Audience: Audience 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.

***Spend Ratios and Allowlist/Blocklist targeting are not supported for the audience dimension.

More resources

• Create a Bid Model tutorial
• Campaign delivery and optimization Help Center article

Authentication

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

Bid Model settings details

Get list of Bid Model Bundles

GET

Get a list of Bid Model Bundles for a given campaign ID and dimension.

A bundleId can be used in various Bid Model settings management endpoints to add, update, or delete Bid Model settings.

Path parameter
campaignId integer	Campaign ID.

Query parameter
dimensionId integer	Dimension ID.
searchField string	Filter results by search field.

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 Bid Model settings are 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

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 entity IDs with Bid Model settings applied.
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

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. Required only when attributes includes totalCount.
endDate integer	Unix epoch timestamp (in milliseconds) for the total count. Required only when attributes includes totalCount.
attributes string	List of statistics to return. Supported values: totalCount, modelledCount, modelledIds.
dimensionIds array of integers	List of dimension IDs to fetch statistics for. Allowed values: 1 (Creative), 10 (State), 11 (City), 12 (Zip), 3 (Deal), 4 (Open Exchange), 5 (Publisher Category), 13 (Exchange), 7 (Traffic Type), 8 (Device Type).

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 with Bid Model settings in a dimension.
modelledIds object	List of entity IDs with Bid Model settings applied.

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

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

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 settings management endpoints to update or delete Bid Model settings.

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 of retrieved data, default: 1.
searchField string	Filter results by search field.
noOfEntries integer	Number of entries returned 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 Model settings will be returned.

Response properties (creative)

recordsList array of objects	Modeled creative entities for the campaign. Entities that have been added to a Bundle are grouped under a parent entry, as described below.
recordsList entry properties id integer Creative ID. name string Creative name. isExcluded integer Whether the entity is excluded via Allowlist/Blocklist. modelled boolean Whether the entity has Bid Model settings applied. targeted boolean Whether the entity is targeted by the campaign. bundleId integer Bundle ID the entity belongs to, if any. creativeStatus string Creative status, e.g. Running, Deleted. creativeThumbnailSource string Creative thumbnail image URL. creativeCardSource string Creative card preview image URL. creativeType string Creative type, e.g. Video. creativeWidth integer Creative width, in pixels. creativeHeight integer Creative height, in pixels. creativeDuration integer Creative duration, in seconds. spentDistribution number Share of spend distributed to this entity. bidModelData object Bid Model settings applied to the entity, if modelled. bidModelData object properties id integer Bid Model data ID. priority integer Assigned priority: [ 1 .. 10 ]. bidMultiplier number Bid Modifier: [ 0.1 .. 100 ]. spendRatio number Spend Ratio: [ 0 .. 100 ]. spendRatioTypeId integer Spend Ratio type ID. Flexible: 1. Strict: 2. Entry properties when grouped in a Bundle bundleName string Bundle name. bundleEntityIds array of integers Creative IDs belonging to the Bundle. entityRecordsList array of objects The underlying creative entities in the Bundle, each with the same properties described above (except bidModelData and Bundle grouping, which only apply at the Bundle level).
campaignBidDetails object	Campaign-level bid and priority-shift details.
campaignBidDetails object properties baseBid number Campaign base bid. maxBid number Campaign max bid. minBid number Campaign min bid. currentPriority integer Campaign's current Bid Model priority, once serving has started. nextPerformanceCheck integer Unix epoch timestamp (in milliseconds) of the next scheduled priority-shift performance check, once serving has started. lastPerformanceCheck integer Unix epoch timestamp (in milliseconds) of the last priority-shift performance check, once serving has started.

Response properties (audience)

recordsList array of objects	Modeled audience entities for the campaign. Audiences that have been added to a Bundle are grouped under a parent entry, as described below.
recordsList entry properties id integer Audience ID. name string Audience name. isExcluded integer Whether the entity is excluded via Allowlist/Blocklist. modelled boolean Whether the entity has Bid Model settings applied. Only ever true for an ID-Based audience. targeted boolean Whether the entity is targeted by the campaign. bundleId integer Bundle ID the entity belongs to, if any. audienceStatus string Audience status, e.g. Ready, Processing. audienceType string Audience category, e.g. Matched Audience, Lookalike Audience. classType string ID-Based or Non-ID-Based. Only ID-Based audiences are eligible to be modelled. parentAudienceId integer Parent audience ID. Only ever populated for Integrated Care Team audiences, null otherwise. spentDistribution number Share of spend distributed to this entity. bidModelData object Bid Model settings applied to the entity, if modelled. bidModelData object properties id integer Bid Model data ID. priority integer Assigned priority: [ 1 .. 10 ]. bidMultiplier number Bid Modifier: [ 0.1 .. 100 ]. spendRatio number Spend Ratio: [ 0 .. 100 ]. spendRatioTypeId integer Spend Ratio type ID. Flexible: 1. Strict: 2. Entry properties when grouped in a Bundle bundleName string Bundle name. bundleEntityIds array of integers Audience IDs belonging to the Bundle. entityRecordsList array of objects The underlying audience entities in the Bundle, each with the same properties described above (except bidModelData and Bundle grouping, which only apply at the Bundle level).
campaignBidDetails object	Campaign-level bid and priority-shift details.
campaignBidDetails object properties baseBid number Campaign base bid. maxBid number Campaign max bid. minBid number Campaign min bid. currentPriority integer Campaign's current Bid Model priority, once serving has started. nextPerformanceCheck integer Unix epoch timestamp (in milliseconds) of the next scheduled priority-shift performance check, once serving has started. lastPerformanceCheck integer Unix epoch timestamp (in milliseconds) of the last priority-shift performance check, once serving has started.

JSON

Request sample

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

Response examplesModeled creatives listing (dimensionId = 1)Modeled audiences listing (dimensionId = 14)

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
    }
  }
}

Response 200

{
  "success": true,
  "data": {
    "recordsTotal": {
      "totalCount": 5,
      "impressions": 9534,
      "winRate": 99.40569283703472,
      "clicks": 8573,
      "eCPM": 82.57879955947136,
      "totalECPM": 90.06778634361234,
      "eCPC": 0.0918355622302578,
      "totalECPC": 0.10016403534352035,
      "dataCost": 14.301,
      "mediaSpent": 787.306275,
      "CTR": 89.92028529473464,
      "spent": 858.706275,
      "conversionCount": 0,
      "conversionValue": 0,
      "returnOnAdSpend": 0.0,
      "bidImpressions": 9591,
      "prebidCost": 0.0,
      "spentDistribution": 0.0
    },
    "recordsList": [
      {
        "bundleId": 1627,
        "bundleName": "sample bundle",
        "bundleEntityIds": [1176057, 1176058],
        "entityRecordsList": [
          {
            "id": 1176058,
            "name": "Plan Failure Check 1_HCP_pl_Filtered",
            "modelled": false,
            "bundleId": 1627,
            "audienceStatus": "Ready",
            "audienceType": "Matched Audience",
            "classType": "ID-Based",
            "parentAudienceId": null,
            "targeted": true,
            "impressions": 4540,
            "clicks": 4534,
            "winRate": 99.30008748906387,
            "CTR": 99.86784140969164,
            "mediaSpent": 407.531,
            "spent": 446.121
          },
          {
            "id": 1176057,
            "name": "Plan Failure Check 1_HCP_data360_Filtered",
            "modelled": false,
            "bundleId": 1627,
            "audienceStatus": "Processing",
            "audienceType": "Matched Audience",
            "classType": "ID-Based",
            "parentAudienceId": null,
            "targeted": true,
            "impressions": 451,
            "clicks": 450,
            "winRate": 99.77876106194691,
            "CTR": 99.77827050997783,
            "mediaSpent": 40.139,
            "spent": 43.9725
          }
        ],
        "modelled": true,
        "bidModelData": {
          "id": 30544,
          "priority": 3,
          "bidMultiplier": 1.0,
          "spendRatio": 0
        },
        "impressions": 4991,
        "clicks": 4984,
        "winRate": 99.34315286624204,
        "CTR": 99.85974754558205,
        "mediaSpent": 447.67,
        "spent": 490.0935
      },
      {
        "id": 1176047,
        "name": "Plan Failure Check_HCP_pl_Filtered",
        "modelled": false,
        "bundleId": 0,
        "audienceStatus": "Ready",
        "audienceType": "Matched Audience",
        "classType": "ID-Based",
        "parentAudienceId": null,
        "targeted": true,
        "impressions": 3166,
        "clicks": 3158,
        "winRate": 99.24764890282131,
        "CTR": 99.74731522425773,
        "mediaSpent": 282.329,
        "spent": 309.24,
        "bidModelData": {
          "id": 30543,
          "priority": 2,
          "bidMultiplier": 1.0,
          "spendRatio": 0
        }
      },
      {
        "id": -1,
        "name": "Others",
        "modelled": false,
        "bundleId": 0,
        "targeted": false,
        "impressions": 531,
        "clicks": 431,
        "winRate": 100.0,
        "CTR": 81.16760828625236,
        "mediaSpent": 22.1875875,
        "spent": 22.9840875,
        "bidModelData": {
          "id": 30545,
          "priority": 10,
          "bidMultiplier": 1.0,
          "spendRatio": 0
        }
      }
    ],
    "totalRecords": 5,
    "filteredRecords": 5,
    "campaignBidDetails": {
      "baseBid": null,
      "minBid": 1.0,
      "lastPerformanceCheck": null,
      "maxBid": 50.0,
      "currentPriority": null,
      "nextPerformanceCheck": null
    }
  }
}

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);
}

Include/exclude management

Include/exclude entities from a campaign

POST

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

Path parameters
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 Model settings management

Bid Model settings criteria

• Bid Modifier & 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'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**
• Device: Traffic Type, Device Type
• Exchange: Exchange ID
• Audience: Audience 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.

***Spend Ratios and Allowlist/Blocklist targeting are not supported for the audience dimension.

Manage Bid Model settings

PUT

Manage Bid Model settings for a given campaign and dimension. Supports operations for adding, updating, and deleting Bid Model settings 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 Model settings criteria before applying Bid Model settings to a campaign.

ADD: Create new Bid Model settings 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 Model settings to the existing Bundle.

UPDATE: Update existing Bid Model settings for a single entity or entity Bundles.

DELETE: Remove Bid Model settings or unbundle a Bundle.

INCLUDE/EXCLUDE Map: Defines which entity IDs are explicitly included or excluded in Bid Model settings.

Audience-specific rules:

• spendRatio and spendRatioTypeId are not supported.
• priority is required.
• bidMultiplier is required.
• Include/exclude map is not supported.
• Only ID-based audiences can be modelled. Providing a non-ID-based audience ID returns the error: "Bid modelling is not allowed for non-ID-based audiences. Please provide only ID-based audience IDs."

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 Modifier. [ 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 Model settings updateAdd Bid Model settings (initial setup)Add Bid Model settings for audiencesUpdate existing Bid Model settingsUpdate Bid Model settingsRemove Bid Model settingsDelete 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": {
    "ADD": {
      "bidModelEntityDetails": [
        {
          "entityId": 50,
          "entityTypeId": 1,
          "priority": 1,
          "bidMultiplier": 2
        },
        {
          "entityId": -1,
          "entityTypeId": 3,
          "priority": 1,
          "bidMultiplier": 2
        }
      ]
    }
  }
}

{
  "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

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 modeling attributes at the Bundle level with the Manage Bid Model settings 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

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

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 Model settings 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 Model settings

PUT

Add, update, or remove Bid Model settings at the insertion order (IO) level. Changes will be applied to all campaigns associated with the specified IO.

Path parameter
ioId integer	IO 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 Modifier. [ 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
DELETE
PATCH

Add, update, or delete Priorities at the IO level. Changes will be applied to all campaigns associated with the IO.

Assigning Priority to campaigns allows 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	IO 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

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 of retrieved data. Default: 1.
searchField string	Filter results by search field.
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 BundlesAudience Listing (dimensionId = 14)

{
  "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
  }
}

{
  "success": true,
  "data": {
    "recordsTotal": {
      "totalCount": 2,
      "impressions": 1000,
      "dataCost": 2.5,
      "winRate": 20.0,
      "clicks": 25,
      "eCPM": 12.0,
      "totalECPM": 15.0,
      "eCPC": 0.48,
      "totalECPC": 0.6,
      "mediaSpent": 12.0,
      "CTR": 2.5,
      "spent": 15.0,
      "conversionCount": 2,
      "conversionValue": 50,
      "attributedClickThroughConversions": 1,
      "attributedViewThroughConversions": 1,
      "costPerAttributedConversions": 7.5,
      "attributedConversionsRate": 8.0,
      "returnOnAdSpend": 333.33,
      "prebidCost": 1.0
    },
    "recordsList": [
      {
        "id": 54321,
        "name": "Political Voters - Segment A",
        "audienceStatus": "Active",
        "audienceType": "Matched Audience",
        "classType": "ID-Based",
        "parentAudienceId": null,
        "modelled": true,
        "targeted": true,
        "impressions": 1000,
        "clicks": 25,
        "winRate": 20.0,
        "CTR": 2.5,
        "eCPM": 12.0,
        "totalECPM": 15.0,
        "eCPC": 0.48,
        "totalECPC": 0.6,
        "mediaSpent": 12.0,
        "dataCost": 2.5,
        "prebidCost": 1.0,
        "spent": 15.0,
        "spentDistribution": 4.2,
        "conversionCount": 2,
        "conversionValue": 50,
        "attributedClickThroughConversions": 1,
        "attributedViewThroughConversions": 1,
        "costPerAttributedConversions": 7.5,
        "attributedConversionsRate": 8.0,
        "returnOnAdSpend": 333.33,
        "bidModelData": {
          "id": 19322,
          "priority": 3,
          "bidMultiplier": 1.5,
          "spendRatio": 100,
          "spendRatioTypeId": 1
        }
      },
      {
        "id": 65432,
        "name": "Lookalike - Household Income",
        "audienceStatus": "Active",
        "audienceType": "Lookalike Audience",
        "classType": "Non-ID-Based",
        "parentAudienceId": null,
        "modelled": false,
        "targeted": true,
        "impressions": 0,
        "clicks": 0,
        "winRate": 0.0,
        "CTR": 0.0,
        "eCPM": 0.0,
        "totalECPM": 0.0,
        "eCPC": 0.0,
        "totalECPC": 0.0,
        "mediaSpent": 0.0,
        "dataCost": 0.0,
        "prebidCost": 0.0,
        "spent": 0.0,
        "spentDistribution": 0.0,
        "conversionCount": 0,
        "conversionValue": 0,
        "attributedClickThroughConversions": 0,
        "attributedViewThroughConversions": 0,
        "costPerAttributedConversions": 0.0,
        "attributedConversionsRate": 0.0,
        "returnOnAdSpend": 0.0
      }
    ],
    "totalRecords": 2,
    "filteredRecords": 2
  }
}

Note the second record: a Non-ID-Based audience can appear in the listing for visibility, but has no bidModelData since it isn't eligible to be modelled.

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 of retrieved 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 of retrieved 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 examplesInventory Listing Download file CSVAudience Listing Download file CSV

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"
  }
}

Request sample

{
  "startDate": 1751001600000,
  "endDate": 1753593599000,
  "timeZoneId": 29,
  "pageNo": 1,
  "sortBy": "-impressions",
  "download": {
    "fileType": "csv",
    "columns": [
      {
        "label": "Audience Name",
        "value": "name"
      },
      {
        "label": "Audience Type",
        "value": "audienceType"
      },
      {
        "label": "Class Type",
        "value": "classType"
      },
      {
        "label": "Parent Audience ID",
        "value": "parentAudienceId"
      },
      {
        "label": "Status",
        "value": "audienceStatus"
      },
      {
        "label": "Modeling",
        "value": "modelled"
      },
      {
        "label": "Spend Distribution %",
        "value": "spentDistribution"
      }
    ]
  }
}

Response 200

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

---

Get list of Bid Model dimensions

GET

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.
14	Audience.

JSON

Response 200

{
  "success": true,
  "data": {
    "totalRecords": 6,
    "filteredRecords": 6,
    "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
      },
      {
        "name": "audience",
        "id": 14,
        "label": "Audience",
        "order": 6,
        "modellingEnabled": true
      }
    ]
  }
}

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);
}

---