Skip to main content

Create an Insights Report

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

The following endpoints will be used to check Campaigns for eligibility and create different types of Insights Reports:

POST /api/v3/ua/login
GET /api/v2/cmp/campaign/{campaignId}
GET /api/v3/ins/campaign/bid-insights/{campaignId}
POST /api/v3/ins/insights/add
POST /api/v3/ins/insights/download
POST /api/v3/cmp/audience/targeting
POST /api/v3/ins/vld-report
POST /api/v3/ins/vld-report/download
POST /api/v3/ins/pld-report
POST /api/v3/ins/pld-report/download

About IQM Insights​

Insights reports are one of IQM's analytics tools that help Advertisers quickly identify trends and apply precise adjustments to deliver better results for Campaigns. With pre-defined metrics and dimensions, Insights reports can be generated for the following areas:

  • Campaign Bidding Insights capture rejected Campaigns and segments them based on rejection reason, allowing you to assess which parameters are limiting a Campaign's success.
  • Audience Insights provide in-depth Reports of Audience characteristics, interests, and behaviors to give you a deeper understanding of your target Audience and create targeted and personalized advertising strategies.
  • Voter Level Data (VLD) Reports offer Insights about targeting in current or prior political Campaigns. These Reports include ad exposure, engagement data, demographic data, and voting-history details by voter.
  • Provider Level Data (PLD) Reports include details about healthcare professionals targeted in your Campaigns, and provide similar details as VLD Reports while adhering to healthcare data privacy regulations.

Before You Begin​

To generate an Insights Report you will need an account on the IQM Platform (see Getting Started). Once you have an account you can log in and review the eligibility requirements table for each kind of Insights Report.

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 Sample
{
   "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."
      }
   ]
}

Eligibility Requirements​

The table below outlines the eligibility requirements for each Insights Report type and includes relevant resources. Click on a type to jump to the instructions for generating that Insights Report.

TypeRequirementsResources
Campaign Bidding InsightsCampaign requirements:
  • More than 1 impression
  • Status: "running", "paused", or "expired" (within last two weeks)
  • Type: "advanced"
Campaign API
Create New Campaign
Campaign Status Type ID
Campaign Type ID
Audience InsightsAudience requirements:
  • Type: Matched Audience
  • Status: "ready"
  • Reach: 10,000+
  • (Recommended) Creation date within the last year
Upload a Matched Audience
Audience API
Audience Status Type ID
Audience Type ID
Voter Level Data ReportCampaign requirements:
  • Must be a political Campaign
  • Status: "running", "paused", or "expired" (within last two years)
  • Must have duration of 3 or more days
  • Creation date: Sept. 16, 2024 or later
  • Voter location: all US states (except Oregon)
  • Audience type: Matched Audience
Provider Level Data ReportCampaign requirements:
  • Must be healthcare Campaign
  • "running", "expired" (within last 90 days), "paused" (within last 90 days) status
  • Must have duration of 3 or more days
  • Audience type: Matched Audience from NPI IDs
ABM Audience Details

Campaign Bidding Insights​

Step 1: Check Campaign for Eligibility​

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

To generate Campaign Bidding Insights, use the campaignId and the Get Campaign Details endpoint to check if the eligibility requirements are met.

The endpoint will return a JSON schema of Campaign details; the relevant parameters are highlighted in the sample Response 200 code block. A Campaign type of 1 means it's an "advanced" Campaign. In the sample response the status is running, and the impressions count is 5. This Campaign meets the eligibilty requirements to generate an Insights Report.

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: Generate Insights​

GET /api/v3/ins/campaign/bid-insights/{campaignId}

Once a Campaign is determined eligible, you can generate Bidding Insights. Pass the campaignId in the endpoint's path and use the query parameters to specify the date range of the Insights report (maximum two weeks).

