Skip to main content

Create a Bid Model

Create a Bid Model with this in-depth tutorial using IQM's API.

The following endpoints are used to check a campaign's eligibility and create a Bid Model:

POST
GET
GET
GET
PUT

About IQM Bid Model​

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.

The Bid Model 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 underspends if unable to meet that ratio.
    2. Flexible: budget reallocates 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.

More resources​

Before you begin​

To create a Bid Model the following are required:

  1. An account on the IQM platform
  2. A campaign that meets the following criteria:
    • Duration of at least 3 days
    • Daily budget of at least $100
    • Base bid and max bid price must be defined

Create a Bid Model using the IQM API​

This tutorial covers how to create a Bid Model.

The minimum requirements to perform this task are: logging in with authentication credentials, checking a campaign's eligibility, and creating a Bid Model. Once these steps are accomplished, more can be learned about IQM's API through the guidelines pages.

  1. Check campaign for eligibility
    • 1.1: Check insertion order (IO) for campaign eligibility
  2. Select a dimension
  3. Create a Bid Model

Authentication​

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

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

Bid Model criteria​

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.

Step 1: Check campaign for eligibility​

GET

Before creating a Bid Model, check that you have an eligible campaign by using the campaignId and the Get campaign details endpoint.

The endpoint returns a JSON schema of campaign details (the relevant parameters are highlighted in the sample Response 200 code block):

  • startTime and endTime indicate the campaign's duration.
  • The daily budget is shown by the budgetDay parameter.
Path parameters
campaignId
integer		Campaign's unique ID
Response 200
{
    "statusCode": 200,
    "responseObject": {
        "owId": 203578,
        "parentOrganizationName": "Signup testing 1",
        "id": 537599,
        "uowId": 188494,
        "campaignName": "TestCampaign",
        "advertiserDomain": "https://iqm.com",
        "creativeType": 11,
        "campaignType": 1,
        "totalBudgetPacing": true,
        "isTvAd": false,
        "budgetDay": 1199.08,
        "budgetTotal": 50000.0,
        "maxBid": 15.0,
        "timezone": 29,
        "startTime": 1726518001,
        "endTime": 1727668800,
        "status": "running",
        "dspMargin": 0,
        "platformMargin": 0,
        "userDealMargin": 0,
        "spentScale": false,
        "creativeIds": "676384",
        "conversionType": "None",
        "bidOptimization": true,
        "bidPacing": true,
        "isBidShading": false,
        "impressionCapping": 0,
        "maxDayImpressions": 0,
        "maxDayClicks": 0,
        "maxDayConversions": 0,
        "totalImpressions": 5,
        "totalClicks": 0,
        "totalConversions": 0,
        "deviceType": "13,15,11,12",
        "trafficType": "11,12",
        "exchanges": "",
        "isLocationWithOrFilter": true,
        "countryId": "30100001",
        "locationDetails": {},
        "isCampaignFromNewPlatform": true,
        "organizationName": "User's Org",
        "userEmail": "User@iqm.com",
        "userName": "User",
        "conversionTypeId": 0,
        "isUnapprovedAudienceTargeted": false,
        "isAllAudienceUnapproved": false,
        "createDate": 1726517360,
        "ioId": 15844,
        "ioName": "Test2",
        "prebidAudienceSegmentIdList": [],
        "campaignTypeId": 1,
        "budgetTypeId": 1,
        "isAdvanceAudioVideoTargeted": false,
        "isEstimatorAvailable": true,
        "isEditAccess": true,
        "isMarginSet": false,
        "isApprovalAccess": false,
        "isParentInvoiceTemplateSet": true
    }
}

Step 1.1: Check insertion order for max bid and base bid​

GET

Pass the ioId returned from Step 1 in the searchField query parameter. Then check the IO's advanced details to confirm that baseBid and maxBid are defined for the campaign's eligibility.

