Skip to main content

Create an Insights report

Create an Insights report with this in-depth tutorial using IQM's API.

The following endpoints are used to check campaigns for eligibility and create different types of Insights reports:

POST
GET
GET
POST
POST
POST
POST
POST
POST
POST

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 reports capture rejected campaigns and segment them based on rejection reason, allowing you to assess which parameters are limiting a campaign's success.
  • Audience Insights reports provide an in-depth view 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) Insights reports offer information 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) Insights reports include details about healthcare professionals targeted in your campaigns, and provide similar details as VLD Insights reports while adhering to healthcare data privacy regulations.

More resources​

Before you begin​

To generate an Insights report, you 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

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		Authentication bearer token. See Sign up and authenticate
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."
      }
   ]
}

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

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 Insights reportCampaign requirements:
  • More than 1 impression
  • Status: "running", "paused", or "expired" (within last two weeks)
  • Type: "advanced"
Campaign API guidelines
Create new campaign
Campaign status type ID
Campaign type ID
Audience Insights reportAudience requirements:
  • Type: Matched audience
  • Status: "ready"
  • Reach: 10,000+
  • (Recommended) Creation date within the last year
Upload a Matched audience
Audience API guidelines
Audience status type ID
Audience type ID
VLD Insights 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
PLD Insights 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 report​

Step 1: Check campaign for eligibility​

GET

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

The endpoint returns 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 eligibility requirements to generate an Insights report.

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": 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 Campaign Bidding Insights report​

GET

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

This endpoint returns a list of rejection reasons for why the campaign's bid requests were dropped. The number of bids won is also returned.

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

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

Query parameters
searchField
string		Filter results by search field
pageSize
integer		Number of entries returned per page, default: 20
pageNo
integer		Page number of 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 Audience Insights report​

POST

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.

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 Audience Insights report​

POST

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 Audience Insights report.

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		Audience Insights report URL
Request sample
{
    "customLogoFile": "string"
}
Response 200
{
    "success": true,
    "data": {
        "insightsReportUrl": "https://domain.com/insights.pdf"
    }
}

VLD Insights report​

Step 1: Check campaign for eligibility​

GET

To generate a VLD Insights report, first use the campaignId and the Get campaign details endpoint to check if the eligibility requirements are met.

The endpoint returns 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.
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": 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

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

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.
Supported values
1Matched audience
2Segmented audience
3Retargeted audience
4Geofarmed audience
5Contextual audience
6Lookalike audience
7Campaign audience
8Pre-bid audience
9Account Based Marketing (ABM) audience
10Custom Voter audience (CVA)
11Integrated Care Team (ICT) audience
12Power Segment audience
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 Insights report​

POST

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

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 Insights 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 Insights report
vldChargedImps
integer		The number of impressions for which the VLD Insights report is already generated
vldChargeableCost
integer		Cost to generate the VLD Insights report
vldChargedCost
integer		Cost of VLD Insights report that is already generated
fundsAvailable
boolean		Indicates if sufficient funds are available in the Advertiser's account to generate the VLD Insights 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 Insights report​

POST

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

Request schema
fileTypeId
integer		File type ID
XLSX: 1
CSV: 2
vldId
integer		VLD ID
Response properties
vldReportUrl
string		VLD Insights 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-"
  }
}

PLD Insights report​

Step 1: Check campaign for eligibility​

GET

To generate a PLD Insights report, first use the campaignId and the Get campaign details endpoint to check if the eligibility requirements are met.

The endpoint returns 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.
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": 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

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

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.
Supported values
1Matched audience
2Segmented audience
3Retargeted audience
4Geofarmed audience
5Contextual audience
6Lookalike audience
7Campaign audience
8Pre-bid audience
9Account Based Marketing (ABM) audience
10Custom Voter audience (CVA)
11Integrated Care Team (ICT) audience
12Power Segment audience
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 Insights report​

POST

Once the desired campaign has been determined eligible, pass the campaignId in the request schema (along with pldStartDate and pldEndDate) to generate a PLD Insights report.

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 Insights 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 Insights report
pldChargedImps
integer		The number of impressions for which the PLD Insights report is already generated
pldChargeableCost
integer		Cost to generate the PLD Insights report
pldChargedCost
integer		Cost of PLD Insights report that is already generated
fundsAvailable
boolean		Indicates if sufficient funds are available in the Advertiser's account to generate the PLD Insights 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 Insights report​

POST

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

Request schema
fileType
integer		File type ID
XLSX: 1
CSV: 2
pldId
integer		PLD Insights report ID
Response properties
pldReportUrl
string		PLD Insights 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."
    }
  ]
}
Have a question?
Ask the community
Was this page helpful?