Skip to main content

Insights API

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:

TypeDescriptionNotes
Campaign Bidding InsightsCampaign Bidding Insights capture rejected campaigns and segment them based on rejection reason, allowing you to assess which parameters are limiting a campaign’s success.
Audience Insights reportAudience Insights reports 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.
Power Segment Insights (PSI)PSI reports provide audience data for pre-defined political personality segments, such as office-holders, candidates, and other public figures. Available to political vertical Advertisers only.
Audience Quality (AQ) Insights reportAQ Insights reports leverage third-party healthcare data from PurpleLab to confirm audience exposure based on patient-level targeting criteria including prescriptions, diagnoses, and procedures.
Voter Level Data (VLD) Insights reportVLD 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.
Script Lift Study (SLS) Insights reportSLS Insights reports include key details about prescribing behaviors and how they are influenced by current and previous healthcare campaigns.
Provider Level Data (PLD) Insights reportPLD 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.PLD Insights, NLD Insights, and ICT Insights reports are handled by the Report templates endpoints with the category parameter.
Nurse Level Data (NLD) Insights reportNLD Insights reports offer deeper visibility into how Non-NPI nurses engage with your campaigns. They uncover ad-exposure, engagement, demographic, and physician-specialty data to reveal reach and impact.
Integrated Care Team (ICT) Insights reportICT Insights reports uncover key details about the ICT Audiences you’ve targeted in previous and current campaigns.
NOTE

Some Insights reports will need to be enabled by an administrator to access. By default VLD, PLD, SLS, and AQ Insights reports are not accessible to Advertiser users.

You can check an Advertiser's access to Insights reports with the Get Customer config details endpoint.

More resources​

Authentication​

Use the following header parameters for all requests:

Headers
Authentication
string required		Authentication bearer token.
See Sign up and authenticate.
X-IAA-OW-ID
integer required		Organization Workspace ID header.

Insights report details​

Get a list of Insights reports​

GET

Get a list of Insights reports available in the database.

An Insights id can be used to perform various actions in Insights report management endpoints.

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
id
integer		Insights report ID.
typeId
integer		Insights report type ID.
statusId
integer		Insights report status ID.
name
string		Insights report name.
sourceId
integer		Insights report source ID.
createdAt
integer		Unix epoch timestamp of Insights creation date, in milliseconds.
Response 200
{
  "success": true,
  "data": {
    "totalRecords": 1,
    "filterRecords": 1,
    "insightsData": [
      {
        "id": 123,
        "typeId": 1,
        "statusId": 2,
        "name": "demo_insights",
        "sourceId": 123,
        "createdAt": 1687848574780
      }
    ]
  }
}

Get Campaign Bidding Insights​

GET

Campaign Bidding Insights provides a list of bid rejection reasons for a given campaign ID.

info

A campaign must meet the following eligibility criteria to generate Campaign Bidding Insights:

  • More than 1 impression captured
  • "running," "expired" (within last two weeks), "paused" status
  • Must have been active within the last two weeks
  • Campaign type: "advanced"
Path parameters
campaignId
integer		Campaign ID.
Query parameters
dateRangeStart
integer required		Unix epoch timestamp, in milliseconds.
dateRangeEnd
integer required		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.

Bid rejection descriptions
accountSettings 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.
creativeSettings subReasonInfo object properties
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.
creativeDimensionBids dropped off due to the size of creative.
creativeUnavailableBids dropped off due to the campaign's creative settings, such as creative type, dimensions, duration and others.
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.
campaignBidPriceBids dropped off because the bid price is lower than the floor price received from the exchange.
operatingSystemBids dropped off because Operating System did not match the campaign's Operating System requirements.
deviceTargeting subReasonInfo object properties
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"
    }
  ]
}

Get Insights reports count by type​

GET

Get a count of Insights reports by type ID. See list of Insights report type IDs.

Response properties
data
object		Name-Value pairs of insightsTypeId and count.
Response 200
{
    "success": true,
    "data": {
        "1": 32,
        "3": 20
    }
}

Get eligible campaigns​

GET

Get a status-wise list of eligible campaigns for generation of PLD, ICT, or NLD Insights reports.

Eligible campaign IDs can be used in the Calculate Insights computation and Create report template endpoints.

Query parameters
reportType
string required		Type of report: pld, ict, or nld.
Response properties
running
array of objects		Campaigns with running status.
paused
array of objects		Campaigns with paused status.
expired
array of objects		Campaigns with expired status.
Campaign object properties
campaignId
integer		Campaign ID.
campaignTimezoneId
integer		Timezone ID.
Response 200
{
  "success": true,
  "data": {
    "running": [
      {
        "campaignId": 451351,
        "campaignTimezoneId": 29
      }
    ],
    "paused": [
      {
        "campaignId": 451350,
        "campaignTimezoneId": 29
      }
    ],
    "expired": [
      {
        "campaignId": 470839,
        "campaignTimezoneId": 29
      }
    ]
  }
}
Response 400
{
  "success": false,
  "errorObjects": [
    {
      "error": "Invalid report type provided : vlds"
    }
  ]
}

Calculate Insights computation​

POST

Compute the cost and impressions for creation of PLD, ICT, or NLD Insights reports based on the provided campaign IDs and date range.

The computation calculates the chargeable impressions and cost based on the markup charged to the Organization. This returns an estimate only; it doesn't create a report or charge the account.

Request schema
category
string required		Insights type category: pld, ict, or nld.
campaignIds
array of integers required		Campaign IDs for which to compute the report.
startDate
integer required		Unix epoch timestamp of report start date, in milliseconds.
endDate
integer required		Unix epoch timestamp of report end date, in milliseconds.
reportId
integer		ID of an existing report (for example, a failed one) to price its regeneration. When set, the other fields aren't needed.
Response properties
ioId
integer		Insertion order ID.
ioName
string		Insertion order name.
startDate
integer		Unix epoch timestamp of report start date, in milliseconds.
endDate
integer		Unix epoch timestamp of report end date, in milliseconds.
campaignIds
array of integers		Campaign IDs included in the computation.
reportCreatable
boolean		Indicates whether the report can be created.
chargeableImps
integer		Number of chargeable impressions.
chargedImps
integer		Impressions already paid for by an earlier report of the same type. These aren't billed again.
chargeableCost
number		Chargeable cost amount.
chargedCost
number		Cost of impressions already paid for by an earlier report of the same type. This isn't billed again.
fundsAvailable
boolean		Indicates whether sufficient funds are available.
effectiveRate
number		Rate per 1,000 impressions (CPM) for this report type.
templateId
integer		Associated template ID.
Request sample
{
  "category": "pld",
  "campaignIds": [451351, 451352],
  "startDate": 1640995200000,
  "endDate": 1643673599000
}
Response 200
{
  "success": true,
  "data": {
    "ioId": 101,
    "ioName": "Test IO",
    "startDate": 1742898000000,
    "endDate": 1774238399000,
    "campaignIds": [11011],
    "reportCreatable": true,
    "chargeableImps": 100,
    "chargedImps": 25,
    "chargeableCost": 345.23,
    "chargedCost": 45.21,
    "fundsAvailable": true,
    "effectiveRate": 3.45,
    "templateId": 111
  }
}
Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Date range is invalid or exceeds maximum allowed period"
    }
  ]
}

Insights report management​

Delete Insights report record​

DELETE

Delete records from the database for valid Insights reports IDs passed.

Query parameters
insightsIds
string		Comma separated Insights report IDs to delete.
Response properties
deletedIds
array of integers		Deleted Insights report records.
invalidIDs
array of integers		Invalid IDs.
Response 200
{
  "success": true,
  "data": {
    "deletedIds": [
      35,
      34
    ],
    "invalidIds": [
      33,
      1
    ]
  }
}

Regenerate Insights report​

POST

Regenerates an Insights report.

Path parameters
insightsIds
string		Comma separated Insights report IDs to regenerate.
Response properties
success
boolean		Indicates Insights report was successfully regenerated: true.
data
string		Success message.
Response 200
{
  "success": true,
  "data": "Insights regenerated successfully."
}
Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "error message."
    }
  ]
}

Send Insights report email​

POST

Send an attached Insights report file via email to specified recipients.

Query parameters
id
integer		Insights report ID.
attachmentType
string		File type of report: pdf or xlsx.
recipientEmails
string		Comma separated string of emails to send Insights report to, up to 15.
Request schema
file
string		Multipart/form-data format.
Response properties
success
boolean		Indicates Insights report email was successfully sent: true.
data
string		Success message.
Request sample
{
  "file": "string"
}
Response 200
{
  "success": true,
  "data": "Insights-1 pdf email sent successfully."
}

Audience Insights report​

Get a list of eligible audiences​

GET

Get a list of audiences eligible for an Insights report.

info

Audiences must have a minimum of 10,000 uniques to be eligible for Insights report generation.

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 report 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
      }
    ]
  }
}

Get Matched audience details​

GET

Get Matched audience details by audience ID.

Path parameters
audienceId
integer		Audience ID.
Response properties
matchedAudienceData
object		Matched Audience Insights report details.
matchedAudienceData object properties
audienceName
string		Audience name.
matchRate
integer		The percentage of matched records compared to a reference set.
uniques
integer		Count of unique audiences reached.
createdDate
integer		Unix epoch timestamp of Audience Insights report creation date, in milliseconds.
fileTotalCount
integer		Total number of records in the uploaded audience file.
dataCost
integer		Fees charged by the platform if the audience is used in any campaign.
audienceStatusName
string		Audience status.
s3FileName
string		S3 file name.
Response 200
{
  "success": true,
  "data": {
    "matchedAudienceData": {
      "audienceName": "Data Trust NY 4 Cols",
      "matchRate": 90.0,
      "uniques": 90,
      "createdDate": 1728010319,
      "fileTotalCount": 100,
      "dataCost": 2.0,
      "audienceStatusName": "Ready",
      "s3FileName": "1728010319692_DataTrust_NY_4_Cols.csv"
    }
  }
}

Get Matched audience file URL​

GET

Get Matched audience details as a file URL.

