Skip to main content

Create a campaign

Create your first campaign using IQM's API in this step-by-step quickstart guide.

The following endpoints are used to create an insertion order (IO) and start a campaign:

POST
POST
POST
GET

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.

More resources​

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

Create a campaign using the IQM API​

This quickstart guide covers 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 IO, 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 an insertion order
    • Optional if already created
  3. Create a campaign
  4. Check campaign status

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

Step 1: Log in​

POST

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 is used for any further API communications.

For further information see OAuth token.

Headers
Authentication
string required		Client ID and Client Secret
Content-Type
string required		application/x-www-form-urlencoded
Request schema
grant_type
string required		password for login
OAuth Grant Types
username
string required		User account email
password
string required		User account password
Request sample
curl -i --location 'https://api.iqm.com/api/v3/ua/oauth/token' \
--header 'accept: application/json, text/plain, */*' \
--header 'Authorization: Basic <Client ID/Client Secret>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=user@iqm.com' \
--data-urlencode 'password=<your password>'
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 an insertion order​

POST

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

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

Read more: Insertion orders (IO) overview

Request schema
ioName
string		IO 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
Supported values
1Active
2Expired
3Deleted
ioTimeZoneId
integer		Timezone ID for IO
isAutoSumIoTotalBudget
boolean		If true Keeps IO budget same as total budget of all included campaigns
ioBudgetTypeId
integer		IO budget type ID
Supported values
1Budget
2Impression
ioBudgetDistributionMethodId
integer		Budget distribution method ID
Supported values
1Manual
2Auto
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

Create a new campaign in pending status.

Select campaignType: 1 for an "Advanced" campaign.

Use the ioId in the response from the IO 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 IO.

Request schema
campaignName
string		campaign name
isAgreementChecked
boolean		Check to proceed: true
ioId
string		IO ID that campaign belongs to
countryId
string		Country ID
advertiserDomain
string		Advertiser domain
creativeType
integer		Creative type ID
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
campaignType
integer		Campaign type ID
Supported values
1Advanced campaign
2PG campaign
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
Supported values
1Budget
2Impression
maxBid
integer		Max bid for each bid request
timezone
integer		Timezone ID for campaign
creativeIds
string		Comma-separated creative IDs
exchanges
string 		Comma-separated exchange 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

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
    }
}
Have a question?
Ask the community
Was this page helpful?