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 Provider Level Data Reports and ScriptLift Studies Reports.

Type	Description	Notes
Audience Quality Score (AQS)	AQS Reports leverage third-party healthcare data from PurpleLab to confirm Audience exposure based on patient-level targeting criteria including prescriptions, diagnoses, and procedures.
ScriptLift Studies (SLS)	SLS Reports include key details about prescribing behaviors and how they are influenced by current and previous healthcare Campaigns.
Provider Level Data (PLD)	PLD Reports include details about healthcare professionals targeted in your Campaigns, and provide similar details as VLD Reports while adhering to healthcare data privacy regulations.	PLD, NLD, and ICT reports are handled by the Report Templates endpoints with the `category` parameter.
Nurse Level Data (NLD)	NLD 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)	ICT 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 PLD, SLS, and AQS 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

Create an Insights Report Tutorial
Reporting and Analytics Help Center articles
Audience Quality Insights Reports Help Center articles
Script Lift Study (SLS) Insights Reports Help Center articles
Provider Level Data (PLD) Insights Reports Help Center articles
Nurse Level Data (NLD) Insights Reports Help Center articles
Integrated Care Team (ICT) Insights Reports Help Center articles

Authentication

Use the following header parameters for all requests:

Headers
`Authentication` string required	Authentication bearer token See Authentication Guide
`X-IAA-OW-ID` integer required	Organization Workspace ID Header

Insights Details

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 to 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

JSON
TypeScript

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

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          running: {
            campaignId: number;
            campaignTimezoneId: number;
          }[];
          paused: {
            campaignId: number;
            campaignTimezoneId: number;
          }[];
          expired: {
            campaignId: number;
            campaignTimezoneId: number;
          }[];
        }
      }
    };
  };
}

function getEligibleCampaigns(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/ins/insights/eligible-campaigns',
    params: {
      query: {
        reportType: `string`,
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

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.

Request Schema
`category` string required	Insight 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

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	Number of already charged impressions
`chargeableCost` number	Chargeable cost amount
`chargedCost` number	Already charged cost amount
`fundsAvailable` boolean	Indicates whether sufficient funds are available
`effectiveRate` number	Effective rate for the report
`templateId` integer	Associated Template ID

JSON
TypeScript

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

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          ioId: number;
          ioName: string;
          startDate: number;
          endDate: number;
          campaignIds: number[];
          reportCreatable: boolean;
          chargeableImps: number;
          chargedImps: number;
          chargeableCost: number;
          chargedCost: number;
          fundsAvailable: boolean;
          effectiveRate: number;
          templateId: number;
        }
      }
    };
  };
}

function computeInsightsReports(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/ins/insights/computation',
    requestBody: {
      content: {
        "application/json": {
          category: `string`,
          campaignIds: `number[]`,
          startDate: `number`,
          endDate: `number`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Audience Quality Score Reports

AQS Eligibility Requirements

AQS Reports are available for Campaigns that meet certain requirements.

Read more about these requirements in our Help Center article.

Requirement Type	Requirement Details	Notes
Campaign vertical	Healthcare	Any Campaign created under a healthcare advertiser account is a “Healthcare” campaign.
Audience type	Matched (Patient), Segmented (Patient)
Audience status	Ready
Campaign type	Advanced, and targeting at least one patient Audience
Campaign status	Running, Expired (within the past two years), Paused
Campaign impressions	1K or more impressions
Campaign duration	14 or more days

AQS Resource Properties

Resource Properties

`reportId` integer	AQS Report ID
`reportName` string	AQS Report name
`campaignId` integer	Campaign ID
`campaignName` string	Campaign name
`statusId` integer	AQS Status Type ID
`statusName` string	AQS Status name
`startDate` integer	Unix epoch timestamp of start date, in seconds
`endDate` integer	Unix epoch timestamp of end date, in seconds
`ioId` integer	Insertion Order ID
`ioName` string	Insertion Order name
`ioBudgetType` integer	Insertion Order Budget Type ID
`isCampaignEligible` boolean	Indicates that Campaign is eligible for AQS Report: `true`
`reportCreatedOn` integer	Unix epoch timestamp of creation date, in seconds
`creativeTypeId` integer	Creative Type ID
`campaignTimeZoneId` integer	Timezone ID
`fileSizeDetails` object	Object containing file sizes by type ID (1: XLSX, 2: CSV)
`aqsReportCreatable` boolean	Indicates if AQS Report can be generated for the given Campaign and date range (`true`)
`aqsChargeableImps` integer	The number of chargeable impressions for the requested AQS Report
`aqsChargedImps` integer	The number of impressions for which the AQS Report is already generated
`aqsChargeableCost` number	Cost to generate the AQS Report
`aqsChargedCost` number	Cost of AQS Report that is already generated
`fundsAvailable` boolean	Indicates if sufficient funds are available in the Advertiser's account to generate the AQS Report (`true`)
`effectiveAqsRate` number	The effective rate applied for AQS Report generation

Get List of AQS Reports

GET

Get a paginated list of Audience Quality Score (AQS) Reports with detailed information.

A reportId can be used in the Download AQS Report and Delete AQS 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": 1603152000,
        "endDate": 1603411200,
        "ioId": 5,
        "ioName": "Corporate, Inc.",
        "isCampaignEligible": false,
        "reportCreatedOn": 1721253632,
        "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": 1603152000,
        "endDate": 1603411200,
        "ioId": 15,
        "ioName": "Quinton for Mayor",
        "isCampaignEligible": false,
        "reportCreatedOn": 1720325578,
        "creativeTypeId": 14,
        "ioBudgetType": 1,
        "campaignTimeZoneId": 29,
        "fileSizeDetails": {
          "1": 1024,
          "2": 1024
        }
      }
    ],
    "filteredRecords": 10
  }
}