Path parameters
audienceId
integer		Audience ID.
Response properties
audienceFileUrl
string		Matched audience file URL.
Response 200
{
    "success": true,
    "data": {
        "audienceFileUrl": "https://iqm-data-lake-stage.s3.amazonaws.com/CAM-FILES/Client%3D202029/Audience%3D1099461/1728010319692_DataTrust_NY_4_Cols.csv?response-content-disposition=attachment%3Bfilename%3D1728010319692_DataTrust_NY_4_Cols.csv&response-content-type=application%2Foctet-stream&AWSAccessKeyId=ASIAZSYSEW2IDYRQV256&Signature=bg47k4d9Yr6XEp1%2B2AiQpG6UsH8%3D&x-amz-security-token=IQoJb3JpZ2luX2VjEDwaCXVzLWVhc3QtMSJIMEYCIQDZQ0HdONURAdKClNDJtsxRy2Q%2FuhAVl8j8mkg%2BYySOXAIhALLGdASViJ%2BjqGbMUOeNGVzSKJmWlO4Rndg9%2FwYMeFCvKoQECKT%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQAhoMNjU4Nzc4NjY2NjQwIgxTA4EPtZELcoAi5R4q2APj0QWXoTRXCAdw7rbtrcGELFLafSFSWkvl2TlAs%2BIXPNNRwL2y2ymFrmlCOxqFCs9DTWR%2FMRvZMmn7CiN%2ByOPem4C8Rp%2BKE6VSTBeMvQrjQIl1l3S0NxluwzOuBiv%2FA2q0%2F2ehoIPkOOl0ecoghzO8%2FZFVPvVjJkWCnm6c8x2MubJXVYZdiOWd2MHaUmMzsIRlvvl4s30JW9iNnHyOdIyHf6JQ2FbYmKSX4SVEPrv7j7kUv3Vr2iffNE%2BQfGYNtQLr7Yu6yjXpko6N6oZ0BpKsw%2BmwgywN%2FWgPBOQUcwZsexrjBkN9%2BMfRWwOKRS%2F6mn80VYRNV%2F2bA0jDzUBVUmATCjmPFx2tovoveIbb7dwm627ulG0yAkJYx4pvn6OFuFQiZ8YMpWd3e9Hdz44Jm01dGZ%2FluW17THYmmIMOmf3UUSSlxjHm6MuzfULBmspjtAFi5apazS8zUVxwMaK2UfcRkWV%2FQjvziaEHNdaI%2FEStWpzz8E9KRApKtPTsU%2BeXtv2ol1O1Z4GgKOqWRquxqr0qD7rwBX2UjE1Vwp86zcQAxZSj84Uqy%2BqVdh1HUX037Tnpt5DIu9zeHQLHDV2KtH9swuDZyjiNa3z8Mmt%2BSO%2F5wzxOgo8srPyYMIyO3rgGOqQBlVBy4y2GJAjMy2fEyseApwBtfXxXtvcet2hHcTZma1iyMjNL9u92XgsVjHY89iBT4cFAfrTn5c8lswph9%2FKyTm%2FoOQpoxPmkoKD5qs1TCuBFXFXMp4d2Clb%2FUkSmqS01aiEkX1%2FrkAF3klbwrC1%2FUKR6%2BaMAahquyYXskHrlqwBHQ9oizw64rkXNIZeSlbfajnNTVmTkhh3QqyEJw9CYZTNN4hk%3D&Expires=1729596011"
    }
}

Create Audience Insights report​

POST

Create an Insights report for a given audience ID.

Check the list of eligible audiences and Matched audience details endpoints for eligible audiences.

info

An audience must meet the following eligibility criteria to generate Insights report:

  • Must be Matched audience type
  • Audience status: "ready"
  • Audience reach: 10,000+
  • (Recommended) audience creation date within the last year
Request schema
insightsTypeId
integer		Insights type ID.
sourceIds
integer		Source IDs.
(E.g. audience IDs).
Response properties
invalidSourceIds
array of integers		Invalid source IDs list.
insightsData
object		Insights data details.
insightsData object properties
id
integer		Audience Insights report ID.
typeId
integer		Insights report type ID.
statusId
integer		Insights report status ID.
sourceName
string		Source name.
name
string		Insights report name.
sourceId
integer		Source ID.
createdAt
integer		Unix epoch timestamp of Insights report 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
      }
    ]
  }
}

Download Insights report​

POST

Download Insights report for audience (pdf or xlsx) by passing multipart/form-data format.

Query parameters
insightsId
integer		Insights report 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"
    }
}

Power Segment Insights​

info

Power Segment Insights (PSI) is available to Political vertical Advertisers only.

Generate PSI report​

POST

Initiates report generation for a Power Segment identified by its taxonomyId. The request is forwarded to the data team after validating the segment's current report status.

Only segments with a status of NotRequested or Failed can be triggered.

See Get Power Segment Insights list.

Request schema
taxonomyId
string		Taxonomy ID of the Power Segment.
Response properties
message
string		Success message.
Request sample
{
  "taxonomyId": "IQMADV0002606"
}
Response 200
{
  "success": true,
  "data": {
    "message": "Report generation initiated successfully."
  }
}
Response 422 (report already in progress or ready)
{
  "success": false,
  "errorObjects": [
    {
      "error": "Report generation cannot be initiated. Current report status is: Processing"
    }
  ]
}

Get Power Segment Insights list​

GET

Get a list of Power Segments and their available reports, based on search, sorting, and pagination criteria.

Query parameters
searchField
string		Search Power Segments by name.
sortBy
string		Sorts by ascending (+) or descending (-), allowed values: id, name, category.
pageNo
integer		Page number of retrieved data.
noOfEntries
integer		Number of entries returned per page, default: 20.
categories
array of strings		Filter Power Segments by category name, e.g. CABINET_MEMBERS.
visibilityScope
array of strings		Filter by visibility scope, allowed values: public, private. Default: public.
Response properties
totalRecords
integer		Total number of Power Segments.
filteredRecords
integer		Number of Power Segments matching the search/filter criteria.
powerSegmentsReports
array of objects		Power Segments matching the search/filter criteria.
object properties
id
integer		Power Segment ID.
name
string		Power Segment name.
category
string		Power Segment category.
reports
array of objects		Reports available for this Power Segment.
object properties
type
string		Report type.
status
string		Report status: NotRequested, Processing, Ready, or Failed.
generationTime
number		Estimated report generation time, in minutes.
sizeInBytes
integer		Report file size, in bytes.
taxonomyId
string		Taxonomy ID used to generate, download, or email this report.
Response 200
{
  "success": true,
  "data": {
    "totalRecords": 2,
    "filteredRecords": 2,
    "powerSegmentsReports": [
      {
        "id": 1,
        "name": "Donald Trump",
        "category": "Neptune",
        "reports": [
          {
            "type": "SPHERE",
            "status": "NotRequested",
            "generationTime": 3.0,
            "sizeInBytes": null,
            "taxonomyId": "283230NNJW"
          },
          {
            "type": "ORBIT",
            "status": "NotRequested",
            "generationTime": 3.0,
            "sizeInBytes": null,
            "taxonomyId": "56329JJSH67"
          }
        ]
      },
      {
        "id": 2,
        "name": "Hillary Clinton",
        "category": null,
        "reports": [
          {
            "type": "SPHERE",
            "status": "NotRequested",
            "generationTime": 3.0,
            "sizeInBytes": null,
            "taxonomyId": "HHKNW972JL"
          }
        ]
      }
    ]
  }
}

Download PSI report​

GET

Get a presigned S3 URL for downloading the PSI report PDF for the given taxonomyId. The report must be in Ready status. If the segment's personality is private, only the owning organization can download it.

Query parameters
taxonomyId
string required		Taxonomy ID of the Power Segment.
Response properties
reportURL
string		Presigned URL for downloading the PSI report PDF.
Response 200
{
  "success": true,
  "data": {
    "reportURL": "https://s3.amazonaws.com/..."
  }
}
Response 422 (report not ready)
{
  "success": false,
  "errorObjects": [
    {
      "error": "Report is not ready for download."
    }
  ]
}

Email PSI report​

POST

Sends the PSI report PDF for the given taxonomyId to the specified email addresses.

If the file is 10 MB or smaller the PDF is attached directly; otherwise the email includes a download link only. The report must be in Ready status.

Query parameters
taxonomyId
string required		Taxonomy ID of the Power Segment.
Request schema
emailIds
array of strings		Email addresses to send the report to, 1-15 addresses, each 1-320 characters.
Response properties
message
string		Success message.
Request sample
{
  "emailIds": ["jane.doe@example.com"]
}
Response 200
{
  "success": true,
  "data": {
    "message": "Report email sent successfully."
  }
}
Response 422 (report not ready)
{
  "success": false,
  "errorObjects": [
    {
      "error": "Report is not ready for download."
    }
  ]
}

Get Power Segment Insights category types​

GET

Get all Power Segment Insights category types with their names, display names, and display orders.

Use name as the value for the categories filter on Get Power Segment Insights list.

Response 200
{
  "success": true,
  "data": [
    { "id": 1, "name": "CABINET_MEMBERS", "displayName": "Cabinet Members", "order": 10 },
    { "id": 2, "name": "GOVERNOR", "displayName": "Governor", "order": 20 },
    { "id": 3, "name": "HOUSE_OF_REPRESENTATIVE", "displayName": "House of Representative", "order": 30 },
    { "id": 4, "name": "SENATOR", "displayName": "Senator", "order": 40 },
    { "id": 5, "name": "MAYOR", "displayName": "Mayor", "order": 50 }
  ]
}

Get Power Segment Insights avatar URL​

GET

Get a presigned S3 URL for the profile avatar image at the given s3Path, scoped to the given taxonomyId. The report must be in Ready status. If the segment's personality is private, only the owning organization can access it.

Query parameters
taxonomyId
string required		Taxonomy ID of the Power Segment.
s3Path
string required		S3 URI of the profile avatar image, scoped under the segment's own taxonomy folder.
Response properties
avatarURL
string		Presigned URL for the profile avatar image.
Response 200
{
  "success": true,
  "data": {
    "avatarURL": "https://s3.amazonaws.com/..."
  }
}
Response 422 (avatar not found)
{
  "success": false,
  "errorObjects": [
    {
      "error": "Avatar file not found for the provided taxonomyId: IQMADV0002606"
    }
  ]
}