This endpoint will return a list of rejection reasons for why the Campaign's bid requests were dropped. The number of bids won will also be returned.

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
Query Parameters
dateRangeStart
integer		Unix epoch timestamp, in milliseconds
dateRangeEnd
integer		Unix epoch timestamp, in milliseconds
Response Properties
rejectionList
object		List of bid rejection reasons
rejectionList object properties
campaignSettings
object		Campaign settings
ioBudget
object		IO Budget
inventoryTargeting
object		Inventory targeting
campaignBidPrice
object		Campaign bid price
locationTargeting
object		Location targeting
deviceTargeting
object		Device targeting
creativeSettings
object		Creative settings
advanceTargeting
object		Advanced targeting
audienceTargeting
object		Audience targeting
bidStrategy
object		Bid strategy
campaignBudget
object		Campaign budget
demographicsTargeting
object		Demographics targeting
undefined
object		Undefined
rejectionList sub-objects properties
title
string		Object title
rejectedBids
integer		Rejected bids count
description
string		description
subReasonInfo
object		List of sub-reasons info
topMainReasons
object		rejectionList objects with the highest rejectedBids counts
topSubReasons
object		rejectionList sub-objects with the highest droppedRequests counts
totalBids
integer		Total bids count
lostBids
integer		Lost bids count
totalWins
integer		Total won bids count

subReasonInfo object properties
inactiveAccountBids dropped off because Advertiser's account with IQM is inactive
insufficientBalanceBids dropped off because there is an insufficient balance in your account
creativeRollPositionBids dropped off because the roll position (pre-, mid-, post-roll) didn't match the Campaign's required roll position
creativePlayerSizeBids dropped off because player size did not match Campaign's required player size
ioBudgetBids dropped off because budget on the Campaign's associated IO has spent in full
audienceUnavailableBids dropped off because Audience did not match Campaign's Audience targeting parameters
creativeUnavailableBids dropped off due to the Campaign's creative settings, such as creative type, dimensions, duration and others
campaignBidPriceBids dropped off because the bid price is lower than the floor price recived from the exchange
operatingSystemBids dropped off because Operating System did not match the Campaign's Operating System requirements
manufacturerBids dropped off because the Manufacturer did not match the Campaign's Manufacturer parameters
deviceTypeBids dropped off because the Device Type did not match the Campaign's Device Type targeting parameters
channelsBids dropped off because Channels did not match the Campaign's Channel Targeting Parameters
networkTypesBids dropped off because Network Type did not match the Campaign's Network Type requirements
carrierBids dropped off because Carrier did not match the Campaign's Carrier requirements
Response 200
{
  "success": true,
  "data": {
    "totalRequests": 100,
    "rejectionList": {
      "campaignSettings": {
        "title": "Campaign Settings",
        "rejectedBids": 0,
        "description": "Campaign is filtered due to Campaign Settings set in the campaign.",
        "subReasonInfo": {}
      },
      "ioBudget": {
        "title": "IO Budget",
        "rejectedBids": 0,
        "description": null,
        "subReasonInfo": {}
      },
      "inventoryTargeting": {
        "title": "Inventory Targeting",
        "rejectedBids": 0,
        "description": "Campaign is filtered due to Inventory Targeting.",
        "subReasonInfo": {}
      },
      "campaignBidPrice": {
        "title": "Campaign Bid Price",
        "rejectedBids": 0,
        "description": "Campaign is filtered because the bid price is lower than the floor price received from the exchange.",
        "subReasonInfo": {}
      },
      "locationTargeting": {
        "title": "Location Targeting",
        "rejectedBids": 0,
        "description": "Campaign is filtered due to Location Targeting.",
        "subReasonInfo": {}
      },
      "deviceTargeting": {
        "title": "Device Targeting",
        "rejectedBids": 0,
        "description": "Campaign is filtered due to Device Targeting.",
        "subReasonInfo": {}
      },
      "creativeSettings": {
        "label": "Creative Settings",
        "rejectedBids": 100,
        "description": "Campaign is filtered due to non-matching creative dimensions found in the request",
        "subReasonInfo": {
          "creativeDimension": {
            "label": "Creative Dimensions",
            "droppedRequests": 100,
            "description": "Campaign is filtered due to non-matching creative dimensions found in the request."
          }
        }
      },
      "advanceTargeting": {
        "title": "Advanced Targeting",
        "rejectedBids": 0,
        "description": null,
        "subReasonInfo": {}
      },
      "audienceTargeting": {
        "title": "Audience Targeting",
        "rejectedBids": 0,
        "description": "Campaign is filtered due to Audience Targeting.",
        "subReasonInfo": {}
      },
      "bidStrategy": {
        "title": "Bid Strategy",
        "rejectedBids": 0,
        "description": "Campaign is filtered due to bid strategy setting applied in campaign.",
        "subReasonInfo": {}
      },
      "campaignBudget": {
        "title": "Campaign Budget",
        "rejectedBids": 0,
        "description": "Campaign is filtered because the campaign budget is now unavailable for further bidding.",
        "subReasonInfo": {}
      },
      "demographicsTargeting": {
        "title": "Demographics Targeting",
        "rejectedBids": 0,
        "description": "Campaign is filtered due to Demographics Targeting.",
        "subReasonInfo": {}
      },
      "undefined": {
        "title": "Undefined",
        "rejectedBids": 0,
        "description": "Campaign is filtered due to Undefined reasons.",
        "subReasonInfo": {}
      }
    },
    "topMainReasons": {
      "creativeSettings": 100
    },
    "topSubReasons": {
      "creativeDimension": 100
    },
    "totalBids": 0,
    "lostBids": 0,
    "totalWins": 0
  }
}