Get List of Campaigns Eligible for AQS Reports

GET

Get a status-wise list of Campaign IDs eligible for AQS 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 AQS Report Name

GET

Validate the report name for generation of AQS 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 AQS Report Cost

POST

Compute the cost and impressions for AQS Report generation based on the campaign and date range.

Request Schema
`campaignId` integer	Campaign ID
`aqsId` integer	AQS Report ID (for regeneration)
`aqsName` string	AQS Report name
`aqsStartDate` integer	Unix epoch timestamp of start date, in seconds
`aqsEndDate` integer	Unix epoch timestamp of end date, in seconds
`aqsReportTypeId` integer	AQS Report Type ID
`aqsAudienceConceptGroups` array of objects	Array of audience/concept group mappings

Request Sample
{
  "campaignId": 1,
  "aqsStartDate": 1722311000,
  "aqsEndDate": 1722315000,
  "aqsName": "Dummy AQS Name",
  "aqsReportTypeId": 1,
  "aqsAudienceConceptGroups": {
    "audienceId": 101,
    "conceptGroupId": "202335"
  }
}

Response 200
{
  "success": true,
  "data": {
    "aqsReportCreated": true,
    "campaignId": 1,
    "aqsStartDate": 1722311000,
    "aqsEndDate": 1722315000,
    "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": {
    "aqsReportCreated": false,
    "aqsId": 1,
    "aqsName": "AQS report 1",
    "aqsStatusId": 1,
    "aqsCreatedOn": 1722315234,
    "campaignId": 1,
    "ioId": 1,
    "ioName": "Insertion Order Name",
    "ioTypeId": 1,
    "aqsReportTypeId": 1,
    "aqsAudienceConceptGroups": {
      "audienceId": 101,
      "conceptGroupId": "202335"
    }
  }
}

Response 200 (processing)
{
  "success": true,
  "data": {
    "aqsReportCreated": false,
    "message": "AQS Insights can't be generated for this campaigns at the moment as another insight with overlapping date range is processing"
  }
}

Generate AQS Report

POST

Generate an Audience Quality Score (AQS) Report. This API calculates the cost for the impressions based on the impressions and mark up charged on the Organization and then creates the AQS Reports.

Request Schema
`campaignId` integer	Campaign ID
`aqsId` integer	AQS Report ID to regenerate
`aqsName` string	AQS Report name
`aqsStartDate` integer	Unix epoch timestamp of start date, in seconds
`aqsEndDate` integer	Unix epoch timestamp of end date, in seconds
`aqsReportTypeId` integer	AQS Report Type ID
`aqsAudienceConceptGroups` array of objects	Array of audience/concept group mappings

Request Sample (new report)
{
  "campaignId": 1,
  "aqsStartDate": 1722311000,
  "aqsEndDate": 1722315000,
  "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": {
    "aqsReportCreated": false,
    "aqsId": 1,
    "aqsName": "AQS report 1",
    "aqsStatusId": 1,
    "aqsCreatedOn": 1722315234,
    "campaignId": 1,
    "ioId": 1,
    "ioName": "Insertion Order Name",
    "ioTypeId": 1,
    "aqsReportTypeId": 1,
    "aqsAudienceConceptGroups": {
      "audienceId": 101,
      "conceptGroupId": "202335"
    }
  }
}

Response 200 (failure)
{
  "success": true,
  "data": {
    "aqsReportCreated": false,
    "message": "AQS Insights can't be generated for this campaigns at the moment as another insight with overlapping date range is processing"
  }
}

Get AQS Report Types

GET

Get available AQS Report types. Returns a list of report types that can be generated. Only users from Advertiser organizations are authorized to access this API.

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 AQS Report

POST

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

Request Schema
`fileTypeId` integer	File type ID XLSX: `1` CSV: `2`
`reportId` integer	AQS Report ID

Response Properties

reportUrl
string AQS 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."
    }
  ]
}

