Skip to main content

Create a PG Campaign

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

The following endpoints will be used to create a PG Campaign:

POST /api/v3/ua/login
POST /api/v3/cmp/pg/campaigns/add
GET /api/v2/cmp/campaign/{campaignId}

About IQM PG Campaigns​

IQM's Programmatic Guaranteed (PG) Campaigns define the individual marketing strategies of your ads with an inventory purchased directly from a specific publisher. By specifying the supported parameters you can use the API to create a new PG Campaign.

See How Do I Set Up a Programmatic Guaranteed (PG) Campaign for more information.

Before You Begin​

To create a PG Campaign, 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. An Approved and Running Creative
    • See Upload a Creative Quickstart Guide to upload a Creative
  3. An Insertion Order
  4. A Conversion
  5. A PG Deal

Create a PG Campaign Using the IQM API​

This Quickstart Guide will cover how to create a Campaign and upload a Creative.

The minimum requirements to perform this task are: logging in with authentication credentials, uploading a Creative, and creating a Campaign. 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. Create a PG Campaign
    • 2.1 Create a PG Campaign, provide necessary targeting parameters
    • 2.2 Check Campaign's status

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: Create a PG Campaign​

Step 2.1 Create Campaign​

POST /api/v3/cmp/pg/campaigns/add

Once you are logged in and have met the prerequisite conditions (see Before You Begin), you can create a PG Campaign. You will need a Creative, an Insertion Order, a Conversion, and a PG Deal to create a PG Campaign. Review the Request Schema table below for all the other parameters required for this endpoint.

info

Make sure that the budgetTypeId of your PG Campaign matches the ioBudgetTypeId of your Insertion Order.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Request Schema
pgCampaignInfo
object		Object containing Campaign information
pgCampaignInfo object properties
campaignName
string		Name of Campaign
ioId
integer		Insertion Order ID
timeZoneId
integer		Timezone ID
totalImpressions
integer optional		Targeted impressions for impression-based Campaign as budget, use if not a dollars-based Campaign
budgetTotal
integer optional		Total budget of the Campaign for dollars-based Campaign, use if not an impressions-based Campaign
maxBid
integer		Maximum allowed bid price for Campaign
startTime
integer		Unix epoch start time of Campaign, in milliseconds
endTime
integer		Unix epoch end time of Campaign, in milliseconds
budgetTypeId
integer		Budget Type ID of given Campaign (impression-based or dollar-based)
campaignTypeId
integer		Campaign Type ID
2: PG Campaign
advertiserDomain
string		Domain of the Advertiser user
creativeTargeting
object		Object containing Creative targeting details
creativeTargeting object properties
creativeTypeId
integer		Creative Type ID
creativeIds
array of integers		IDs of Creatives attached to this Campaign
inventoryTargeting
object		Object containing Inventory targeting details
inventoryTargeting object properties
pgDealIds
array of integers		PG Deal IDs attached to this Campaign
conversionTargeting
object		Object containing Campaign Conversion targeting details
conversionTargeting object properties
conversionTypeId
integer		Conversion type ID attached to this Campaign
conversionIds
array of integers		IDs of Conversions attached to this Campaign
politicalAdvertiserClientId
integer		Advertiser client ID if user is political Advertiser
countryId
integer		ID of targeted country
Request Sample
{
  "pgCampaignInfo": {
    "campaignName": "test imps PG campaign",
    "ioId": 95179,
    "timeZoneId": 29,
    "totalImpressions": 12345,
    "maxBid": 8,
    "startTime": 1715662337,
    "endTime": 1717128000,
    "budgetTypeId": 2,
    "campaignTypeId": 2,
    "advertiserDomain": "https://www.xyz.com"
  },
  "creativeTargeting": {
    "creativeTypeId": 11,
    "creativeIds": [
      644506
    ]
  },
  "inventoryTargeting": {
    "pgDealIds": [
      30,
      12
    ]
  },
  "conversionTargeting": {
    "conversionTypeId": 1,
    "conversionIds": [
      465,
      687,
      987
    ]
  },
  "politicalAdvertiserClientId": 989898,
  "countryId": 23
}
Response 200
{
  "success": true,
  "data": {
    "message": "PG Campaign Created successfully",
    "campaignId": 2
  }
}
More Responses
Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Invalid campaign Type provided"
    }
  ]
}

Step 2.2: Check Campaign Status​

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

To run a Campaign, it must be approved. Use the campaignId returned from the last step to check the created Campaign's status.

Path Parameter
campaignId
string required		Campaign ID
Headers
Authentication
string required		Authentication Bearer Token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Response 200
{
  "statusCode": 200,
  "responseObject": {
    "owId": 1,
    "parentOrganizationName": "IQM Corporation",
    "id": 25859,
    "uowId": 9216,
    "campaignName": "Test Campaign",
    "advertiserDomain": "https://iqm.com",
    "creativeType": 11,
    "campaignType": 1,
    "totalBudgetPacing": false,
    "isTvAd": false,
    "budgetDay": 10.0,
    "budgetTotal": 100.0,
    "maxBid": 10.0,
    "timezone": 433,
    "startTime": 1703794800,
    "endTime": 1704614400,
    "status": "running",
    "dspMargin": 0,
    "platformMargin": 0,
    "userDealMargin": 0,
    "spentScale": false,
    "creativeIds": "148971",
    "conversionType": "None",
    "bidOptimization": true,
    "bidPacing": true,
    "impressionCapping": 0,
    "maxDayImpressions": 0,
    "maxDayClicks": 0,
    "maxDayConversions": 0,
    "totalImpressions": 0,
    "totalClicks": 0,
    "totalConversions": 0,
    "deviceType": "13,15,11,12",
    "trafficType": "11,12",
    "exchanges": "55,61,58,41,39,47,59,1,54,56,45,16,11,37,57,50,46,53,60",
    "isLocationWithOrFilter": true,
    "countryId": "30100001",
    "locationDetails": {},
    "isCampaignFromNewPlatform": true,
    "organizationName": "IQM Corporation 1",
    "userEmail": "domo@iqm.com",
    "userName": "Domo Integration",
    "conversionTypeId": 0,
    "isUnapprovedAudienceTargeted": false,
    "isAllAudienceUnapproved": false,
    "createDate": 1703794110,
    "ioId": 2695,
    "ioName": "Sanity test Io",
    "prebidAudienceSegmentIdList": [],
    "budgetTypeId": 1,
    "isAdvanceAudioVideoTargeted": false,
    "isEstimatorAvailable": true,
    "isEditAccess": true,
    "isApprovalAccess": false,
    "isMarginSet": true,
    "isParentInvoiceTemplateSet": true
  }
}