Response 422 (invalid start date)

{
  "success": false,
  "errorObjects": [
    {
      "error": "Date Range End must be greater than Date Range Start"
    }
  ]
}

Audience Insights Report​

Step 1: Check for Eligible Audiences​

GET /api/v3/ins/audiences/list

To generate an Audience Insights Report, first use this endpoint to retrieve a list of eligible Audiences.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Query Parameters
searchField
string		Search results by keyword
pageSize
integer		Maximum number of entries per page, default: 20
pageNo
integer		Number of pages for retrieved data
sortBy
string		Sorts by ascending (+) or descending (-), default: -id
Response Properties
insightsData
object		Insights data details
insightsData object properties
id
integer		Audience ID
audienceName
string		Audience name
matchRate
integer		The percentage of matched records compared to a reference set
uniques
integer		Count of unique Audiences reached
Response 200
{
  "success": true,
  "data": {
    "totalRecords": 10,
    "filteredRecords": 3,
    "insightsData": [
      {
        "id": 12345,
        "audienceName": "audience1",
        "matchRate": 58.99,
        "uniques": 52432
      },
      {
        "id": 12365,
        "audienceName": "audience2",
        "matchRate": 78.88,
        "uniques": 72786
      },
      {
        "id": 12376,
        "audienceName": "audience3",
        "matchRate": 34.88,
        "uniques": 31122
      }
    ]
  }
}

Step 2: Generate Insights Report​

POST /api/v3/ins/insights/add

Pass the Audience id (from the response data in step 1) in the Source IDs array to generate the Audience Insights Report with this endpoint.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Request Schema
insightsTypeId
integer		Insights Type ID
sourceIds
integer		Source IDs
Response Properties
invalidSourceIds
array of integers		Invalid source IDs list
insightsData
object		Insights data details
insightsData object properties
id
integer		Audience Insights ID
typeId
integer		Insights type ID
statusId
integer		Insights Status ID
sourceName
string		Source name
name
string		Insights name
sourceId
integer		Source ID
createdAt
integer		Unix epoch timestamp of Insights creation date, in milliseconds
Request Sample
{
  "insightsTypeId": 1,
  "sourceIds": [
    567895,
    925436,
    123677
  ]
}
Response 200
{
  "success": true,
  "data": {
    "invalidSourceIds": [],
    "insightsData": [
      {
        "id": 1213,
        "typeId": 1,
        "statusId": 2,
        "sourceName": "Data Trust NY 4 Cols",
        "name": "Data Trust NY 4 Cols_insights",
        "sourceId": 1099461,
        "createdAt": 1728366883518
      }
    ]
  }
}

Step 3: Download Insights Report​

POST /api/v3/ins/insights/download

