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.

Provider Level Data (PLD) Reports include details about healthcare professionals targeted in your Campaigns, and provide similar details as VLD Reports while adhering to healthcare data privacy regulations.
ScriptLift Studies (SLS) Reports include key details about prescribing behaviors and how they are influenced by current and previous healthcare Campaigns.
Audience Quality Score (AQS) Reports leverage third-party healthcare data from PurpleLab to confirm Audience exposure based on patient-level targeting criteria including prescriptions, diagnoses, and procedures.

More Resources

Reporting and Analytics Help Center article
Insights API Guidelines

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

Provider Level Data Reports

PLD Resource Properties

Resource Properties

`pldId` integer	PLD ID
`pldName` string	PLD name
`campaignId` integer	Campaign ID
`campaignName` string	Campaign name
`pldStatusId` integer	PLD 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 VLD Report: `true`
`pldCreatedOn` integer	Unix epoch timestamp of creation date, in milliseconds
`creativeTypeId` integer	Creative Type ID
`campaignPldTimezoneId` integer	Timezone ID
`pldReportCreatable` boolean	Indicates if PLD Report can be generated for the given Campaign and date range (`true`)
`pldChargeableImps` integer	The number of chargeable impressions for the requested PLD Report
`pldChargedImps` integer	The number of impressions for which the PLD Report is already generated
`pldChargeableCost` integer	Cost to generate the PLD Report
`pldChargedCost` integer	Cost of PLD Report that is already generated
`fundsAvailable` boolean	Indicates if sufficient funds are available in the Advertiser's account to generate the PLD Report (`true`)

Get List of PLD Reports

GET

Get a list of PLD Reports.

A pldId can be used in the Generate PLD Report, Download PLD Insight Report, and Delete PLD 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: `-pldId`

JSON
TypeScript

Response 200
{
  "success": true,
  "data": {
    "totalRecords": 10,
    "pldReportDataList": [
      {
        "pldId": 10,
        "pldName": "530667_PLD_Insights_7",
        "campaignName": "prod-campaign-21145",
        "campaignId": 21145,
        "pldStatusId": 3,
        "startDate": 1732165200000,
        "endDate": 1732424399000,
        "ioId": 5,
        "ioName": "Corporate, Inc.",
        "isCampaignEligible": false,
        "pldCreatedOn": 1721253632,
        "creativeTypeId": 11,
        "campaignPldTimezoneId": 29,
        "ioTypeId": 1
      },
      {
        "pldId": 9,
        "pldName": "530667_PLD_Insights_6",
        "campaignName": "Campaign-4949",
        "campaignId": 4949,
        "pldStatusId": 3,
        "startDate": 1732165200000,
        "endDate": 1732424399000,
        "ioId": 15,
        "ioName": "Quinton for Mayor",
        "isCampaignEligible": false,
        "pldCreatedOn": 1720325578,
        "creativeTypeId": 14,
        "campaignPldTimezoneId": 29,
        "ioTypeId": 1
      }
    ],
    "filteredRecords": 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: {
          totalRecords: number;
          filteredRecords: number;
          pldReportDataList: {
            pldId: number;
            pldName: string;
            campaignName: string;
            campaignId: number;
            pldStatusId: number;
            startDate: number;
            endDate: number;
            ioId: number;
            ioName: string;
            isCampaignEligible: boolean;
            pldCreatedOn: number;
            creativeTypeId: number;
            campaignPldTimezoneId: number;
            ioTypeId: number;
          }[];
        }
      }
    }
  };
}

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

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

Get List of Campaigns Eligible for PLD Reports

GET

Get a list of Campaign IDs by status eligible for PLD 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": 451351,
        "campaignTimezoneId": 29
      }
    ],
    "paused": [
      {
        "campaignId": 451350,
        "campaignTimezoneId": 29
      }
    ],
    "expired": [
      {
        "campaignId": 470839,
        "campaignTimezoneId": 29
      }
    ]
  }
}

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: {
          running: number[];
          paused: number[];
          expired: number[];
        }
      }
    }
  };
}

function getStatusWiseCampaignsForPLDReports(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/ins/pld-reports/campaigns',
  };

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

Generate PLD Report

POST

This API calculates the cost for the impressions for the Provider Level Data Reports based on the impressions and mark up charged on the Organization and then creates the PLD Reports.

info

A Campaign must meet the following eligibility criteria to generate PLD Report:

Must be healthcare Campaign
"running", "expired" (within last 90 days), "paused" (within last 90 days) status
Must have duration of 3 or more days
Audience type: Matched Audience from NPI IDs

Request Schema
`pldStartDate` integer	Unix epoch timestamp of start date, in milliseconds
`pldEndDate` integer	Unix epoch timestamp of end date, in milliseconds
`campaignId` integer	Campaign ID
`pldId` integer	PLD ID to regenerate

JSON
TypeScript

Request Sample
{
  "campaignId": 12345,
  "pldStartDate": 1722311000,
  "pldEndDate": 1722315000
}