Get Power Segment Insights report data​

GET

Get the PSI report JSON data from S3 for the given taxonomyId, used to render the Power Segment Insights report viewer. The report must be in Ready status. If the segment's personality is private, only the owning organization can access it.

Query parameters
taxonomyId
string required		Taxonomy ID of the Power Segment.
Response properties
insightType
string		Report type: SPHERE or ORBIT.
data
object		Report content used to render the report viewer. Its shape is generated by the backend's page-builder and may change as new block types are introduced.
Response 200
{
  "success": true,
  "data": {
    "insightType": "ORBIT",
    "data": {
      "id": "IQMADV0002606",
      "pageData": [
        {
          "title": "Profile",
          "id": 1,
          "blocks": [
            {
              "type": "profileHeader",
              "data": {
                "firstName": "John",
                "lastName": "Doe",
                "subjectTitle": "Senator",
                "state": "Texas"
              }
            }
          ]
        }
      ]
    }
  }
}
Response 403 (private report, owner mismatch)
{
  "success": false,
  "errorObjects": [
    {
      "error": "This report is private and cannot be accessed"
    }
  ]
}
Response 422 (report not ready)
{
  "success": false,
  "errorObjects": [
    {
      "error": "Report is not ready. Current report status is: Processing"
    }
  ]
}

Audience Quality (AQ) Insights report​

AQ Insights report eligibility requirements​

AQ Insights reports are available for campaigns that meet certain requirements.

Read more about these requirements in our Help Center article.

Requirement typeRequirement detailsNotes
Campaign verticalHealthcare.Any campaign created under a Healthcare Advertiser account is a “Healthcare” campaign.
Audience typeMatched (Patient), Segmented (Patient).
Audience statusReady.
Campaign typeAdvanced, and targeting at least one patient audience.
Campaign statusRunning, Expired (within the past two years), Paused.
Campaign impressions1K or more impressions.
Campaign duration14 or more days.

AQ Insights report resource properties​

Resource properties
reportId
integer		AQ Insights report ID.
reportName
string		AQ Insights report name.
campaignId
integer		Campaign ID.
campaignName
string		Campaign name.
statusId
integer		AQ Insights report status type ID.
statusName
string		AQ Insights report status name.
startDate
integer		Unix epoch timestamp of start date, in milliseconds.
endDate
integer		Unix epoch timestamp of end date, in milliseconds.
ioId
integer		Insertion order ID.
ioName
string		Insertion order name.
ioBudgetType
integer		Insertion order budget type ID.
Supported values
1Budget
2Impression
isCampaignEligible
boolean		Indicates that campaign is eligible for AQ Insights report: true.
reportCreatedOn
integer		Unix epoch timestamp of creation date, in milliseconds.
creativeTypeId
integer		Creative type ID.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
campaignTimeZoneId
integer		Timezone ID.
fileSizeDetails
object		Object containing file sizes by type ID (1: XLSX, 2: CSV).
aqsReportCreatable
boolean		Indicates if AQ Insights report can be generated for the given campaign and date range (true).
aqsChargeableImps
integer		The number of chargeable impressions for the requested AQ Insights report.
aqsChargedImps
integer		The number of impressions for which the AQ Insights report is already generated.
aqsChargeableCost
number		Cost to generate the AQ Insights report.
aqsChargedCost
number		Cost of AQ Insights report that is already generated.
fundsAvailable
boolean		Indicates if sufficient funds are available in the Advertiser's account to generate the AQ Insights report (true).
effectiveAqsRate
number		The effective rate applied for AQ Insights report generation.

Get list of AQ Insights reports​

GET

Get a paginated list of AQ Insights reports with detailed information.

A reportId can be used in the Download AQ Insights report and Delete AQ Insights report endpoints.

Query parameters
searchField
string		Filter results by search field.
noOfEntries
integer		Number of entries returned per page, default: 200.
pageNo
integer		Page number of retrieved data, default: 1.
sortBy
string		Sorts by ascending (+) or descending (-), default: reportId.
Response 200
{
  "success": true,
  "data": {
    "totalRecords": 10,
    "reportDataList": [
      {
        "reportId": 10,
        "reportName": "530667_AQS_Insights_7",
        "campaignName": "prod-campaign-21145",
        "campaignId": 21145,
        "statusId": 3,
        "statusName": "Completed",
        "startDate": 1603152000000,
        "endDate": 1603411200000,
        "ioId": 5,
        "ioName": "Corporate, Inc.",
        "isCampaignEligible": false,
        "reportCreatedOn": 1721253632000,
        "creativeTypeId": 11,
        "ioBudgetType": 1,
        "campaignTimeZoneId": 29,
        "fileSizeDetails": {
          "1": 1024,
          "2": 1024
        }
      },
      {
        "reportId": 9,
        "reportName": "530667_AQS_Insights_6",
        "campaignName": "Campaign-4949",
        "campaignId": 4949,
        "statusId": 3,
        "statusName": "Completed",
        "startDate": 1603152000000,
        "endDate": 1603411200000,
        "ioId": 15,
        "ioName": "Quinton for Mayor",
        "isCampaignEligible": false,
        "reportCreatedOn": 1720325578000,
        "creativeTypeId": 14,
        "ioBudgetType": 1,
        "campaignTimeZoneId": 29,
        "fileSizeDetails": {
          "1": 1024,
          "2": 1024
        }
      }
    ],
    "filteredRecords": 10
  }
}

Get list of campaigns eligible for AQ Insights reports​

GET

Get a status-wise list of campaign IDs eligible for AQ Insights report generation.

Response properties
running, paused, expired
array of objects		Object array of campaign IDs mapped to each of these three campaign statuses.
Object properties
campaignId
integer		Campaign ID.
campaignTimezoneId
integer		Campaign timezone ID.
Response 200
{
  "success": true,
  "data": {
    "running": [
      {
        "campaignId": 451351,
        "campaignTimezoneId": 29
      }
    ],
    "paused": [
      {
        "campaignId": 451350,
        "campaignTimezoneId": 29
      }
    ],
    "expired": [
      {
        "campaignId": 470839,
        "campaignTimezoneId": 29
      }
    ]
  }
}

Validate AQ Insights report name​

GET

Validate the report name for generation of AQ Insights reports. Checks if the name meets length requirements (3-100 characters) and ensures uniqueness within the Organization.

Query parameters
reportName
string		Name of report to validate.
Response properties
available
boolean		Indicates if the report name is available: true.
message
string		Validation message.
Response 200 (valid)
{
  "success": true,
  "data": {
    "available": true,
    "message": "This AQS report name is valid"
  }
}
Response 200 (already used)
{
  "success": true,
  "data": {
    "available": false,
    "message": "The name 'report_name' is already used by another report, kindly update the name"
  }
}
Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Please provide name with at least 3 characters and maximum of 100 characters"
    }
  ]
}

Compute AQ Insights report cost​

POST

Compute the cost and impressions for AQ Insights report generation based on the campaign and date range. This returns an estimate only; it doesn't create a report or charge the account.

Request schema
campaignId
integer		Campaign ID.
aqsId
integer		AQ Insights report ID (for regeneration).
aqsName
string		AQ Insights report name.
aqsStartDate
integer		Unix epoch timestamp of start date, in milliseconds.
aqsEndDate
integer		Unix epoch timestamp of end date, in milliseconds.
aqsReportTypeId
integer		AQ Insights report type ID.
aqsAudienceConceptGroups
array of objects		Array of audience/concept group mappings.
Request sample
{
  "campaignId": 1,
  "aqsStartDate": 1722311000000,
  "aqsEndDate": 1722315000000,
  "aqsName": "Dummy AQS Name",
  "aqsReportTypeId": 1,
  "aqsAudienceConceptGroups": [{
    "audienceId": 101,
    "conceptGroupId": 202335
  }]
}
Response 200
{
  "success": true,
  "data": {
    "aqsReportCreatable": true,
    "campaignId": 1,
    "aqsStartDate": 1722311000000,
    "aqsEndDate": 1722315000000,
    "aqsChargeableImps": 1000,
    "aqsChargedImps": 100,
    "aqsChargeableCost": 1000,
    "aqsChargedCost": 100,
    "aqsName": "Dummy AQS Name",
    "aqsReportTypeId": 1,
    "aqsAudienceConceptGroups": [{
      "audienceId": 101,
      "conceptGroupId": 202335
    }],
    "fundsAvailable": true
  }
}
Response 200 (report exists)
{
  "success": true,
  "data": {
    "aqsReportCreatable": false,
    "aqsId": 1,
    "aqsName": "AQS report 1",
    "aqsStatus": 1,
    "aqsCreatedOn": 1722315234000,
    "campaignId": 1,
    "ioId": 1,
    "ioName": "Insertion Order Name",
    "ioTypeId": 1,
    "aqsReportTypeId": 1,
    "aqsAudienceConceptGroups": [{
      "audienceId": 101,
      "conceptGroupId": 202335
    }]
  }
}
Response 200 (processing)
{
  "success": true,
  "data": {
    "aqsReportCreatable": false,
    "message": "AQS Insights can't be generated for this campaigns at the moment as another insight with overlapping date range is processing"
  }
}

Generate AQ Insights report​

POST

Generate an AQ Insights report. This endpoint calculates the cost for the impressions based on the impressions and mark up charged on the Organization and then creates the AQ Insights reports.

