Skip to main content

Create a Bid Model

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

The following endpoints will be used to check a Campaign's eligibility and create a Bid Model:

POST /api/v3/ua/login
GET /api/v2/cmp/campaign/{campaignId}
GET /api/v3/cmp/io/advanced/list
GET /api/v3/bm/static/dimensions
POST /api/v3/bm/campaigns/{campaignId}/bid-models

About IQM Bid Modeling​

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.

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

Before You Begin​

To create a Bid Model the following are required:

  1. An Account On the IQM Platform
    • See Getting Started section to create an account and request a Client ID and Client Secret
  2. A Campaign 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 Quickstart Guide will cover 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. Log In
    • Optional if you have already logged in and have a token
  2. Check Campaign for Eligibility
    • 2.1: Check Insertion Order for Campaign eligibility
  3. Select a Dimension
  4. Create a Bid Model

Step 1: Log in​

POST /api/v3/ua/login

To log in, the Authentication: Basic header is required. The Login API returns an OAuth-compliant response with an Organization Workspace ID (owId), a unique identifier for each Organization. This ID will be used for any further API communications.

For further information see the complete Login API Documentation.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-HOST
string required		Workspace URL
Request Schema
grantType
string required		OAuth Grant Types
email
string required		User account email
password
string required		User account password
Request Schema
{
  "grantType": "password",
  "email": "pratik.t+ihp@iqm.com",
  "password": "123456"
}
Response 200
{
  "success": true,
  "data":
  {
    "access_token": "106adb25-37b0-4cab-8381-d682fe7cc3c8",
    "refresh_token": "eac4c1f6-781e-4b04-baff-9c2e415d1f64",
    "scope": "read write",
    "token_type": "bearer",
    "expires_in": 35999,
    "owId": 200001
  }
}
More Responses
Response 400
{
   "success": false,
   "data":
   {
      "status": "On Hold",
      "reason": "The particular account is kept on hold due to missed payment dates for last 3 months.",
      "supportEmail": "support@iqm.com"
   },
   "errorObjects":
   [
      {
         "error": "User is not allowed to access provided customer",
         "reason": "User is not associated with any active organization."
      }
   ]
}
Response 403
{
   "success": false,
   "errorObjects":
   [
      {
         "error": "User doesn't exist or user is not allowed to provided workspace."
      }
   ]
}

Step 2: Check Campaign for Eligibility​

GET /api/v2/cmp/campaign/{campaignId}

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

The endpoint will return 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.
Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
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 2.1 Check Insertion Order for Max Bid and Base Bid​

GET /api/v3/cmp/io/advanced/list

Pass the ioId returned from Step 2 in the searchField query parameter. Then check the Insertion Order's advanced details to confirm that baseBid and maxBid are defined for the Campaign's eligibility.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Query Paramters
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 3: Select Dimension​

GET /api/v3/bm/static/dimensions

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

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Dimensions
1Creative
2Inventory
3Deal ID
4Open Exchange
5Publisher Category
6Device
7Traffic Type
8Device Type
9Location
10State
11City
12Zip
13Exchange
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
      }
    ]
  }
}

Step 4: Create a Bid Model​

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

Once you have determined your Campaign is eligible, you can pass the campaignId to create Bid Modeling for it. Review the Bid Model tools descriptions in the About section and the Request Schema table below to create a Bid Model and apply it to your desired dimension(s).

info

Bid Modeling criteria:

  • 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**

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

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Path Parameters
campaignId
integer		Campaign ID
Request Schema
bidModelling
object		Object containing Bid Modeling properties
bidModelling object 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
dimensionEntityMappings
object		Object containing entity mappings
dimensionEntityMappings object properties
dimensionId
integer		Dimension ID
entityId
integer		Entity ID of chosen dimension
(For example: if chosen dimension is Creative, then pass the Creative ID here)
Response Properties
data
string		Success message
Request Sample
{
  "bidModelling": [
    {
      "bidModelData": {
        "id": 1,
        "priority": 1,
        "spendRatio": 100,
        "spendRatioTypeId": 1,
        "bidMultiplier": 1
      },
      "dimensionEntityMappings": [
        {
          "dimensionId": 1,
          "entityId": 583002
        }
      ]
    }
  ]
}
Response 200
{
  "success": true,
  "data": "Priority Updated Successfully"
}