Pass the Insights id (from the response data in step 2) in the insightsId query, along with your desired file type, to generate a download link for your Insights Report.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Query Parameters
insightsId
integer		Insights ID
fileType
string		File type of Report: pdf or xlsx
Request Schema
customLogoFile
string		Multipart/form-data format
Response Properties
insightsReportUrl
string		Insights Report URL
Request Sample
{
    "customLogoFile": "string"
}
Response 200
{
    "success": true,
    "data": {
        "insightsReportUrl": "https://domain.com/insights.pdf"
    }
}

Voter Level Data Report​

Step 1: Check Campaign for Eligibility​

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

To generate a VLD Report, first use the campaignId and the Get Campaign Details endpoint to check if the eligibility requirements are met.

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

  • The status is running.
  • createDate indicates when the Campaign was created (in Unix epoch milliseconds).
  • startTime and endTime indicate the Campaign's duration.
  • A Country ID of 30100001 indicates the targeted Audience is in the US.
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 1.1: Check Campaign Audience Type​

POST /api/v3/cmp/audience/targeting

Pass the campaignId to check its Audience. Audience type ID 1 indicates this Campaign has a Matched Audience.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Request Schema
campaignIds
array of integers		Campaign IDs
Response Properties
campaignId
object		Name-Value pairs of campaignId and its object properties
campaignId object properties
audienceTypeId
integer		Audience Type ID
audienceIds
array of integers		Audience IDs
Request Sample
{
  "campaignIds": [
    52241,
    50322
  ]
}
Response 200
{
  "success": true,
  "data": {
    "543363": [],
    "553441": [
      {
        "audienceTypeId": 1,
        "audienceIds": [
          1101833,
          1101834,
          1101835,
          1102476
        ]
      }
    ],
    "553443": [
      {
        "audienceTypeId": 1,
        "audienceIds": [
          1101831,
          1101835,
          1102476
        ]
      },
      {
        "audienceTypeId": 9,
        "audienceIds": [
          1124205,
          1124206
        ]
      }
    ]
  }
}

Step 2: Generate VLD Report​

POST /api/v3/ins/vld-report

Once the desired Campaign has been determined eligible, pass the campaignId in the request schema (along with vldStartDate and vldEndDate) to generate a VLD Report.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Request Schema
vldStartDate
integer		Unix epoch timestamp of start date, in milliseconds
vldEndDate
integer		Unix epoch timestamp of end date, in milliseconds
campaignId
integer		Campaign ID
Response Properties
vldReportCreated
boolean		Indicates VLD Report was created: true
campaignId
integer		Campaign ID
campaignName
string		Campaign name
campaignStatus
string		Campaign Status Type
vldStartDate
integer		Unix epoch timestamp of start date, in milliseconds
vldEndDate
integer		Unix epoch timestamp of end date, in milliseconds
vldChargeableImps
integer		The number of chargeable impressions for the requested VLD Report
vldChargedImps
integer		The number of impressions for which the VLD Report is already generated
vldChargeableCost
integer		Cost to generate the VLD Report
vldChargedCost
integer		Cost of VLD Report that is already generated
fundsAvailable
boolean		Indicates if sufficient funds are available in the Advertiser's account to generate the VLD Report (true)
Request Sample
{
  "campaignId": 12345,
  "vldStartDate": 1722311000,
  "vldEndDate": 1722315000
}
Response 200
{
  "success": true,
  "data": {
    "vldReportCreated": true,
    "campaignId": 1,
    "campaignName": "Campaign Name",
    "campaignStatus": "running",
    "vldStartDate": 1722311000,
    "vldEndDate": 1722315000,
    "vldChargeableImps": 1000,
    "vldChargedImps": 100,
    "vldChargeableCost": 1000,
    "vldChargedCost": 100,
    "fundsAvailable": true
  }
}

Step 3: Download VLD Report​

POST /api/v3/ins/vld-report/download

Get a download link for a VLD insight Report in CSV or XLSX format.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Request Schema
fileTypeId
integer		File type ID
XLSX: 1
CSV: 2
vldId
integer		VLD ID
Response Properties
vldReportUrl
string		VLD Report File URL
Response 200
{
  "success": true,
  "data": {
    "vldReportUrl": "https://tem.domain.s3.amazonaws.com/vld-campaigns/ds/2024-08-20/503481_Insights_1.xlsx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240820T112818Z&X-Amz-"
  }
}