Request schema
campaignId
integer		Campaign ID.
aqsId
integer		AQ Insights report ID to regenerate.
aqsName
string		AQ Insights report name.
aqsStartDate
integer		Unix epoch timestamp of start date, in milliseconds.
aqsEndDate
integer		Unix epoch timestamp of end date, in milliseconds.
aqsReportTypeId
integer		AQ Insights report type ID.
aqsAudienceConceptGroups
array of objects		Array of audience/concept group mappings.
Request sample (new report)
{
  "campaignId": 1,
  "aqsStartDate": 1722311000000,
  "aqsEndDate": 1722315000000,
  "aqsName": "Dummy AQS Name",
  "aqsReportTypeId": 1,
  "aqsAudienceConceptGroups": [{
    "audienceId": 101,
    "conceptGroupId": 202335
  }]
}
Request sample (regenerate)
{
  "aqsId": 1
}
Response 200
{
  "success": true,
  "data": {
    "aqsReportCreatable": true,
    "aqsChargeableImps": 1,
    "aqsChargedImps": 1,
    "aqsChargeableCost": 1,
    "aqsChargedCost": 1,
    "fundsAvailable": true,
    "effectiveAqsRate": 1
  }
}
Response 200 (report exists)
{
  "success": true,
  "data": {
    "aqsReportCreatable": false,
    "aqsId": 1,
    "aqsName": "AQS report 1",
    "aqsStatus": 1,
    "aqsCreatedOn": 1722315234000,
    "campaignId": 1,
    "ioId": 1,
    "ioName": "Insertion Order Name",
    "ioTypeId": 1,
    "aqsReportTypeId": 1,
    "aqsAudienceConceptGroups": [{
      "audienceId": 101,
      "conceptGroupId": 202335
    }]
  }
}
Response 200 (failure)
{
  "success": true,
  "data": {
    "aqsReportCreatable": false,
    "message": "AQS Insights can't be generated for this campaigns at the moment as another insight with overlapping date range is processing"
  }
}

Get AQ Insights report types​

GET

Get available AQ Insights report types. Returns a list of report types that can be generated. Only users from Advertiser Organizations are authorized to access this endpoint.

Response properties
reportTypeData
array of objects		Array of report type objects.
Object properties
id
integer		Report type ID.
name
string		Report type name.
label
string		Report type display label.
order
integer		Display order.
totalRecords
integer		Total number of records.
filteredRecords
integer		Number of filtered records.
Response 200
{
  "success": true,
  "data": {
    "reportTypeData": [
      {
        "id": 1,
        "name": "audience",
        "label": "Audience",
        "order": 1
      },
      {
        "id": 2,
        "name": "Campaign",
        "label": "Campaign",
        "order": 2
      }
    ],
    "totalRecords": 2,
    "filteredRecords": 2
  }
}

Download AQ Insights report​

POST

Get a download link for an AQ Insights report in CSV or XLSX format. Only reports with a 'ready' status are eligible for download.

Request schema
fileTypeId
integer		File type ID.
Supported values
1XLSX
2CSV
reportId
integer		AQ Insights report ID.
Response properties
reportURL
string		AQ Insights report file URL.
Request sample
{
  "fileTypeId": 1,
  "reportId": 50
}
Response 200
{
  "success": true,
  "data": {
    "reportURL": "https://download.domain.com/aqs-reports/2024-12-03/50_Report.xlsx?X-Amz-Algorithm=AWS4-HMAC"
  }
}
More responses
Response 400
{
  "success": false,
  "errorObjects": [
    {
      "error": "Unsupported file type provided. Please use fileType 1 for XLSX or 2 for CSV."
    }
  ]
}
Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Invalid sortBy value."
    }
  ]
}

Email AQ Insights report​

POST

Send an AQ Insights report to the provided email address(es) after validating the report ID and email addresses.

Request schema
reportId
integer required		AQ Insights report ID to email.
fileTypeId
integer required		File type ID.
Supported values
1XLSX
2CSV
emailIds
array of strings required		Recipient email addresses (1–15).
Response properties
message
string		Success message.
Request sample (XLSX file)
{
  "reportId": 50,
  "fileTypeId": 1,
  "emailIds": ["user1@email.com"]
}
Request sample (CSV file)
{
  "reportId": 50,
  "fileTypeId": 2,
  "emailIds": ["user1@email.com"]
}
Response 200
{
  "success": true,
  "data": {
    "message": "AQS report e-mail sent successfully."
  }
}

Delete AQ Insights report​

DELETE

Delete AQ Insights reports that are not marked as deleted and have a 'failed' status. Requires user authorization and checks if the provided AQ Insights report IDs are valid.

Query parameters
reportIds
string		Comma-separated AQ Insights report IDs.
Response properties
success
boolean		Indicates report was successfully deleted: true.
message
string		Success message.
Response 200
{
  "success": true,
  "data": {
    "message": "255944_AQS_Insights_2 deleted successfully"
  }
}

Voter Level Data (VLD) Insights report​

VLD Insights eligibility requirements​

VLD Insights reports are available for campaigns that meet certain requirements.

Read more about these requirements in our Help Center article.

Requirement typeRequirement detailsNotes
Campaign verticalPolitical.Any campaign created under a Political Advertiser account is a “Political” campaign.
Campaign statusRunning, Expired (within the past two years), Paused.
Campaign duration3 or more days.
Campaign creation dateSeptember 16, 2024 or later (or earlier upon request to IQM's support team).
Voter locationAll US states except Oregon.Due to privacy laws in the state of Oregon, we are unable to generate the VLD Insights report on any voters located there. Contact your account representative for more detailed information on the legality of reidentifying voters at the user level.
Audience typeMatched audience created from L2 IDs, Matched audience created from raw data.Your campaign must only include the audience types listed in this requirements table. For example, you cannot generate a VLD Insights report for a campaign if it includes a Matched audience created from L2 IDs and a Retargeted audience consisting of your website’s past visitors.

The VLD Insights report supports audiences you create using First Name, Last Name, Address, and Phone Number. IQM anonymizes the data in the matching process, encrypts the files, and stores them behind a firewall to protect them against information leaks.

VLD Insights resource properties​

Resource properties
vldId
integer		VLD Insights ID.
vldName
string		VLD Insights name.
vldStatus
integer		VLD Insights status type ID.
ioId
integer		Insertion order ID.
ioName
string		Insertion order name.
ioTypeId
integer		Insertion order budget type ID.
Supported values
1Budget
2Impression
isCampaignEligible
boolean		Indicates that campaign is eligible for VLD Insights report: true.
vldCreatedOn
integer		Unix epoch timestamp of creation date, in milliseconds.
vldStartDate / startDate
integer		Unix epoch timestamp of start date, in milliseconds.
vldEndDate / endDate
integer		Unix epoch timestamp of end date, in milliseconds.
campaignId
integer		Campaign ID.
campaignName
string		Campaign name.
campaignStatus
string		Campaign status type.
creativeTypeId
integer		Creative type ID.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
timezoneId
integer		Timezone ID.
vldReportCreatable
boolean		Indicates if VLD Insights report can be generated for the given campaign and date range (true).
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).
effectiveVldRate
integer		Margin rate set by the admin and Workspace for generating VLD Insights report.

Get list of VLD Insights reports​

GET

Get a list of VLD Insights reports based on search filters.

A vldId can be used in the Generate VLD Insights report, Download VLD Insights report, and Delete VLD Insights report endpoints.

Query parameters
searchField
string		Filter results by search field.
noOfEntries
integer		Number of entries returned per page, default: 200.
pageNo
integer		Page number of retrieved data.
sortBy
string		Sorts by ascending (+) or descending (-), default: -vldId.
Response 200
{
  "success": true,
  "data": {
    "totalRecords": 10,
    "vldReportDataList": [
      {
        "vldId": 10,
        "vldName": "530667_VLD_Insights_7",
        "campaignName": "prod-campaign-21145",
        "campaignId": 21145,
        "vldStatus": 3,
        "startDate": 1603152000,
        "endDate": 1603411200,
        "ioId": 5,
        "ioName": "Corporate, Inc.",
        "isCampaignEligible": false,
        "vldCreatedOn": 1721253632,
        "creativeTypeId": 11,
        "timezoneId": 29,
        "ioTypeId": 1
      },
      {
        "vldId": 9,
        "vldName": "530667_VLD_Insights_6",
        "campaignName": "Campaign-4949",
        "campaignId": 4949,
        "vldStatus": 3,
        "startDate": 1603152000,
        "endDate": 1603411200,
        "ioId": 15,
        "ioName": "Quinton for Mayor",
        "isCampaignEligible": false,
        "vldCreatedOn": 1720325578,
        "creativeTypeId": 14,
        "timezoneId": 29,
        "ioTypeId": 1
      }
    ],
    "filteredRecords": 10
  }
}

Get list of campaigns eligible for VLD Insights reports​

GET

Get a list of campaign IDs by status eligible for VLD Insights report generation.

Response properties
running, paused, expired
array of objects		Object array of campaign IDs mapped to each of these three campaign statuses.
Object properties
campaignId
integer		Campaign ID.
campaignTimezoneId
integer		Campaign timezone ID.
Response 200
{
  "success": true,
  "data": {
    "running": [
      {
        "campaignId": 451351,
        "campaignTimezoneId": 29
      }
    ],
    "paused": [
      {
        "campaignId": 451350,
        "campaignTimezoneId": 29
      }
    ],
    "expired": [
      {
        "campaignId": 470839,
        "campaignTimezoneId": 29
      }
    ]
  }
}

Generate VLD Insights report​

POST

This endpoint calculates the cost for the impressions for the VLD Insights reports based on the impressions and mark up charged on the Organization and then creates the VLD Insights reports.

info

A campaign must meet the following eligibility criteria to generate VLD Insights report:

  • Must be Political campaign
  • "running," "expired" (within last two years), "paused" status
  • 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
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.
vldId
integer		Generate Insights report again for VLD Insights ID.
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
  }
}

Get cost assessment for VLD Insights report​

POST

Calculates the cost for the impressions for the VLD Insights report based on impressions and the mark up charged on the Organization. This returns an estimate only; it doesn't create a report or charge the account.

Request schema
campaignId
integer		Campaign ID.
vldStartDate
integer		Unix epoch timestamp of start date, in milliseconds.
vldEndDate
integer		Unix epoch timestamp of end date, in milliseconds.
Request sample
{
  "campaignId": 1,
  "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
  }
}

Download VLD Insights report​

POST

Get a download link for a VLD Insights report in CSV or XLSX format.

Request schema
fileTypeId
integer		File type ID.
Supported values
1XLSX
2CSV
vldId
integer		VLD Insights 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-"
  }
}

Email VLD Insights report​

POST

Send a VLD Insights report as an email attachment to specified recipients.

