Skip to main content

Create a Campaign

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

The following endpoints will be used to create an Insertion Order and start a Campaign:

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

About IQM Campaigns​

IQM's Campaigns define the individual marketing strategies of your ads. By specifying the supported parameters you can use the API to create a new Campaign.

Learn more by reading the Campaigns Overview Help Center Article.

Before You Begin​

To create a 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

Create a Campaign Using the IQM API​

This Quickstart Guide will cover how to create an Insertion Order and a new Campaign.

The minimum requirements to perform this task are: logging in with authentication credentials, creating an Insertion Order, and starting a new 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 Insertion Order
    • Optional if already created
  3. Create a Campaign
  4. 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 Insertion Order​

POST /api/v3/cmp/io/add

Before a Campaign can be started an Insertion Order must be created. An Insertion Order is a contractual agreement that outlines the terms and conditions for one or more advertising Campaigns. Once created, a Campaign can be created and assigned to an Insertion Order. Read more about Insertion Orders.

The minimum required values for IO creation are as listed below. See a complete table of Resource Properties for all supported values.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Request Schema
ioName
string		Insertion Order name
ioStartTime
integer		Unix epoch timestamp (in milliseconds) of IO start time
ioEndTime
integer		Unix epoch timestamp (in milliseconds) of IO end time
ioTotalBudget
integer		IO budget
ioStatusID
integer		Status ID
ioTimeZoneId
integer		Timezone ID for Insertion Order
isAutoSumIoTotalBudget
boolean		If true Keeps IO budget same as total budget of all included campaigns
ioBudgetTypeId
integer		IO Budget Type ID
ioBudgetDistributionMethodId
integer		Budget Distribution Method ID
Request Sample (budget based IO)
{
    "ioName": "IO Name 1",
    "ioStartTime": 1690898148000,
    "ioEndTime": 1690898888000,
    "ioTotalBudget": 1000,
    "ioTimeZoneId": 29,
    "isAutoSumIoTotalBudget": true,
    "ioBudgetTypeId": 1,
    "ioBudgetDistributionMethodId": 1
}
Response 200
{
    "success": true,
    "data": {
        "ioId": 123456,
        "ioName": "IO Name 1",
        "ioStartTime": 1690898148000,
        "ioEndTime": 1690898888000,
        "ioTotalBudget": 0,
        "ioTimeZoneId": 29,
        "ioBudgetTypeId": 1,
        "ioBudgetDistributionMethodId": 1,
        "isAutoSumIoTotalBudget": true,
        "ioTotalImpressions": null
    }
}

Step 3: Create a Campaign​

POST /api/v2/cmp/campaigns/add

Create a new Campaign in pending status.

Select campaignType: 1 for an "advanced" Campaign.

Use the ioId in the response from the Insertion Order you created in Step 2.

The minimum required values for creating a Campaign are as listed below. See the Create New Campaign documentation for the complete request schema.

info

Make sure that the budgetTypeId of your 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
campaignName
string		Campaign name
isAgreementChecked
boolean		Check to proceed: true
ioId
string		Insertion Order ID that Campaign belongs to
countryId
string		Country ID
advertiserDomain
string		Advertiser domain
creativeType
integer		Creative Type ID
campaignType
integer		Campaign Type ID
startTime
integer		Campaign start time
endTime
integer		Campaign end time (required if total budget pacing is enabled)
totalBudgetPacing
boolean		Budget is spent equally every hour: true
budgetDay
integer		Daily budget for Campaign serving daily (not applicable if budget pacing is set to true)
budgetTotal
integer		Total budget for Campaign serving period
budgetTypeId
integer		Budget Type ID
maxBid
integer		Max bid for each bid request
timezone
integer		Timezone ID for Campaign
creativeIds
string		Comma separated Creative IDs
exchanges
string 		Comma separated Exchanges IDs for targeting (leave string empty to select all)
publisherAdCategory
string 		Comma separated Publisher Ad Category IDs for targeting (leave string empty to select all)

Response Properties
data
integer		Campaign ID
message
string		Success message
status
string		Campaign status
Request Sample
{
  "campaignName": "NewTest",
  "maxBid": 100,
  "budgetTotal": 1500,
  "startTime": 1748890201,
  "endTime": 1749096000,
  "timezone": 29,
  "budgetDay": 50,
  "creativeType": 11,
  "isAgreementChecked":true,
  "ioId": 17994,
  "countryId": "30100001",
  "creativeIds": "676384",
  "advertiserDomain": "https://iqm.com",
  "totalBudgetPacing": false,
  "publisherAdCategory":"",
  "exchanges": "",
  "budgetTypeId": 1,
  "campaignType": 1
}
Response 200
{
  "statusCode": 201,
  "responseObject": {
    "data": 123456,
    "message": "Campaign saved successfully.",
    "status": "pending"
  }
}

Step 4: Check Campaign Status​

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

To run a Campaign, it must be approved. Use the Campaign ID returned in the data field in Step 3 to check the created Campaign's status and other details.

Path Parameters
campaignId
integer		Campaign 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": 0,
        "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
    }
}