Response 200
{
  "success": true,
  "data": {
    "pldReportCreated": true,
    "campaignId": 1,
    "campaignName": "Campaign Name",
    "campaignStatus": "running",
    "pldStartDate": 1722311000,
    "pldEndDate": 1722315000,
    "pldChargeableImps": 1000,
    "pldChargedImps": 100,
    "pldChargeableCost": 1000,
    "pldChargedCost": 100,
    "fundsAvailable": true
  }
}

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

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          pldReportCreated: boolean;
          campaignId: number;
          campaignName: string;
          campaignStatus: string;
          pldStartDate: number;
          pldEndDate: number;
          pldChargeableImps: number;
          pldChargedImps: number;
          pldChargeableCost: number;
          pldChargedCost: number;
          fundsAvailable: boolean
        }
      }
    };
  };
}

function generatePLDReports(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/ins/pld-report',
    requestBody: {
      content: {
        "application/json": {
          campaignId?: `number`,
          pldId?: `number`,
          pldStartDate?: `number`,
          pldEndDate?: `number`,
          endDate?: `number`,
          startDate?: `number`,
          id?: `number`,
        }
      }
    }
  };

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

Get PLD Reports Columns

GET

Get columns details for PLD Reports.

The response properties for this endpoint include names of each possible column paired with a boolean value indicating whether it is included in the report (true) or not (false).

JSON
TypeScript

Response 200
{
  "success": true,
  "data": {
    "id": true,
    "insightsName": true,
    "campaignName": true,
    "campaignId": true,
    "status": true,
    "dateRange": true,
    "createdOn": true,
    "ioName": true,
    "ioId": false
  }
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          id: boolean;
          insightsName: boolean;
          campaignName: boolean;
          campaignId: boolean;
          status: boolean;
          dateRange: boolean;
          createdOn: boolean;
          ioName: boolean;
          ioId: boolean;
        }
      }
    };
  };
}

function fetchPLDReportSelectedColumns(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/ins/pld-reports/columns',
  };

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

Update PLD Reports Columns

POST

Save or update the selection of columns shown in PLD Reports.

The request schema and response properties for this endpoint include names of each possible column paired with a boolean value indicating whether it is included in the report (true) or not (false).

JSON
TypeScript

Request Sample
{
  "id": true,
  "insightsName": true,
  "campaignName": true,
  "campaignId": true,
  "status": true,
  "dateRange": true,
  "createdOn": true,
  "ioName": true,
  "ioId": false
}

Response 200
{
  "success": true,
  "data": {
    "id": true,
    "insightsName": true,
    "campaignName": true,
    "campaignId": true,
    "status": true,
    "dateRange": true,
    "createdOn": true,
    "ioName": true,
    "ioId": false
  }
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          id: boolean;
          insightsName: boolean;
          campaignName: boolean;
          campaignId: boolean;
          status: boolean;
          dateRange: boolean;
          createdOn: boolean;
          ioName: boolean;
          ioId: boolean;
        }
      }
    };
  };
}

function saveOrUpdatePLDReportSelectedColumns(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/ins/pld-reports/columns',
    requestBody: {
      content: {
        "application/json": {
            id: `boolean`,
            insightsName: `boolean`,
            campaignName: `boolean`,
            campaignId: `boolean`,
            status: `boolean`,
            dateRange: `boolean`,
            createdOn: `boolean`,
            ioName: `boolean`,
            ioId: `boolean`,
        }
      }
    }
  };

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

Download PLD Report

POST

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

Request Schema
`fileType` integer	File type ID XLSX: `1` CSV: `2`
`pldId` integer	Provider Level Data Report ID

Response Properties

pldReportUrl
string PLD Report File URL

JSON
TypeScript

Request Sample
{
  "fileType": 1,
  "pldId": 50
}

Response 200
{
  "success": true,
  "data": {
    "pldReportUrl": "https://dowload.domain.com/pld-reports/20220101/pld-report-1.xlsx"
  }
}

More Responses

Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Invalid sortBy value."
    }
  ]
}

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

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

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

Delete PLD Report

DELETE

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

Query Parameters
`pldIds` string	Comma separated PLD 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 deleteFailedPLDReport(): Promise<Responses> {
  const options = {
    method: 'DELETE',
    url: 'https://api.iqm.com/api/v3/ins/pld-reports',
    params: {
      query: {
        pldIds: `string`,
      }
    }
  };

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

ScriptLift Studies Reports

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.

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
`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
`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);
}

Audience Quality Score Reports

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

Have a question?

Ask the Community

Was this page helpful?

More Resources​

Authentication​

Provider Level Data Reports​

PLD Resource Properties​

Get List of PLD Reports​

Get List of Campaigns Eligible for PLD Reports​

Generate PLD Report​

Get PLD Reports Columns​

Update PLD Reports Columns​

Download PLD Report​

Delete PLD Report​

ScriptLift Studies Reports​

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​

Audience Quality Score Reports​

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​

More Resources

Authentication

Provider Level Data Reports

PLD Resource Properties

Get List of PLD Reports

Get List of Campaigns Eligible for PLD Reports

Generate PLD Report

Get PLD Reports Columns

Update PLD Reports Columns

Download PLD Report

Delete PLD Report

ScriptLift Studies Reports

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

Audience Quality Score Reports

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