Request schema
reportId
integer required		VLD Insights report ID to email.
fileTypeId
integer required		File type ID.
Supported values
1XLSX
2CSV
emailIds
array of strings required		Recipient email addresses (1–15).
Response properties
message
string		Success message.
Request sample (XLSX file)
{
  "fileTypeId": 1,
  "emailIds": ["user1@email.com"],
  "reportId": 50
}
Request sample (CSV file)
{
  "fileTypeId": 2,
  "emailIds": ["user1@email.com"],
  "reportId": 50
}
Response 200
{
  "success": true,
  "data": {
    "message": "VLD report e-mail sent successfully."
  }
}

Delete VLD Insights report​

DELETE

Deletes VLD Insights reports that are not marked as deleted and have a 'failed' status, requires user authorization and checks if the provided VLD Insights report IDs are valid.

Query parameters
vldId
integer		VLD Insights ID.
Response properties
success
boolean		Indicates report was successfully deleted: true.
message
string		Success message.
Response 200
{
  "success": true,
  "data": {
    "message": "255944_VLD_Insights_2 deleted successfully"
  }
}

Script Lift Study (SLS) Insights report​

SLS Insights eligibility requirements​

SLS Insights reports are available for Healthcare campaigns that meet certain requirements.

Read more about these requirements in our Help Center article.

Requirement typeRequirement detailsNotes
Campaign verticalHealthcare.Any campaign created under a Healthcare Advertiser account is a “Healthcare” campaign.
Campaign statusRunning, Expired (within the past two years), Paused.
Campaign impressions>1 impression.
Campaign duration7 or more days.
Campaign start date[Release date], 2025 or later (or earlier upon request from IQM's support team).
Audience typeMatched audience created from NPI IDs.The campaign must only include the audience type listed in this requirements table. For example, you won’t be able to generate an SLS Insights report for a campaign if it includes a Matched audience created from NPI IDs and a Retargeted audience consisting of your website’s past visitors. The NPI-based audience must be assigned to the campaign at the time of report creation and while report generation is in progress to remain eligible.

SLS Insights resource properties​

Resource properties
slsId
integer		SLS Insights ID.
slsName
string		SLS Insights name.
campaignIds
array of integers		Campaign IDs.
slsStatusId
integer		SLS Insights status type ID.
startDate
integer		Unix epoch timestamp of start date, in milliseconds.
endDate
integer		Unix epoch timestamp of end date, in milliseconds.
ioId
integer		Insertion order ID.
ioName
string		Insertion order name.
ioTypeId
integer		Insertion order budget type ID.
Supported values
1Budget
2Impression
isCampaignEligible
boolean		Indicates that campaign is eligible for SLS Insights report: true.
slsCreatedOn
integer		Unix epoch timestamp of creation date, in milliseconds.
campaignSlsTimezoneId
integer		Timezone ID.
slsChargeableImps
integer		The number of chargeable impressions for the requested SLS Insights report.
slsChargedImps
integer		The number of impressions for which the SLS Insights report is already generated.
slsChargeableCost
integer		Cost to generate the SLS Insights report.
slsChargedCost
integer		Cost of SLS Insights report that is already generated.
pdfFileSize
integer		PDF file size in bytes.
excelFileSize
integer		Excel file size in bytes.
slsReportTypeIds
array of integers		SLS Insights report type IDs.

Get list of SLS Insights reports​

GET

Get a list of SLS Insights reports.

An slsId can be used in the Generate SLS Insights report, Download SLS Insights report, and Delete SLS Insights report endpoints.

Query parameters
searchField
string		Filter results by search field.
noOfEntries
integer		Number of entries returned per page, default: 200.
pageNo
integer		Page number of retrieved data.
sortBy
string		Sorts by ascending (+) or descending (-), default: -slsId.
Response 200
{
  "success": true,
  "data": {
    "totalRecords": 2,        
    "slsReportDataList": [
      {
        "slsId": 10,
        "slsName": "530667_SLS_Insights_7",
        "campaignIds": [
          21145,
          21146,
          21147
        ],
        "slsStatusId": 3,
        "slsStatusName": "Failed",
        "startDate": 1732165200000,
        "endDate": 1732424399000,
        "ioId": 5,
        "ioName": "Corporate, Inc.",
        "isCampaignEligible": false,
        "slsCreatedOn": 1721253632,
        "campaignSlsTimezoneId": 29,
        "ioTypeId": 1,
        "pdfFileSize": 2500000,     
        "excelFileSize": 2500000,  
        "slsReportTypeIds": [
          1,
          2,
          3
        ]
      },
      {
        "slsId": 9,
        "slsName": "530667_SLS_Insights_6",
        "campaignId": [
          4949,
          5959
        ],
        "slsStatusId": 2,
        "slsStatusName": "Processing",
        "startDate": 1732165200000,
        "endDate": 1732424399000,
        "ioId": 15,
        "ioName": "Quinton for Mayor",
        "isCampaignEligible": false,
        "slsCreatedOn": 1720325578,
        "campaignSlsTimezoneId": 29,
        "ioTypeId": 1,
        "slsReportTypeIds": [
          1,
          3
        ]
      },
    ],
    "filteredRecords": 2
  }
}

Generate SLS Insights report​

POST

This endpoint calculates the cost for the impressions for the SLS Insights reports based on the impressions and markup charged on the Organization and then creates the SLS Insights reports.

SLS Insights reports support three report types: "Pre vs Post Analysis," "Exposed vs Underexposed Analysis," and "Competitive Analysis."

Refer to our Help Center article for more details: SLS Insights Report Overview - SLS Insights Reporting Methods.

Request schema
ioId
integer		Insertion order ID.
campaignIds
array of integers		Campaign IDs.
slsStartDate
integer		Unix epoch timestamp of start date, in milliseconds.
slsEndDate
integer		Unix epoch timestamp of end date, in milliseconds.
slsName
string		SLS name, 3–100 characters. Must be unique.
slsLookbackDuration
integer		SLS lookback duration, in months (1–6).
conceptGroupId
string		Concept group ID.
reportTypes
array of integers		Report type IDs.
1: Pre vs Post Analysis.
2: Exposed vs Underexposed Analysis.
3: Competitive Analysis.
competitorConceptGroupIds
array of strings		Competitor concept group IDs.
slsId
integer		SLS Insights ID to regenerate.
Request sample
{
  "ioId": 1234,
  "campaignIds": [
    1,
    2,
    3
  ],
  "slsStartDate": 1722311000,
  "slsEndDate": 1722315000,
  "slsName": "Dummy SLS Name",
  "slsLookbackDuration": 3,
  "conceptGroupId": 202335,
  "reportTypes": [
    1,
    2,
    3
  ],
  "competitorConceptGroupIds": [
    800214,
    800215,
    800216
  ]
}
Response 200
{
  "success": true,
  "data": {
    "slsReportCreated": true,
    "campaignIds": [
      1,
      2,
      3
    ],
    "slsStartDate": 1722311000,
    "slsEndDate": 1722315000,
    "slsChargeableImps": 1000,
    "slsChargedImps": 100,
    "slsChargeableCost": 1000,
    "slsChargedCost": 100,
    "slsName": "Dummy SLS Name",
    "slsLookbackDuration": 3,
    "conceptGroupId": 202335,
    "reportTypes": [
      1,
      2,
      3
    ],
    "competitorConceptGroupIds": [
      800214,
      800215,
      800216
    ],
    "fundsAvailable": true
  }
}

SLS Insights reports computation​

POST

Calculates the cost for the impressions for the SLS Insights report based on impressions and the markup charged on the Organization. This returns an estimate only; it doesn't create a report or charge the account.

SLS Insights reports support three report types: "Pre vs Post Analysis," "Exposed vs Underexposed Analysis," and "Competitive Analysis."

Refer to our Help Center article for more details: SLS Insights Report Overview - SLS Insights Reporting Methods.

Request schema
ioId
integer		Insertion order ID.
campaignIds
array of integers		Campaign IDs.
slsStartDate
integer		Unix epoch timestamp of start date, in milliseconds.
slsEndDate
integer		Unix epoch timestamp of end date, in milliseconds.
slsName
string		SLS name, 3–100 characters. Must be unique.
slsLookbackDuration
integer		SLS lookback duration, in months (1–6).
conceptGroupId
string		Concept group ID.
reportTypes
array of integers		Report type IDs.
1: Pre vs Post Analysis.
2: Exposed vs Underexposed Analysis.
3: Competitive Analysis.
competitorConceptGroupIds
array of strings		Competitor concept group IDs.
Request sample
{
  "ioId": 1234,
  "campaignIds": [
    1,
    2,
    3
  ],
  "slsStartDate": 1722311000,
  "slsEndDate": 1722315000,
  "slsName": "Dummy SLS Name",
  "slsLookbackDuration": 3,
  "conceptGroupId": 202335,
  "reportTypes": [
    1,
    2,
    3
  ],
  "competitorConceptGroupIds": [
    800214,
    800215,
    800216
  ]
}
Response 200
{
  "success": true,
  "data": {
    "slsReportCreated": true,
    "campaignIds": [
      1,
      2,
      3
    ],
    "slsStartDate": 1722311000,
    "slsEndDate": 1722315000,
    "slsChargeableImps": 1000,
    "slsChargedImps": 100,
    "slsChargeableCost": 1000,
    "slsChargedCost": 100,
    "slsName": "Dummy SLS Name",
    "slsLookbackDuration": 3,
    "conceptGroupId": 202335,
    "reportTypes": [
      1,
      2,
      3
    ],
    "competitorConceptGroupIds": [
      800214,
      800215,
      800216
    ],
    "fundsAvailable": true
  }
}

Validate SLS Insights report name​

GET

Validate a name for SLS Insights reports.

Query parameters
reportName
string		Report name.
Response properties
success
boolean		Indicates successful validation.
data
string		Success message.
Response 200
{
  "success": true,
  "data": "This SLS report name is valid"
}

Get list of campaigns eligible for SLS Insights reports​

GET

Get a list of campaign IDs by status eligible for SLS Insights report generation.

Response properties
running, paused, expired
array of objects		Object array of campaign IDs mapped to each of these three campaign statuses.
object properties
campaignId
integer		Campaign ID.
campaignTimezoneId
integer		Campaign timezone ID.
Response 200
{
  "success": true,
  "data": {
    "running": [
      {
        "campaignId": 516038,
        "campaignTimezoneId": 29
      }
    ],
    "paused": [
      {
        "campaignId": 523630,
        "campaignTimezoneId": 29
      }
    ],
    "expired": [
      {
        "campaignId": 500291,
        "campaignTimezoneId": 29
      }
    ]
  }
}

Download SLS Insights report​

POST

Get a download link for a SLS Insights report in CSV or XLSX format.

Request schema
fileTypeId
integer		File type ID.
XLSX: 1.
CSV: 2.
reportId
integer		SLS Insights report ID.
Response properties
slsReportUrl
string		SLS Insights report file URL.
Request sample
{
  "fileTypeId": 1,
  "reportId": 50
}
Response 200
{
  "success": true,
  "data": {
    "slsReportUrl": "https://dowload.domain.com/pld-reports/20220101/pld-report-1.xlsx"
  }
}
More responses
Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Invalid sortBy value."
    }
  ]
}