Query parameters
searchField
string		Search returned results for specified ioId
Response 200
{
    "success": true,
    "data": {
        "totalRecords": 2,
        "filteredRecords": 2,
        "recordsTotal": {
          ...
        },
        "recordsList": [
            {
                "prebidCost": 0.0,
                "clicks": 0,
                "totalCount": 0,
                "winRate": 0.0,
                "logoURL": null,
                "avatarURL": null,
                "budgetDay": 0.0,
                "budgetSpent": 0.0,
                "budgetTotal": 0.0,
                "dataCost": 0.0,
                "mediaBudget": 0.0,
                "owId": 203578,
                "orgId": 0,
                "impressions": 0,
                "industry": 0,
                "mediaSpent": 0.0,
                "spent": 0.0,
                "organizationBidShadingSaving": null,
                "workspaceSpent": 0.0,
                "platformSpent": 0.0,
                "customerSpent": 0.0,
                "platformMediaEarning": 0.0,
                "platformBidShadingEarning": 0.0,
                "platformTotalEarning": 0.0,
                "workspaceMediaEarning": 0.0,
                "workspaceBidShadingEarning": 0.0,
                "workspaceTotalEarning": 0.0,
                "organizationName": "Conor's Org",
                "companySize": 0,
                "workspaceName": null,
                "workspaceId": 0,
                "workspaceDomain": null,
                "workspaceOrganizationName": null,
                "bidImpressions": 0,
                "startCount": 0,
                "firstCount": 0,
                "midCount": 0,
                "thirdCount": 0,
                "completeCount": 0,
                "audioVideoActualBids": 0,
                "audioVideoActualImpressions": 0,
                "eCPC": 0.0,
                "eCPM": 0.0,
                "eCPI": 0.0,
                "eCPCV": 0.0,
                "eCPV": 0.0,
                "totalAttributedConversion": null,
                "totalAttributedViewThroughConversion": null,
                "totalAttributedClickThroughConversion": null,
                "costPerAttributedConversion": null,
                "totalAttributedConversionRate": null,
                "reach": 0,
                "frequency": 0.0,
                "date": null,
                "campaignId": 0,
                "campaignName": null,
                "maxBid": 40.0,
                "startTime": 0,
                "endTime": 0,
                "campaignType": null,
                "status": null,
                "mappingDataCost": 0.0,
                "mappingSpent": 0.0,
                "campaignTimezone": null,
                "creativeType": null,
                "budgetPacing": false,
                "isCampaignFromNewPlatform": false,
                "percentageOfTotalSpent": 0.0,
                "uowId": 0,
                "audioVideoViewed": 0.0,
                "ioId": 15844,
                "ioName": "Test2",
                "ioTimezone": 29,
                "ioBudgetDistributionMethod": 1,
                "ioStartTime": 1726517280000,
                "ioEndTime": 0,
                "ioTotalBudget": 50000.0,
                "isAutoSumIoTotalBudget": true,
                "ioBudgetTypeId": 1,
                "ioTotalImpressions": null,
                "ioStatusId": 1,
                "exchangeId": 0,
                "exchangeName": null,
                "budgetTypeId": 1,
                "targetImpression": null,
                "dailyImpression": null,
                "creativesCount": null,
                "campaignsCount": 1,
                "pacingPercentage": null,
                "actualSpent": null,
                "expectedSpent": null,
                "campaignDuration": null,
                "remainingDuration": null,
                "dailyPacingPercentage": null,
                "expectedDailySpent": null,
                "actualDailySpent": null,
                "ioPacingPercentage": 0.0,
                "ioActualSpent": 0.0,
                "ioExpectedSpent": 0.0,
                "ioDuration": null,
                "ioRemainingDuration": 0,
                "budgetTotalCombined": null,
                "budgetDayCombined": null,
                "ioTotalBudgetCombined": 50000.0,
                "campaignPriority": null,
                "bidModelDataId": null,
                "baseBid": 20.0,
                "campaignTypeId": null,
                "workspaceVLDInsightsEarnings": null,
                "platformVLDInsightsEarnings": null,
                "isEligibleForVLDInsightsReport": null,
                "vldInsightsCost": null,
                "ioTimeZoneName": "US/Eastern",
                "CTR": 0.0,
                "VCR": 0.0,
                "CVR": 0.0
            }
        ]
    }
}

Step 2: Select dimension​

GET

This API provides values of Bid Model dimensions and sub-dimensions. Select the desired dimension id to apply the Bid Model to.

Dimensions
1Creative
2Inventory
3Deal ID
4Open Exchange
5Publisher Category
6Device
7Traffic Type
8Device Type
9Location
10State
11City
12Zip
13Exchange
14Audience
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
      }
    ]
  }
}

Step 3: Create a Bid Model​

PUT

Once you have determined your campaign is eligible, you can pass the campaignId and your selected dimensionId to create a Bid Model. Review the Bid Model tools descriptions in the About section, the Bid Model criteria, and the Request schema table below to create a Bid Model.

See the Manage Bid Model settings endpoint for full documentation.

info

Spend Ratio:

  • Strict Spend Ratios must equal 100% across all allocated dimensions.
  • Flexible Spend Ratios require a dimension priority.
tip

Group multiple dimension entities into a bundle to apply the same Bid Modifier and Spend Ratio to all entities in the bundle.

See the Create Bid Model bundle endpoint for more information on how to create a bundle, then use the bundleName and entityIds in your requests.

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 operation
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
Response properties
data
string		Success message
Request Sample
{
  "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
          ]
        }
      ]
    }
  }
}
Response 200
{
  "success": true,
  "data": "Bid Model updated successfully"
}
Have a question?
Ask the community
Was this page helpful?