Delete AQS Report

DELETE

Delete AQS Reports that are not marked as deleted and have a 'failed' status. Requires user authorization and checks if the provided AQS IDs are valid.

Query Parameters
`reportIds` string	Comma-separated AQS 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"
  }
}

ScriptLift Studies Reports

SLS Eligiblity Requirements

SLS reports are available for healthcare Campaigns that meet certain requirements.

Read more about these requirements in our Help Center article.

Requirement Type	Requirement Details	Notes
Campaign vertical	Healthcare	Any Campaign created under a healthcare advertiser account is a “Healthcare” campaign.
Campaign status	Running, Expired (within the past two years), Paused
Campaign impressions	>1 impression
Campaign duration	7 or more days
Campaign start date	[Release date], 2025 or later (or earlier upon request from IQM's support team)
Audience type	Matched 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 Resource Properties

Resource Properties

`slsId` integer	SLS ID
`slsName` string	SLS name
`campaignIds` array of integers	Campaign IDs
`slsStatusId` integer	SLS 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
`isCampaignEligible` boolean	Indicates that Campaign is eligible for SLS 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 Report
`slsChargedImps` integer	The number of impressions for which the SLS Report is already generated
`slsChargeableCost` integer	Cost to generate the SLS Report
`slsChargedCost` integer	Cost of SLS Report that is already generated
`pdfFileSize` integer	PDF file size in bytes
`excelFileSize` integer	Excel file size in bytes
`slsReportTypeIds` array of integers	SLS Report type IDs

Get List of SLS Reports

GET

Get a list of SLS Reports.

An slsId can be used in the Generate SLS Report, Download SLS Report, and Delete SLS 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`

JSON
TypeScript

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

See TypeScript Prerequisites for usage.

Generate SLS Report

POST

This API calculates the cost for the impressions for the ScriptLift Studies Reports based on the impressions and mark up charged on the Organization and then creates the SLS Reports.

SLS 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
`slsLookbackDuration` integer	SLS lookback duration
`conceptGroupId` integer	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 integers	Competitor concept group IDs
`slsId` integer	SLS ID to regenerate

JSON
TypeScript

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

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          slsReportCreated: number;
          campaignIds: number[];
          slsStartDate: number;
          slsEndDate: number;
          slsChargeableImps: number;
          slsChargedImps: number;
          slsChargeableCost: number;
          slsChargedCost: number;
          slsName: string;
          slsLookbackDuration: number;
          conceptGroupId: number;
          reportTypes: number[];
          competitorConceptGroupIds: number[];
          fundsAvailable: boolean;
        }
      }
    };
  };
}

function generateSLSReports(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/ins/sls-reports',
    requestBody: {
      content: {
        "application/json": {
          ioId?: `number`,
          campaignIds?: `array of numbers`,
          slsId?: `number`,
          slsStartDate?: `number`,
          slsEndDate?: `number`,
          slsName?: `string`,
          slsLookbackDuration?: `number`,
          conceptGroupId?: `number`,
          competitorConceptGroupIds?: `array of numbers`,
          reportTypes?: `array of numbers`,
          endDate?: `number`,
          startDate?: `number`,
          id?: `number`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

SLS Reports Computation

POST

Calculates the cost for the impressions for the SLS Report based on impressions and the mark up charged on the Organization.

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
`slsLookbackDuration` integer	SLS lookback duration
`conceptGroupId` integer	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 integers	Competitor concept group IDs

JSON
TypeScript

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

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          slsReportCreated: number;
          campaignIds: number[];
          slsStartDate: number;
          slsEndDate: number;
          slsChargeableImps: number;
          slsChargedImps: number;
          slsChargeableCost: number;
          slsChargedCost: number;
          slsName: string;
          slsLookbackDuration: number;
          conceptGroupId: number;
          reportTypes: number[];
          competitorConceptGroupIds: number[];
          fundsAvailable: boolean;
        }
      }
    };
  };
}

function getChargeableImpressionsDataForSLSReports(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/ins/sls-reports/computation',
    requestBody: {
      content: {
        "application/json": {
          ioId?: `number`,
          campaignIds?: `array of numbers`,
          slsId?: `number`,
          slsStartDate?: `number`,
          slsEndDate?: `number`,
          slsName?: `string`,
          slsLookbackDuration?: `number`,
          conceptGroupId?: `number`,
          competitorConceptGroupIds?: `array of numbers`,
          reportTypes?: `array of numbers`,
          endDate?: `number`,
          startDate?: `number`,
          id?: `number`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Validate SLS Report Name

GET

Validate a name for SLS Reports.

Query Parameters
`reportName` string	Report name

Response Properties

`success` boolean	Indicates successful validation
`data` string	Success message

JSON
TypeScript

Response 200
{
  "success": true,
  "data": "This SLS report name is valid"
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: string;
      }
    };
  };
}

function validateSlsReportName(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/ins/sls-reports/validate/name',
    params: {
      query: {
        reportName: `string`
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Get List of Campaigns Eligible for SLS Reports

GET

Get a list of Campaign IDs by status eligible for VLD 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

JSON
TypeScript

Response 200
{
  "success": true,
  "data": {
    "running": [
      {
        "campaignId": 516038,
        "campaignTimezoneId": 29
      }
    ],
    "paused": [
      {
        "campaignId": 523630,
        "campaignTimezoneId": 29
      }
    ],
    "expired": [
      {
        "campaignId": 500291,
        "campaignTimezoneId": 29
      }
    ]
  }
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          running: number[];
          paused: number[];
          expired: number[];
        }
      }
    };
  };
}

function getStatusWiseCampaignsForSLSReports(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/ins/sls-reports/campaigns',
    params: {
      query: {
        reportName: `string`
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Download SLS Report

POST

Get a download link for a SLS Insight Report in CSV or XLSX format.

Request Schema
`fileType` integer	File type ID XLSX: `1` CSV: `2`
`slsId` integer	SLS Report ID

Response Properties

slsReportUrl
string SLS Report File URL

JSON
TypeScript

Request Sample
{
  "fileType": 1,
  "slsId": 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."
    }
  ]
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          pldReportUrl: string;
        }
      }
    };
  };
}

function getSLSReportDownloadUrl(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/ins/sls-reports/download',
    requestBody: {
      content: {
        "application/json": {
          fileTypeId?: `number`,
          slsId?: `number`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Delete SLS Report

DELETE

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

Query Parameters
`slsIds` string	Comma separated SLS Report IDs

Response Properties

`success` boolean	Indicates Report was succesfully deleted: `true`
`message` string	Success message

JSON
TypeScript

Response 200
{
  "success": true,
  "data": {
    "message": "255944_PLD_Insights_2 deleted successfully"
  }
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          message: string;
        }
      }
    };
  };
}

function deleteFailedSLSReport(): Promise<Responses> {
  const options = {
    method: 'DELETE',
    url: 'https://api.iqm.com/api/v3/ins/sls-reports',
    params: {
      query: {
        slsIds: `string`,
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Report Templates

PLD 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 Type	Requirement Details	Notes
Campaign vertical	Healthcare	Any Campaign created under a healthcare advertiser account is a “Healthcare” campaign.
Campaign status	Running, Expired (within the past 90 days), Paused (within the past 90 days)
Campaign duration	7 or more days
Campaign limit	Up to 50 eligible Campaigns from the same insertion order (IO) per report
Audience type	Matched Audience created from NPI IDs, Matched Audience created from raw data Patient Matched Audiences are not eligible for PLD Insights reporting

NLD 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 Type	Requirement Details	Notes
Campaign vertical	Healthcare	Any Campaign created under a healthcare advertiser account is a “Healthcare” campaign.
Campaign type	Advanced
Campaign status	Running, Expired (within the past 2 years), Paused
Campaign duration	At least 7 days through yesterday's date
Campaign limit	Up to 50 eligible Campaigns from the same insertion order (IO) per report
Audience type	Campaign must target at least one Non-NPI Nurse (Matched, Geofarmed, Contextual) Audience

ICT 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 Type	Requirement Details	Notes
Campaign vertical	Healthcare	Any Campaign created under a healthcare advertiser account is a “Healthcare” campaign.
Campaign type	Advanced
Campaign status	Running, Expired (within the past 2 years), Paused
Campaign duration	At least 7 days through yesterday's date
Campaign limit	Up to 50 eligible Campaigns from the same insertion order (IO) per report
Audience type	Campaign 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	Insight 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

JSON
TypeScript

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

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          data: {
            templateId: number;
            name: string;
            frequencyId: number;
            startDate: number;
            endDate: number;
            timezoneId: number;
            statusId: number;
            nextRunPreviewUtc: number;
            reportIds: number[];
            campaignIds: number[];
            reportStatusSummary: {
              id: number;
              count: number;
            }[];
          }[];
          statusSummary: {
            id: number;
            count: number;
          }[];
          filteredRecords: number;
          totalRecords: number;
        }
      }
    }
  };
}

function getAllTemplates(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/ins/templates',
    params: {
      query: {
        category: `string`,
        searchField?: `string`,
        pageNo?: `number`,
        noOfEntries?: `number`,
        frequencyIds?: `number`,
        statusIds?: `number`,
        sortBy?: `string`,
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

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

JSON
TypeScript

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

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          templateId: number;
          name: string;
          campaignIds: number[];
          frequencyId: number;
          frequencyDetails: {
            dayOfWeekId?: number;
            dayOfMonthTypeId?: number;
            dayOfMonth?: number;
            intervalModeId?: number;
            intervalValue?: number;
          };
          startDate: number;
          endDate: number;
          timezoneId: number;
          aggregationEnabled: boolean;
          recipientEmails: string[];
          statusId: number;
          nextRunPreviewUtc: number;
          firstRunLocked: boolean;
        }
      }
    }
  };
}

function getTemplateById(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/ins/templates/{templateId}',
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

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

JSON
TypeScript

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

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          data: {
            reportId: number;
            name: string;
            requestedStartDate: number;
            requestedEndDate: number;
            statusId: number;
            frequencyId: number;
            generatedAt: number;
            filePaths: {
              csvUrl: string;
              xlsxUrl: string;
              pdfUrl: string;
              zipUrl: string;
            };
            fileSizes: {
              csvBytes: number;
              xlsxBytes: number;
              pdfBytes: number;
              zipBytes: number;
            };
          }[];
          totalRecords: number;
          filteredRecords: number;
          statusSummary: {
            id: number;
            count: number;
          }[];
          frequencySummary: {
            id: number;
            count: number;
          }[];
        }
      }
    }
  };
}

function getReportsForTemplate(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/ins/templates/{templateId}/report',
    params: {
      query: {
        searchField?: `string`,
        pageNo?: `number`,
        noOfEntries?: `number`,
        sortBy?: `string`,
        statusIds?: `number`,
        frequencyIds?: `number`,
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

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	Insight type category: `pld`, `ict`, or `nld`

Response Properties

available
boolean Indicates whether the template name is available: true or false

JSON
TypeScript

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

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          available: boolean;
        }
      }
    };
  };
}

function validateTemplateName(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/ins/templates/validate-name',
    requestBody: {
      content: {
        "application/json": {
          name: `string`,
          category: `string`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

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 Insight 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

JSON
TypeScript

{
  "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"
}

Response 200
{
  "success": true,
  "data": {
    "templateId": 101,
    "nextRunDate": 1764460800000
  }
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          templateId: number;
          nextRunDate: number;
        }
      }
    };
  };
}

function createTemplate(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/ins/templates',
    requestBody: {
      content: {
        "application/json": {
          name: `string`,
          campaignIds: `number[]`,
          frequencyId: `number`,
          frequencyDetails: {
            dayOfWeekId?: `number`,
            dayOfMonthTypeId?: `number`,
            dayOfMonth?: `number`,
            intervalModeId?: `number`,
            intervalValue?: `number`,
          },
          startDate: `number`,
          endDate?: `number`,
          aggregationEnabled: `boolean`,
          recipientEmails?: `string[]`,
          status: `string`,
          category: `string`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

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 Made	Future Execution Impact
Metadata-only update	No impact to future executions
Aggregation flag toggle	Future executions are recalculated
End date modified	Future execution horizon is recalculated
Start date modified	Future execution plan is recalculated
Recurring → Recurring (frequency change)	Future execution pattern changes
Recurring → One-time	One-time execution is triggered
One-time → Recurring	Future recurring executions are scheduled
ACTIVE → INACTIVE	All future executions are stopped
INACTIVE → ACTIVE (recurring)	Future executions resume
Multiple changes in one request	Strongest 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)

JSON
TypeScript

{
  "name": "Updated Template Name"
}

Response 200
{
  "success": true,
  "data": {
    "templateId": 101,
    "nextRunDate": 1764460800000
  }
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          templateId: number;
          nextRunDate: number;
        }
      }
    };
  };
}

function updateTemplate(): Promise<Responses> {
  const options = {
    method: 'PATCH',
    url: 'https://api.iqm.com/api/v3/ins/templates/{templateId}',
    requestBody: {
      content: {
        "application/json": {
          name?: `string`,
          recipientEmails?: `string[]`,
          status?: `string`,
          frequencyId?: `number`,
          frequencyDetails?: {
            dayOfWeekId?: `number`,
            dayOfMonthTypeId?: `number`,
            dayOfMonth?: `number`,
            intervalModeId?: `number`,
            intervalValue?: `number`,
          },
          startDate?: `number`,
          endDate?: `number`,
          aggregationEnabled?: `boolean`,
        }
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Report Management

Download Report

POST

Download a PLD, NLD, or ICT Insights report. Only reports with a ready status are eligible for download. The API 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

JSON
TypeScript

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

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      success: boolean;
      data: {
        reportUrl: string;
      };
    };
  };
  422: {
    content: {
      success: boolean;
      errorObjects: Array<{ error: string }>;
    };
  };
};

function downloadReport(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/ins/report/download',
    data: {
      fileTypeId: 1,
      reportId: 50
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

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

JSON
TypeScript

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

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      success: boolean;
      data: {
        message: string;
      };
    };
  };
  422: {
    content: {
      success: boolean;
      errorObjects: Array<{ error: string }>;
    };
  };
};

function deleteReport(): Promise<Responses> {
  const options = {
    method: 'DELETE',
    url: 'https://api.iqm.com/api/v3/ins/report',
    params: {
      reportIds: '50,51'
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

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

JSON
TypeScript

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."
  }
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      success: boolean;
      data: {
        message: string;
      };
    };
  };
  422: {
    content: {
      success: boolean;
      data: {
        message: string;
      };
    };
  };
};

function emailReport(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/ins/report/email',
    data: {
      fileTypeId: 1,
      emailIds: ['user1@email.com'],
      reportId: 50
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

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

JSON
TypeScript

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."
  }
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      success: boolean;
      data: {
        reportId: number;
        templateId: number;
        nextRunDate: number;
        reportName: string;
      };
    };
  };
  400: {
    content: {
      success: boolean;
      data: {
        message: string;
      };
    };
  };
};

function regenerateReport(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/ins/regenerate/report/{reportId}',
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Get More Insights Details

Get List of Insights Types

GET

Get a list of Insights types by ID.

Payment Term IDs
`1`	Audience Insights
`3`	Voter Level Data
`4`	Provider Level Data
`5`	Script Lift Study

JSON
TypeScript

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

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          totalRecords: number;
          filteredRecords: number;
          insightsTypeData: {
            id: number;
            name: string;
            label: string;
            order: number;
          }[]
        }
      }
    };
  };
};

function getInsightsType(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/ins/static/insights/type/list',
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Get List of Insights Status

GET

Get a list of Insights status types.

Insights Status IDs
`1`	Processing
`2`	Ready
`3`	Failed

JSON
TypeScript

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

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          totalRecords: number;
          filterRecords: number;
          insightsStatusData: {
            id: number;
            name: string;
            label: string;
            order: number;
          }[]
        }
      }
    };
  };
};

function getInsightsStatus(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/ins/static/insights/status/list',
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Get List of Template Statuses

GET

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

Template Status IDs
`1`	Active
`2`	Inactive

JSON
TypeScript

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

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          id: number;
          name: string;
          displayName: string;
          order: number;
        }[]
      }
    };
  };
}

function getTemplateStatuses(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/ins/static/template-status',
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

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
`1`	One-Time
`2`	Daily
`3`	Weekly
`4`	Monthly
`5`	Custom

JSON
TypeScript

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

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface FrequencyField {
  id: number;
  name: string;
  displayName: string;
  order: number;
  fieldType: string;
  min: number | null;
  max: number | null;
  allowedValuesRef: string | null;
}

interface FrequencyMode {
  id: number;
  name: string;
  displayName: string;
  order: number;
  fields: FrequencyField[];
}

interface FrequencyType {
  id: number;
  name: string;
  displayName: string;
  order: number;
  fields: FrequencyField[] | null;
  modes: FrequencyMode[] | null;
}

interface ReferenceItem {
  id: number;
  name: string;
  displayName: string;
  order: number;
}

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          frequencyTypes: FrequencyType[];
          references: {
            [key: string]: ReferenceItem[];
          }
        }
      }
    };
  };
}

function getFrequencyMetadata(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/ins/static/scheduling/frequencies',
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Have a question?

Ask the Community

Was this page helpful?

More Resources​

Authentication​

Insights Details​

Get Eligible Campaigns​

Calculate Insights Computation​

Audience Quality Score Reports​

AQS Eligibility Requirements​

AQS Resource Properties​

Get List of AQS Reports​

Get List of Campaigns Eligible for AQS Reports​

Validate AQS Report Name​

Compute AQS Report Cost​

Generate AQS Report​

Get AQS Report Types​

Download AQS Report​

Delete AQS Report​

ScriptLift Studies Reports​

SLS Eligiblity Requirements​

SLS Resource Properties​

Get List of SLS Reports​

Generate SLS Report​

SLS Reports Computation​

Validate SLS Report Name​

Get List of Campaigns Eligible for SLS Reports​

Download SLS Report​

Delete SLS Report​

Report Templates​

PLD Eligibility Requirements​

NLD Eligibility Requirements​

ICT Eligibility Requirements​

Get List of Templates​

Get Template Details​

Get Template Reports​

Validate Template Name​

Create Report Template​

Update Report Template​

Report Management​

Download Report​

Delete Report​

Email Report​

Regenerate Report​

Get More Insights Details​

Get List of Insights Types​

Get List of Insights Status​

Get List of Template Statuses​

Get Scheduling Frequencies​

More Resources

Authentication

Insights Details

Get Eligible Campaigns

Calculate Insights Computation

Audience Quality Score Reports

AQS Eligibility Requirements

AQS Resource Properties

Get List of AQS Reports

Get List of Campaigns Eligible for AQS Reports

Validate AQS Report Name

Compute AQS Report Cost

Generate AQS Report

Get AQS Report Types

Download AQS Report

Delete AQS Report

ScriptLift Studies Reports

SLS Eligiblity Requirements

SLS Resource Properties

Get List of SLS Reports

Generate SLS Report

SLS Reports Computation

Validate SLS Report Name

Get List of Campaigns Eligible for SLS Reports

Download SLS Report

Delete SLS Report

Report Templates

PLD Eligibility Requirements

NLD Eligibility Requirements

ICT Eligibility Requirements

Get List of Templates

Get Template Details

Get Template Reports

Validate Template Name

Create Report Template

Update Report Template

Report Management

Download Report

Delete Report

Email Report

Regenerate Report

Get More Insights Details

Get List of Insights Types

Get List of Insights Status

Get List of Template Statuses

Get Scheduling Frequencies