Email SLS Insights report​

POST

Send an SLS Insights report as an email attachment to specified recipients.

Request schema
reportId
integer required		SLS Insights report ID to email.
fileTypeId
integer required		File type ID.
Supported values
1XLSX
3PDF
emailIds
array of strings required		Recipient email addresses (1–15).
Response properties
message
string		Success message.
Request sample (XLSX file)
{
  "fileTypeId": 1,
  "emailIds": ["user1@email.com"],
  "reportId": 50
}
Request sample (PDF file)
{
  "fileTypeId": 3,
  "emailIds": ["user1@email.com", "user2@email.com"],
  "reportId": 50
}
Response 200
{
  "success": true,
  "data": {
    "message": "SLS report e-mail sent successfully."
  }
}

Delete SLS Insights report​

DELETE

Deletes SLS Insights reports that are not marked as deleted and have a 'failed' status, requires user authorization and checks if the provided SLS Insights report IDs are valid.

Query parameters
slsIds
string		Comma separated SLS Insights report IDs.
Response properties
success
boolean		Indicates report was successfully deleted: true.
message
string		Success message.
Response 200
{
  "success": true,
  "data": {
    "message": "255944_PLD_Insights_2 deleted successfully"
  }
}

Report templates​

PLD Insights eligibility requirements​

PLD Insights reports are available for Healthcare campaigns that meet certain requirements.

Read more about these requirements in our Help Center article.

Requirement typeRequirement detailsNotes
Campaign verticalHealthcare.Any campaign created under a Healthcare Advertiser account is a “Healthcare” campaign.
Campaign statusRunning, Expired (within the past 90 days), Paused (within the past 90 days).
Campaign duration7 or more days.
Campaign limitUp to 50 eligible campaigns from the same insertion order (IO) per report.
Audience typeMatched audience created from NPI IDs, Matched audience created from raw data.

Patient Matched audiences are not eligible for PLD Insights reporting.

NLD Insights eligibility requirements​

NLD Insights reports are available for Healthcare campaigns that meet certain requirements.

Read more about these requirements in our Help Center article.

Requirement typeRequirement detailsNotes
Campaign verticalHealthcare.Any campaign created under a Healthcare Advertiser account is a “Healthcare” campaign.
Campaign typeAdvanced.
Campaign statusRunning, Expired (within the past 2 years), Paused.
Campaign durationAt least 7 days through yesterday's date.
Campaign limitUp to 50 eligible campaigns from the same insertion order (IO) per report.
Audience typeCampaign must target at least one Non-NPI Nurse (Matched, Geofarmed, Contextual) audience.

ICT Insights eligibility requirements​

ICT Insights reports are available for Healthcare campaigns that meet certain requirements.

Read more about these requirements in our Help Center article.

Requirement typeRequirement detailsNotes
Campaign verticalHealthcare.Any campaign created under a Healthcare Advertiser account is a “Healthcare” campaign.
Campaign typeAdvanced.
Campaign statusRunning, Expired (within the past 2 years), Paused.
Campaign durationAt least 7 days through yesterday's date.
Campaign limitUp to 50 eligible campaigns from the same insertion order (IO) per report.
Audience typeCampaign must target at least one Integrated Care Team (ICT) input-type (HCP, Nurse) audience.

Get list of templates​

GET

Get a list of all templates for the specified report type with optional filtering and pagination.

A templateId can be used to get Get template details or to update an existing template using the Update report template endpoint.

Query parameters
category
string required		Insights type category: pld, ict, or nld.
searchField
string		Filter templates by name.
noOfEntries
integer		Number of entries per page, default: 20.
pageNo
integer		Page number for pagination, default: 1.
frequencyIds
integer		Filter by scheduling frequency IDs.
statusIds
integer		Filter by template status IDs.
sortBy
string		Sorts by ascending (+) or descending (-), default: -templateId.
Response properties
templateId
integer		Template ID.
name
string		Template name.
frequencyId
integer		Scheduling frequency ID.
startDate
integer		Unix epoch timestamp of template start date, in milliseconds.
endDate
integer		Unix epoch timestamp of template end date, in milliseconds.
timezoneId
integer		Timezone ID.
statusId
integer		Template status ID.
nextRunPreviewUtc
integer		Unix epoch timestamp of the next scheduled run (UTC), in milliseconds.
reportIds
array of integers		Associated report IDs.
campaignIds
array of integers		Associated campaign IDs.
reportStatusSummary
array of objects		Summary of report counts by status ID.
statusSummary
array of objects		Summary of template counts by status ID (top-level).
filteredRecords
integer		Number of records matching the applied filters.
totalRecords
integer		Total number of records.
Response 200
{
  "success": true,
  "data": {
    "data": [
      {
        "templateId": 1,
        "name": "Monthly ICT Report",
        "frequencyId": 2,
        "startDate": 1764843796510,
        "endDate": 1764843796510,
        "timezoneId": 29,
        "statusId": 1,
        "nextRunPreviewUtc": 1764843796510,
        "reportIds": [10001, 10002, 10004],
        "campaignIds": [10001, 10003],
        "reportStatusSummary": [
          {
            "id": 1,
            "count": 5
          },
          {
            "id": 2,
            "count": 2
          }
        ]
      }
    ],
    "statusSummary": [
      {
        "id": 1,
        "count": 5
      },
      {
        "id": 2,
        "count": 5
      }
    ],
    "filteredRecords": 1,
    "totalRecords": 10
  }
}

Get template details​

GET

Get the details of a template by its template ID.

Path parameters
templateId
integer		The ID of the template to retrieve.
Response properties
templateId
integer		Template ID.
name
string		Template name.
campaignIds
array of integers		Associated campaign IDs.
frequencyId
integer		Scheduling frequency ID.
frequencyDetails
object		Scheduling details based on frequency type.
startDate
integer		Unix epoch timestamp of template start date, in milliseconds.
endDate
integer		Unix epoch timestamp of template end date, in milliseconds.
timezoneId
integer		Timezone ID.
aggregationEnabled
boolean		Indicates whether report data is aggregated.
recipientEmails
array of strings		Recipient email addresses.
statusId
integer		Template status ID.
nextRunPreviewUtc
integer		Unix epoch timestamp of the next scheduled run (UTC), in milliseconds.
firstRunLocked
boolean		Indicates whether the first run is locked.
Response 200
{
  "success": true,
  "data": {
    "templateId": 1,
    "name": "Monthly PLD Report",
    "campaignIds": [101, 102, 103],
    "frequencyId": 2,
    "frequencyDetails": {
      "dayOfMonthTypeId": 2,
      "dayOfMonth": 15
    },
    "startDate": 1704067200000,
    "endDate": 1735689599000,
    "timezoneId": 29,
    "aggregationEnabled": true,
    "recipientEmails": [
      "xyz@gmail.com"
    ],
    "statusId": 1,
    "nextRunPreviewUtc": 1706745600000,
    "firstRunLocked": true
  }
}

Get template reports​

GET

Get the reports for a specific template with optional filtering and pagination.

Path parameters
templateId
integer		The ID of the template for which to retrieve reports.
Query parameters
searchField
string		Filter reports by search string.
noOfEntries
integer		Number of entries per page, default: 20.
pageNo
integer		Page number for pagination, default: 1.
sortBy
string		Sorts by ascending (+) or descending (-), default: -reportId.
statusIds
integer		Filter by status IDs.
frequencyIds
integer		Filter by scheduling frequency IDs.
Response properties
reportId
integer		Report ID.
name
string		Report name.
requestedStartDate
integer		Unix epoch timestamp of the report's requested start date, in milliseconds.
requestedEndDate
integer		Unix epoch timestamp of the report's requested end date, in milliseconds.
statusId
integer		Report status ID.
frequencyId
integer		Scheduling frequency ID.
generatedAt
integer		Unix epoch timestamp of when the report was generated, in milliseconds.
filePaths
object		Presigned download URLs for the report files.
fileSizes
object		File sizes in bytes for each format.
totalRecords
integer		Total number of records.
filteredRecords
integer		Number of records matching the applied filters.
statusSummary
array of objects		Summary of report counts by status ID.
frequencySummary
array of objects		Summary of report counts by frequency ID.
Response 200
{
  "success": true,
  "data": {
    "data": [
      {
        "reportId": 180,
        "name": "23897_PLD_Insights_7",
        "requestedEndDate": 1762885799000,
        "requestedStartDate": 1762799400000,
        "statusId": 3,
        "frequencyId": 3,
        "generatedAt": 1764671972077,
        "filePaths": {
          "csvUrl": "https://.../9876.csv",
          "xlsxUrl": "https://.../9876.xlxs",
          "pdfUrl": "https://.../9876.pdf",
          "zipUrl": "https://.../9876.zip"
        },
        "fileSizes": {
          "csvBytes": 27223,
          "xlsxBytes": 98604,
          "pdfBytes": 84259,
          "zipBytes": 20471
        }
      }
    ],
    "totalRecords": 2,
    "filteredRecords": 1,
    "statusSummary": [
      {
        "id": 3,
        "count": 1
      },
      {
        "id": 4,
        "count": 1
      }
    ],
    "frequencySummary": [
      {
        "id": 3,
        "count": 1
      }
    ]
  }
}