Provider Level Data Report​

Step 1: Check Campaign for Eligibility​

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

To generate a PLD Report, first use the campaignId and the Get Campaign Details endpoint to check if the eligibility requirements are met.

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

  • The status is running.
  • startTime and endTime indicate the Campaign's duration.
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 1.1 Check Campaign Audience Details​

POST /api/v3/cmp/audience/targeting

Pass the campaignId to check its Audience. Audience type ID 1 indicates this Campaign has a Matched Audience.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Request Schema
campaignIds
array of integers		Campaign IDs
Response Properties
campaignId
object		Name-Value pairs of campaignId and its object properties
campaignId object properties
audienceTypeId
integer		Audience Type ID
audienceIds
array of integers		Audience IDs
Request Sample
{
  "campaignIds": [
    52241,
    50322
  ]
}
Response 200
{
  "success": true,
  "data": {
    "543363": [],
    "553441": [
      {
        "audienceTypeId": 1,
        "audienceIds": [
          1101833,
          1101834,
          1101835,
          1102476
        ]
      }
    ],
    "553443": [
      {
        "audienceTypeId": 1,
        "audienceIds": [
          1101831,
          1101835,
          1102476
        ]
      },
      {
        "audienceTypeId": 9,
        "audienceIds": [
          1124205,
          1124206
        ]
      }
    ]
  }
}

Step 2: Generate PLD Report​

POST /api/v3/ins/pld-report

Once the desired Campaign has been determined eligible, pass the campaignId in the request schema (along with pldStartDate and pldEndDate) to generate a VLD Report.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Request Schema
pldStartDate
integer		Unix epoch timestamp of start date, in milliseconds
pldEndDate
integer		Unix epoch timestamp of end date, in milliseconds
campaignId
integer		Campaign ID
Response Properties
pldReportCreated
boolean		Indicates PLD Report was created: true
campaignId
integer		Campaign ID
campaignName
string		Campaign name
campaignStatus
string		Campaign Status Type
pldStartDate
integer		Unix epoch timestamp of start date, in milliseconds
pldEndDate
integer		Unix epoch timestamp of end date, in milliseconds
pldChargeableImps
integer		The number of chargeable impressions for the requested PLD Report
pldChargedImps
integer		The number of impressions for which the PLD Report is already generated
pldChargeableCost
integer		Cost to generate the PLD Report
pldChargedCost
integer		Cost of PLD Report that is already generated
fundsAvailable
boolean		Indicates if sufficient funds are available in the Advertiser's account to generate the PLD Report (true)
Request Sample
{
  "campaignId": 12345,
  "pldStartDate": 1722311000,
  "pldEndDate": 1722315000
}
Response 200
{
  "success": true,
  "data": {
    "pldReportCreated": true,
    "campaignId": 1,
    "campaignName": "Campaign Name",
    "campaignStatus": "running",
    "pldStartDate": 1722311000,
    "pldEndDate": 1722315000,
    "pldChargeableImps": 1000,
    "pldChargedImps": 100,
    "pldChargeableCost": 1000,
    "pldChargedCost": 100,
    "fundsAvailable": true
  }
}
Response 200 (failure)
{
  "success": true,
  "data": {
    "pldReportCreated": false,
    "message": "PLD Insights can't be generated for this campaign at the moment as another insight with overlapping date range is processing"
  }
}

Step 3: Download PLD Report​

POST /api/v3/ins/pld-report/download

Get a download link for a PLD insight Report in CSV or XLSX format.

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header
Request Schema
fileType
integer		File type ID
XLSX: 1
CSV: 2
pldId
integer		Provider Level Data Report ID
Response Properties
pldReportUrl
string		PLD Report File URL
Request Sample
{
  "fileType": 1,
  "pldId": 50
}
Response 200
{
  "success": true,
  "data": {
    "pldReportUrl": "https://dowload.domain.com/pld-reports/20220101/pld-report-1.xlsx"
  }
}
More Responses
Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Invalid sortBy value."
    }
  ]
}