Validate template name​

POST

Checks if the given template name is available (not already in use) within the caller's Organization.

Request schema
name
string		Template name to validate (3–100 characters).
category
string		Insights type category: pld, ict, or nld.
Response properties
available
boolean		Indicates whether the template name is available: true or false.
Request sample
{
  "name": "Monthly PLD Report",
  "category": "pld"
}
Response 200 (name available)
{
  "success": true,
  "data": {
    "available": true
  }
}
Response 200 (name not available)
{
  "success": true,
  "data": {
    "available": false
  }
}

Create report template​

POST

Creates a report template with the given campaigns and scheduling configuration.

The request defines a template name, associated campaign IDs, frequency and frequency details (daily, weekly, monthly, or custom), template start/end dates, aggregation flag, recipient emails, template status, and report category.

When the template is ACTIVE, the platform will use the configured schedule to trigger periodic report generation.

Request schema
name
string		Template name (3–100 characters).
campaignIds
array of integers		Campaign IDs (max 50).
frequencyId
integer		Scheduling frequency ID.
frequencyDetails
object		Scheduling details based on frequency type (see examples).
frequencyDetails object properties
dayOfWeekId
integer		Day of week (for weekly/custom-weekly).
dayOfMonthTypeId
integer		Day of month type: first day (1), specific day (2), last day (3).
dayOfMonth
integer		Specific day of month (2–28, when dayOfMonthTypeId = 2).
intervalModeId
integer		Custom interval mode: days (501), weeks (502), months (503).
intervalValue
integer		Custom interval value (e.g., every X days/weeks/months).
startDate
integer		Unix epoch timestamp of template start date, in milliseconds.
endDate
integer		Unix epoch timestamp of template end date, in milliseconds.
aggregationEnabled
boolean		Indicates whether to aggregate report data.
recipientEmails
array of strings		Recipient email addresses (max 15).
status
string		Template status: ACTIVE or INACTIVE.
category
string		Insights type category: pld, ict, or nld.
Response properties
templateId
integer		Created template ID.
nextRunDate
integer		Unix epoch timestamp of the next scheduled run, in milliseconds.
{
  "name": "One-Time Template",
  "campaignIds": [111, 222, 333],
  "frequencyId": 1,
  "frequencyDetails": {},
  "startDate": 1763145600000,
  "endDate": 1765737600000,
  "aggregationEnabled": false,
  "recipientEmails": [
    "a@ws.com"
  ],
  "status": "ACTIVE",
  "category": "pld"
}
{
  "name": "Daily Template",
  "campaignIds": [111, 222],
  "frequencyId": 2,
  "frequencyDetails": {},
  "startDate": 1763145600000,
  "endDate": 1789334400000,
  "aggregationEnabled": true,
  "recipientEmails": [
    "daily@ws.com"
  ],
  "status": "ACTIVE",
  "category": "ict"
}
{
  "name": "Weekly Template",
  "campaignIds": [111, 222, 333],
  "frequencyId": 3,
  "frequencyDetails": {
    "dayOfWeekId": 3
  },
  "startDate": 1763145600000,
  "endDate": 1789334400000,
  "aggregationEnabled": false,
  "recipientEmails": [
    "weekly@ws.com"
  ],
  "status": "ACTIVE",
  "category": "nld"
}
{
  "name": "Monthly Template (1st day)",
  "campaignIds": [111],
  "frequencyId": 4,
  "frequencyDetails": {
    "dayOfMonthTypeId": 1
  },
  "startDate": 1763145600000,
  "endDate": 1789334400000,
  "aggregationEnabled": true,
  "recipientEmails": [
    "m1@ws.com"
  ],
  "status": "ACTIVE",
  "category": "pld"
}
{
  "name": "Monthly Template (15th)",
  "campaignIds": [111, 222],
  "frequencyId": 4,
  "frequencyDetails": {
    "dayOfMonthTypeId": 2,
    "dayOfMonth": 15
  },
  "startDate": 1763145600000,
  "endDate": 1789334400000,
  "aggregationEnabled": false,
  "recipientEmails": [
    "m2@ws.com"
  ],
  "status": "ACTIVE",
  "category": "ict"
}
{
  "name": "Monthly Template (last day)",
  "campaignIds": [111, 222],
  "frequencyId": 4,
  "frequencyDetails": {
    "dayOfMonthTypeId": 3
  },
  "startDate": 1763145600000,
  "endDate": 1789334400000,
  "aggregationEnabled": false,
  "recipientEmails": [
    "m3@ws.com"
  ],
  "status": "ACTIVE",
  "category": "nld"
}
{
  "name": "Custom Every 10 Days Template",
  "campaignIds": [111],
  "frequencyId": 5,
  "frequencyDetails": {
    "intervalModeId": 501,
    "intervalValue": 10
  },
  "startDate": 1763145600000,
  "endDate": 1789334400000,
  "aggregationEnabled": true,
  "recipientEmails": [
    "cdays@ws.com"
  ],
  "status": "ACTIVE",
  "category": "pld"
}
{
  "name": "Custom Every 3 Weeks Template",
  "campaignIds": [111, 222],
  "frequencyId": 5,
  "frequencyDetails": {
    "intervalModeId": 502,
    "intervalValue": 3,
    "dayOfWeekId": 4
  },
  "startDate": 1763145600000,
  "endDate": 1789334400000,
  "aggregationEnabled": false,
  "recipientEmails": [
    "cweeks@ws.com"
  ],
  "status": "ACTIVE",
  "category": "ict"
}
{
  "name": "Custom Every 2 Months – 1st Day Template",
  "campaignIds": [111],
  "frequencyId": 5,
  "frequencyDetails": {
    "intervalModeId": 503,
    "intervalValue": 2,
    "dayOfMonthTypeId": 1
  },
  "startDate": 1763145600000,
  "endDate": 1789334400000,
  "aggregationEnabled": true,
  "recipientEmails": [
    "cm1@ws.com"
  ],
  "status": "ACTIVE",
  "category": "nld"
}
{
  "name": "Custom Every 2 Months – 10th Template",
  "campaignIds": [111],
  "frequencyId": 5,
  "frequencyDetails": {
    "intervalModeId": 503,
    "intervalValue": 2,
    "dayOfMonthTypeId": 2,
    "dayOfMonth": 10
  },
  "startDate": 1763145600000,
  "endDate": 1789334400000,
  "aggregationEnabled": false,
  "recipientEmails": [
    "cm2@ws.com"
  ],
  "status": "ACTIVE",
  "category": "pld"
}
{
  "name": "Custom Every 2 Months – Last Day Template",
  "campaignIds": [111, 222],
  "frequencyId": 5,
  "frequencyDetails": {
    "intervalModeId": 503,
    "intervalValue": 2,
    "dayOfMonthTypeId": 3
  },
  "startDate": 1763145600000,
  "endDate": 1789334400000,
  "aggregationEnabled": true,
  "recipientEmails": [
    "cm3@ws.com"
  ],
  "status": "ACTIVE",
  "category": "ict"
}
Response 200
{
  "success": true,
  "data": {
    "templateId": 101,
    "nextRunDate": 1764460800000
  }
}

Update report template​

PATCH

Apply a partial update to an existing report template. Only the fields present in the request are evaluated and applied.

The platform automatically re-evaluates future executions based on the effective configuration after the update. Past executions and generated reports are never modified.

Important notes
  • Updates only affect future executions
  • A resumed template may not necessarily produce a future run
  • "One Time" templates (frequency ID 1) execute at most once
  • If no future execution exists, nextRunDate will be null
Path parameters
templateId
integer		The ID of the template to update.
Update scenarios
Change madeFuture execution impact
Metadata-only updateNo impact to future executions.
Aggregation flag toggleFuture executions are recalculated.
End date modifiedFuture execution horizon is recalculated.
Start date modifiedFuture execution plan is recalculated.
Recurring → Recurring (frequency change)Future execution pattern changes.
Recurring → One-timeOne-time execution is triggered.
One-time → RecurringFuture recurring executions are scheduled.
ACTIVE → INACTIVEAll future executions are stopped.
INACTIVE → ACTIVE (recurring)Future executions resume.
Multiple changes in one requestStrongest applicable rule applies.

Request schema
name
string		Template name (3–100 characters).
recipientEmails
array of strings		Recipient email addresses.
status
string		Template status: ACTIVE or INACTIVE.
frequencyId
integer		Scheduling frequency ID.
frequencyDetails
object		Scheduling details based on frequency type.
frequencyDetails object properties
dayOfWeekId
integer		Day of week (for weekly/custom-weekly).
dayOfMonthTypeId
integer		Day of month type: first day (1), specific day (2), last day (3).
dayOfMonth
integer		Specific day of month (2–28, when dayOfMonthTypeId = 2).
intervalModeId
integer		Custom interval mode: days (501), weeks (502), months (503).
intervalValue
integer		Custom interval value (e.g., every X days/weeks/months).
startDate
integer		Unix epoch timestamp of template start date, in milliseconds.
endDate
integer		Unix epoch timestamp of template end date, in milliseconds.
aggregationEnabled
boolean		Indicates whether to aggregate report data.

Response properties
templateId
integer		Updated template ID.
nextRunDate
integer		Unix epoch timestamp of the next scheduled run, in milliseconds (may be null if no future execution exists).
{
  "name": "Updated Template Name"
}
{
  "aggregationEnabled": true
}
{
  "endDate": 1790000000000
}
{
  "frequencyId": 3,
  "frequencyDetails": {
    "dayOfWeekId": 2
  }
}
{
  "frequencyId": 1,
  "frequencyDetails": {},
  "startDate": 1763145600000,
  "endDate": 1763145600000
}
{
  "frequencyId": 2,
  "frequencyDetails": {},
  "startDate": 1763145600000
}
{
  "status": "INACTIVE"
}
{
  "status": "ACTIVE"
}
Response 200
{
  "success": true,
  "data": {
    "templateId": 101,
    "nextRunDate": 1764460800000
  }
}

Report management​

Download report​

POST

Download a PLD, NLD, or ICT Insights report. Only reports with a ready status are eligible for download.

This endpoint validates the report status, file type, and user permissions before generating a pre-signed download URL.

Request schema
reportId
integer required		Report ID to download.
fileTypeId
integer required		File type ID: 1 (XLSX), 2 (CSV), 3 (PDF), 4 (ZIP).
Response properties
reportURL
string		Pre-signed download URL for the report.
Request sample
{
  "fileTypeId": 1,
  "reportId": 50
}
Response 200
{
  "success": true,
  "data": {
    "reportURL": "https://xyz.abc.com/reports/abcd/2024-12-03/50_acbd_Report.xlsx?X-Amz-Algorithm=AWS4-HMAC"
  }
}
Response 422 (report not ready)
{
  "success": false,
  "errorObjects": [
    {
      "error": "The provided ICT report ID: 50 is not in the ready state."
    }
  ]
}

Delete report​

DELETE

Delete PLD, NLD, or ICT reports that have a failed status.

Reports that are already deleted or do not have a failed status cannot be deleted with this endpoint.

Query parameters
reportIds
string required		Comma-separated list of report IDs to delete.
Response properties
message
string		Success or error message.
Response 200 (bulk delete)
{
  "success": true,
  "data": {
    "message": "2 ICT insights deleted successfully"
  }
}
Response 200 (individual delete)
{
  "success": true,
  "data": {
    "message": "255944_PLD_Insights_2 deleted successfully"
  }
}
Response 422 (invalid state)
{
  "success": false,
  "errorObjects": [
    {
      "error": "Some of the provided NLD ID(s) are either already deleted, do not exist, or do not have a 'failed' status."
    }
  ]
}

Email report​

POST

Send a PLD, NLD, or ICT Insights report as an email attachment to specified recipients.

Only reports with a ready status are eligible to be emailed. Reports larger than 25 MB cannot be sent.

Request schema
reportId
integer required		Report ID to email.
fileTypeId
integer required		File type ID: 1 (XLSX), 2 (CSV), 3 (PDF), 4 (ZIP).
emailIds
array of strings required		Recipient email addresses (1–15).
Response properties
message
string		Success or error message.
Request sample
{
  "fileTypeId": 1,
  "emailIds": [
    "user1@email.com",
    "user2@email.com"
  ],
  "reportId": 50
}
Response 200
{
  "success": true,
  "data": {
    "message": "ICT report e-mail sent successfully."
  }
}
Response 422 (report not ready)
{
  "success": false,
  "data": {
    "message": "The provided ICT ID: 50 is not in the ready state."
  }
}

Regenerate report​

POST

Regenerate a PLD, NLD, or ICT Insights report that has a failed status.

The report must be associated with a scheduling template. Reports that are already deleted or in a ready/processing state cannot be regenerated.

Path parameters
reportId
integer required		Report ID to regenerate.
Response properties
reportId
integer		Report ID that was regenerated.
templateId
integer		Associated template ID.
nextRunDate
integer		Unix epoch timestamp of the next scheduled run, in milliseconds.
reportName
string		Name of the regenerated report.
Response 200
{
  "success": true,
  "data": {
    "reportId": 12,
    "templateId": 123,
    "nextRunDate": 1765774800000,
    "reportName": "sample report"
  }
}
Response 400 (invalid state)
{
  "success": false,
  "data": {
    "message": "ICT Report ID : 12 is already deleted or is in READY/PROCESSING state."
  }
}
Response 422 (invalid ID)
{
  "success": false,
  "data": {
    "message": "Please provide valid insights id value."
  }
}

Get more Insights reports details​

Get list of Insights types​

GET

Get a list of Insights types by ID.

Insights type IDs
1Audience Insights.
3 Voter Level Data.
4 Provider Level Data.
5 Script Lift Study.
Response 200
{
  "success": true,
  "data": {
    "totalRecords": 2,
    "filteredRecords": 2,
    "insightsTypeData": [
      {
        "id": 1,
        "name": "audiences",
        "label": "Audience Insights",
        "order": 1
      },
      {
        "id": 3,
        "name": "voter_level_data",
        "label": "Voter Level Data",
        "order": 3
      },
      {
        "id": 4,
        "name": "provider_level_data",
        "label": "Provider Level Data",
        "order": 4
      },
      {
        "id": 5,
        "name": "script_life_study",
        "label": "Script Lift Study",
        "order": 5
      }
    ]
  }
}

Get list of Insights status types​

GET

Get a list of Insights status types.

Insights status IDs
1Processing.
2Ready.
3 Failed.
Response 200
{
  "success": true,
  "data": {
    "totalRecords": 3,
    "filterRecords": 3,
    "insightsStatusData": [
      {
        "id": 1,
        "name": "processing",
        "label": "Processing",
        "order": 1
      },
      {
        "id": 2,
        "name": "ready",
        "label": "Ready",
        "order": 2
      },
      {
        "id": 3,
        "name": "failed",
        "label": "Failed",
        "order": 3
      }
    ]
  }
}

Get list of template status types​

GET

Get all possible template statuses with their IDs, names, display names, and display orders.

Template status IDs
1Active.
2Inactive.
Response 200
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "active",
      "displayName": "Active",
      "order": 1
    },
    {
      "id": 2,
      "name": "inactive",
      "displayName": "Inactive",
      "order": 2
    }
  ]
}

Get scheduling frequencies​

GET

Get static metadata for scheduling templates, including frequency types, sub-modes, and shared reference lists (day of week, day of month type).

Frequency type IDs
1One-Time.
2Daily.
3Weekly.
4Monthly.
5Custom.
Response 200
{
  "success": true,
  "data": {
    "frequencyTypes": [
      {
        "id": 1,
        "name": "oneTime",
        "displayName": "One-Time",
        "order": 1,
        "fields": [],
        "modes": null
      },
      {
        "id": 2,
        "name": "daily",
        "displayName": "Daily",
        "order": 2,
        "fields": [],
        "modes": null
      },
      {
        "id": 3,
        "name": "weekly",
        "displayName": "Weekly",
        "order": 3,
        "fields": [
          {
            "id": 301,
            "name": "dayOfWeek",
            "displayName": "Day of Week",
            "order": 1,
            "fieldType": "reference",
            "min": null,
            "max": null,
            "allowedValuesRef": "dayOfWeek"
          }
        ],
        "modes": null
      },
      {
        "id": 4,
        "name": "monthly",
        "displayName": "Monthly",
        "order": 4,
        "fields": [
          {
            "id": 401,
            "name": "dayOfMonthType",
            "displayName": "Day of Month Type",
            "order": 1,
            "fieldType": "reference",
            "min": null,
            "max": null,
            "allowedValuesRef": "dayOfMonthType"
          },
          {
            "id": 402,
            "name": "dayOfMonth",
            "displayName": "Day of Month",
            "order": 2,
            "fieldType": "number",
            "min": 2,
            "max": 28,
            "allowedValuesRef": null
          }
        ],
        "modes": null
      },
      {
        "id": 5,
        "name": "custom",
        "displayName": "Custom",
        "order": 5,
        "fields": null,
        "modes": [
          {
            "id": 501,
            "name": "days",
            "displayName": "Day(s)",
            "order": 1,
            "fields": [
              {
                "id": 50101,
                "name": "intervalValue",
                "displayName": "Repeats In",
                "order": 1,
                "fieldType": "number",
                "min": 1,
                "max": 365,
                "allowedValuesRef": null
              }
            ]
          },
          {
            "id": 502,
            "name": "weeks",
            "displayName": "Week(s)",
            "order": 2,
            "fields": [
              {
                "id": 50201,
                "name": "intervalValue",
                "displayName": "Repeats In",
                "order": 1,
                "fieldType": "number",
                "min": 1,
                "max": 52,
                "allowedValuesRef": null
              },
              {
                "id": 50202,
                "name": "dayOfWeek",
                "displayName": "Day of Week",
                "order": 2,
                "fieldType": "reference",
                "min": null,
                "max": null,
                "allowedValuesRef": "dayOfWeek"
              }
            ]
          },
          {
            "id": 503,
            "name": "months",
            "displayName": "Month(s)",
            "order": 3,
            "fields": [
              {
                "id": 50301,
                "name": "intervalValue",
                "displayName": "Repeats In",
                "order": 1,
                "fieldType": "number",
                "min": 1,
                "max": 12,
                "allowedValuesRef": null
              },
              {
                "id": 50302,
                "name": "dayOfMonthType",
                "displayName": "Day of Month Type",
                "order": 2,
                "fieldType": "reference",
                "min": null,
                "max": null,
                "allowedValuesRef": "dayOfMonthType"
              },
              {
                "id": 50303,
                "name": "dayOfMonth",
                "displayName": "Day of Month",
                "order": 3,
                "fieldType": "number",
                "min": 2,
                "max": 28,
                "allowedValuesRef": null
              }
            ]
          }
        ]
      }
    ],
    "references": {
      "dayOfWeek": [
        {
          "id": 1,
          "name": "monday",
          "displayName": "Monday",
          "order": 1
        },
        {
          "id": 2,
          "name": "tuesday",
          "displayName": "Tuesday",
          "order": 2
        },
        {
          "id": 3,
          "name": "wednesday",
          "displayName": "Wednesday",
          "order": 3
        },
        {
          "id": 4,
          "name": "thursday",
          "displayName": "Thursday",
          "order": 4
        },
        {
          "id": 5,
          "name": "friday",
          "displayName": "Friday",
          "order": 5
        },
        {
          "id": 6,
          "name": "saturday",
          "displayName": "Saturday",
          "order": 6
        },
        {
          "id": 7,
          "name": "sunday",
          "displayName": "Sunday",
          "order": 7
        }
      ],
      "dayOfMonthType": [
        {
          "id": 1,
          "name": "firstDay",
          "displayName": "First Day of Month",
          "order": 1
        },
        {
          "id": 2,
          "name": "nthDay",
          "displayName": "Specific Day (2-28)",
          "order": 2
        },
        {
          "id": 3,
          "name": "lastDay",
          "displayName": "Last Day of Month",
          "order": 3
        }
      ]
    }
  }
}
Have a question?
Ask the community
Was this page helpful?