Insights API

Overview

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

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

Learn more about Insights with our 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 Worskpace ID Header

Get Insights Details

Get a List of Insights

GET /api/v3/ins/insights/list

Get a list of Insights available in the database.

Query Parameters
searchField string	Search results by keyword
pageSize integer	Maximum number of entries per page, default: 20
pageNo integer	Number of pages for retrieved data
sortBy string	Sorts by ascending (+) or descending (-), default: -id

Response Properties

id integer	Insights ID
typeId integer	Insights Type ID
statusId integer	Insights Status ID
name string	Insights name
sourceId integer	Insights source ID
createdAt integer	Unix epoch timestamp of Insights creation date, in milliseconds

JSON

Response 200

{
  "success": true,
  "data": {
    "totalRecords": 1,
    "filterRecords": 1,
    "insightsData": [
      {
        "id": 123,
        "typeId": 1,
        "statusId": 2,
        "name": "demo_insights",
        "sourceId": 123,
        "createdAt": 1687848574780
      }
    ]
  }
}

TypeScript

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;
          insightsData: {
            id: number;
            typeId: number;
            statusId: number;
            name: string;
            sourceId: number;
            createdAt: number
          }
        }
      }
    };
  };
};

function getInsightsDetailList(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/ins/insights/list',
    params: {
      query?: {
        searchField?: `string`,
        pageSize?: `number`,
        pageNo?: `number`,
        sortBy?: `string`,
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Get Campaign Bidding Insights

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

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

info

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

• More than 1 impression captured
• "running", "expired" (within last two weeks), "paused" status
• Must have been active within the last two weeks
• Campaign Type: "advanced"

Path Parameters
campaignId integer	Campaign ID

Query Parameters
dateRangeStart integer	Unix epoch timestamp, in milliseconds
dateRangeEnd integer	Unix epoch timestamp, in milliseconds

Response Properties

rejectionList object	List of bid rejection reasons
rejectionList object properties campaignSettings object Campaign settings ioBudget object IO Budget inventoryTargeting object Inventory targeting campaignBidPrice object Campaign bid price locationTargeting object Location targeting deviceTargeting object Device targeting creativeSettings object Creative settings advanceTargeting object Advanced targeting audienceTargeting object Audience targeting bidStrategy object Bid strategy campaignBudget object Campaign budget demographicsTargeting object Demographics targeting undefined object Undefined rejectionList sub-objects properties title string Object title rejectedBids integer Rejected bids count description string description subReasonInfo object List of sub-reasons info
topMainReasons object	rejectionList objects with the highest rejectedBids counts
topSubReasons object	rejectionList sub-objects with the highest droppedRequests counts
totalBids integer	Total bids count
lostBids integer	Lost bids count
totalWins integer	Total won bids count

Bid rejection descriptions

accountSettings subReasonInfo object properties inactiveAccount Bids dropped off because Advertiser's account with IQM is inactive insufficientBalance Bids dropped off because there is an insufficient balance in your account
creativeSettings subReasonInfo object properties creativeRollPosition Bids dropped off because the roll position (pre-, mid-, post-roll) didn't match the Campaign's required roll position creativePlayerSize Bids dropped off because player size did not match Campaign's required player size creativeDimension Bids dropped off due to the size of Creative creativeUnavailable Bids dropped off due to the Campaign's creative settings, such as creative type, dimensions, duration and others
ioBudget	Bids dropped off because budget on the Campaign's associated IO has spent in full
audienceUnavailable	Bids dropped off because Audience did not match Campaign's Audience targeting parameters
campaignBidPrice	Bids dropped off because the bid price is lower than the floor price recived from the exchange
operatingSystem	Bids dropped off because Operating System did not match the Campaign's Operating System requirements
deviceTargeting subReasonInfo object properties manufacturer Bids dropped off because the Manufacturer did not match the Campaign's Manufacturer parameters deviceType Bids dropped off because the Device Type did not match the Campaign's Device Type targeting parameters channels Bids dropped off because Channels did not match the Campaign's Channel Targeting Parameters networkTypes Bids dropped off because Network Type did not match the Campaign's Network Type requirements carrier Bids dropped off because Carrier did not match the Campaign's Carrier requirements

JSON

Response 200

{
  "success": true,
  "data": {
    "totalRequests": 100,
    "rejectionList": {
      "campaignSettings": {
        "title": "Campaign Settings",
        "rejectedBids": 0,
        "description": "Campaign is filtered due to Campaign Settings set in the campaign.",
        "subReasonInfo": {}
      },
      "ioBudget": {
        "title": "IO Budget",
        "rejectedBids": 0,
        "description": null,
        "subReasonInfo": {}
      },
      "inventoryTargeting": {
        "title": "Inventory Targeting",
        "rejectedBids": 0,
        "description": "Campaign is filtered due to Inventory Targeting.",
        "subReasonInfo": {}
      },
      "campaignBidPrice": {
        "title": "Campaign Bid Price",
        "rejectedBids": 0,
        "description": "Campaign is filtered because the bid price is lower than the floor price received from the exchange.",
        "subReasonInfo": {}
      },
      "locationTargeting": {
        "title": "Location Targeting",
        "rejectedBids": 0,
        "description": "Campaign is filtered due to Location Targeting.",
        "subReasonInfo": {}
      },
      "deviceTargeting": {
        "title": "Device Targeting",
        "rejectedBids": 0,
        "description": "Campaign is filtered due to Device Targeting.",
        "subReasonInfo": {}
      },
      "creativeSettings": {
        "label": "Creative Settings",
        "rejectedBids": 100,
        "description": "Campaign is filtered due to non-matching creative dimensions found in the request",
        "subReasonInfo": {
          "creativeDimension": {
            "label": "Creative Dimensions",
            "droppedRequests": 100,
            "description": "Campaign is filtered due to non-matching creative dimensions found in the request."
          }
        }
      },
      "advanceTargeting": {
        "title": "Advanced Targeting",
        "rejectedBids": 0,
        "description": null,
        "subReasonInfo": {}
      },
      "audienceTargeting": {
        "title": "Audience Targeting",
        "rejectedBids": 0,
        "description": "Campaign is filtered due to Audience Targeting.",
        "subReasonInfo": {}
      },
      "bidStrategy": {
        "title": "Bid Strategy",
        "rejectedBids": 0,
        "description": "Campaign is filtered due to bid strategy setting applied in campaign.",
        "subReasonInfo": {}
      },
      "campaignBudget": {
        "title": "Campaign Budget",
        "rejectedBids": 0,
        "description": "Campaign is filtered because the campaign budget is now unavailable for further bidding.",
        "subReasonInfo": {}
      },
      "demographicsTargeting": {
        "title": "Demographics Targeting",
        "rejectedBids": 0,
        "description": "Campaign is filtered due to Demographics Targeting.",
        "subReasonInfo": {}
      },
      "undefined": {
        "title": "Undefined",
        "rejectedBids": 0,
        "description": "Campaign is filtered due to Undefined reasons.",
        "subReasonInfo": {}
      }
    },
    "topMainReasons": {
      "creativeSettings": 100
    },
    "topSubReasons": {
      "creativeDimension": 100
    },
    "totalBids": 0,
    "lostBids": 0,
    "totalWins": 0
  }
}

Response 422 (invalid start date)

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

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          totalRequests: number;
          rejectionList: {
            campaignSettings: {
              title: string;
              rejectedBids: number;
              description: string;
              subReasonInfo: {}
            };
            ioBudget: {
              title: string;
              rejectedBids: number;
              description: string;
              subReasonInfo: {}
            };
            inventoryTargeting: {
              title: string;
              rejectedBids: number;
              description: string;
              subReasonInfo: {}
            };
            campaignBidPrice: {
              title: string;
              rejectedBids: number;
              description: string;
              subReasonInfo: {}
            };
            locationTargeting: {
              title: string;
              rejectedBids: number;
              description: string;
              subReasonInfo: {}
            };
            deviceTargeting: {
              title: string;
              rejectedBids: number;
              description: string;
              subReasonInfo: {}
            };
            creativeSettings: {
              title: string;
              rejectedBids: number;
              description: string;
              subReasonInfo: {
                creativeDimension: {
                  label: string;
                  droppedRequests: number;
                  description: string;
                }
              }
            };
            advancedTargeting: {
              title: string;
              rejectedBids: number;
              description: string;
              subReasonInfo: {}
            };
            audienceTargeting: {
              title: string;
              rejectedBids: number;
              description: string;
              subReasonInfo: {}
            };
            bidStrategy: {
              title: string;
              rejectedBids: number;
              description: string;
              subReasonInfo: {}
            };
            campaignBudget: {
              title: string;
              rejectedBids: number;
              description: string;
              subReasonInfo: {}
            };
            demographicsTargeting: {
              title: string;
              rejectedBids: number;
              description: string;
              subReasonInfo: {}
            };
            undefined: {
              title: string;
              rejectedBids: number;
              description: string;
              subReasonInfo: {}
            }
          };
          topMainReasons: {
            creativeSettings: number
          };
          topSubReasons: {
            creativeSettings: number
          };
          totalBids: number;
          lostBids: number;
          totalWins: number;
        }
      }
    };
  };
  422: {
    content: {
      "application/json": {
        success: boolean;
        errorObjects: {
          error: string;
        }[]
      }
    };
  };
};

function getCampaignBiddingInsight(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/ins/campaign/bid-insights/{campaignId}',
    params: {
      query: {
        dateRangeStart: `number`,
        dateRangeEnd: `number`,
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Get Insights Count by Type

GET /api/v3/ins/insights/type-wise-count

Get a count of Insights by type ID. See List of Insights Type IDs.

Response Properties

data object

Name-Value pairs of insightsTypeId and count

JSON

Response 200

{
    "success": true,
    "data": {
        "1": 32,
        "3": 20
    }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

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

Insights Management

Delete Insights Record

DELETE /api/v3/ins/insights/delete

Delete records from the database for valid insights IDs passed.

Query Parameters
insightsIds string	Comma separated insights IDs to delete

Response Properties

deletedIds array of integers	Deleted Insights records
invalidIDs array of integers	Invalid IDs

JSON

Response 200

{
  "success": true,
  "data": {
    "deletedIds": [
      35,
      34
    ],
    "invalidIds": [
      33,
      1
    ]
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          deletedIds: number[];
          invalidIds: number[];
        }
      }
    };
  };
};

function deleteInsights(): Promise<Responses> {
  const options = {
    method: 'DELETE',
    url: 'https://app.iqm.com/api/v3/ins/insights/delete',
    params: {
      query: {
        insightsId: `array of numbers`
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Regenerate Insights Report

POST /api/v3/ins/insights/regenerate/{insightsId}

Regenerates an Insights Report if the insight fails.

Path Parameters
insightsIds string	Comma separated Insights IDs to regenerate

JSON

Response 200

{
  "success": true,
  "data": "Insights regenerated successfully."
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function regenerateInsights_1(): Promise<Responses> {
  const options = {
    method: 'DELETE',
    url: 'https://app.iqm.com/api/v3/ins/insights/regenerate/{insightsId}',
    params: {
      path: {
        insightsId: `number`
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Send Insights Email

POST /api/v3/ins/send-email

Send an attached Insights Report file via email.

Query Parameters
id integer	Insights ID
attachmentType string	File type of Report: pdf or xlsx
recipientEmails string	Comma separated string of emails to send Insights Report to, up to 15

Request Schema
file string	Multipart/form-data format

Response Properties

success boolean	Indicates Insights email was succesfully sent: true
data string	Success message

JSON

Request Sample

{
  "file": "string"
}

Response 200

{
  "success": true,
  "data": "Insights-1 pdf email sent successfully."
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function sendInsightsEmail(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ins/send-email',
    params: {
      query: {
        id: `number`,
        attachmentType: `string`,
        recipientEmails: `string`,
      },
    },
    requestBody?: {
      content: {
        "application/json": {
          file?: `string`
        }
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Audience Insights

Get a List of Eligible Audiences

GET /api/v3/ins/audiences/list

Get a list of eligible Audiences which have 10k uniques (minimum).

Query Parameters
searchField string	Search results by keyword
pageSize integer	Maximum number of entries per page, default: 20
pageNo integer	Number of pages for retrieved data
sortBy string	Sorts by ascending (+) or descending (-), default: -id

Response Properties

insightsData object	Insights data details
insightsData object properties id integer Audience ID audienceName string Audience name matchRate integer The percentage of matched records compared to a reference set uniques integer Count of unique Audiences reached

JSON

Response 200

{
  "success": true,
  "data": {
    "totalRecords": 10,
    "filteredRecords": 3,
    "insightsData": [
      {
        "id": 12345,
        "audienceName": "audience1",
        "matchRate": 58.99,
        "uniques": 52432
      },
      {
        "id": 12365,
        "audienceName": "audience2",
        "matchRate": 78.88,
        "uniques": 72786
      },
      {
        "id": 12376,
        "audienceName": "audience3",
        "matchRate": 34.88,
        "uniques": 31122
      }
    ]
  }
}

TypeScript

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;
          insightsData: {
            id: number;
            audienceName: string;
            matchRate: number;
            uniques: number;
          }[]
        }
      }
    };
  };
};

function getInsightsCreateEligibleAudienceList(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/ins/audiences/list',
    params: {
      query?: {
        searchField?: `string`,
        pageSize?: `number`,
        pageNo?: `number`,
        sortBy?: `string`,
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Get Matched Audience Details

GET /api/v3/ins/audience/matched/{audienceId}

Get matched Audience details by Audience ID.

Path Parameters
audienceId integer	Audience ID

Response Properties

matchedAudienceData object	Matched Audience Insights details
matchedAudienceData object properties audienceName string Audience name matchRate integer The percentage of matched records compared to a reference set uniques integer Count of unique Audiences reached createdDate integer Unix epoch timestamp of Audience Insights creation date, in milliseconds fileTotalCount integer Total number of records in the uploaded Audience file dataCost integer Fees charged by the platform if the Audience is used in any Campaign audienceStatusName string Audience status s3FileName string S3 file name

JSON

Response 200

{
  "success": true,
  "data": {
    "matchedAudienceData": {
      "audienceName": "Data Trust NY 4 Cols",
      "matchRate": 90.0,
      "uniques": 90,
      "createdDate": 1728010319,
      "fileTotalCount": 100,
      "dataCost": 2.0,
      "audienceStatusName": "Ready",
      "s3FileName": "1728010319692_DataTrust_NY_4_Cols.csv"
    }
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          matchedAudienceData: {
            audienceName: string;
            matchRate: number;
            uniques: number;
            createdDate: number;
            fileTotalCount: number;
            dataCost: number;
            audienceStatusName: string;
            s3FileName: string;
          }
        }
      }
    };
  };
};

function getMatchedAudienceDetailsByAudienceId(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/ins/audience/matched/{audienceId}',
    params: {
      path: {
        audienceId: `number`
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Get Matched Audience File URL

GET /api/v3/ins/audience/matched/download/{audienceId}

Response Properties

audienceFileUrl string

Matched Audience File URL

JSON

Response 200

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

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function downloadMatchedAudienceFile(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/ins/audience/matched/download/{audienceId}',
    params: {
      path: {
        audienceId: `number`
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Create Audience Insights

POST /api/v3/ins/insights/add

Create an Insights Report for a given Audience ID.

info

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

• Must be Matched Audience type
• Audience status: "ready"
• Audience reach: 10,000+
• (Recommended) Audience creation date within the last year

Request Schema
insightsTypeId integer	Insights Type ID
sourceIds integer	Source IDs

Response Properties

invalidSourceIds array of integers	Invalid source IDs list
insightsData object	Insights data details
insightsData object properties id integer Audience Insights ID typeId integer Insights type ID statusId integer Insights Status ID sourceName string Source name name string Insights name sourceId integer Source ID createdAt integer Unix epoch timestamp of Insights creation date, in milliseconds

JSON

Request Sample

{
  "insightsTypeId": 1,
  "sourceIds": [
    567895,
    925436,
    123677
  ]
}

Response 200

{
  "success": true,
  "data": {
    "invalidSourceIds": [],
    "insightsData": [
      {
        "id": 1213,
        "typeId": 1,
        "statusId": 2,
        "sourceName": "Data Trust NY 4 Cols",
        "name": "Data Trust NY 4 Cols_insights",
        "sourceId": 1099461,
        "createdAt": 1728366883518
      }
    ]
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          invalidSourceIds: number[];
          insightsData: {
            id: number;
            typeId: number;
            statusId: number;
            sourceName: string;
            name: string;
            sourceId: number;
            createdAt: number;
          }[]
        }
      }
    };
  };
};

function createInsightsDetails(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ins/insights/add',
    requestBody: {
      content: {
        "application/json": {
          insightsTypeId?: `number`,
          sourceIds?: `array of numbers`,
          owId?: `number`,
          uowId?: `number`,
        }
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Download Insights Report

POST /api/v3/ins/insights/download

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

Query Parameters
insightsId integer	Insights ID
fileType string	File type of Report: pdf or xlsx

Request Schema
customLogoFile string	Multipart/form-data format

Response Properties

insightsReportUrl string

Insights Report URL

JSON

Request Sample

{
    "customLogoFile": "string"
}

Response 200

{
    "success": true,
    "data": {
        "insightsReportUrl": "https://domain.com/insights.pdf"
    }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function downloadInsights(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ins/insights/download',
    params: {
      query: {
        insightsId: `number`,
        fileType: `string`
      }
    },
    requestBody?: {
      content: {
        "application/json": {
          customLogoFile?: `string`
        }
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Voter Level Data Reports

VLD Resource Properties

Resource Properties

vldId integer	VLD ID
vldName string	VLD name
vldStatus integer	VLD Status Type ID
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
vldCreatedOn integer	Unix epoch timestamp of creation date, in milliseconds
vldStartDate / startDate integer	Unix epoch timestamp of start date, in milliseconds
vldEndDate / endDate integer	Unix epoch timestamp of end date, in milliseconds
campaignId integer	Campaign ID
campaignName string	Campaign name
campaignStatus string	Campaign Status Type
creativeTypeId integer	Creative Type ID
campaignVldTimezoneId integer	Timezone ID
vldReportCreatable boolean	Indicates if VLD Report can be generated for the given Campaign and date range (true)
vldChargeableImps integer	The number of chargeable impressions for the requested VLD Report
vldChargedImps integer	The number of impressions for which the VLD Report is already generated
vldChargeableCost integer	Cost to generate the VLD Report
vldChargedCost integer	Cost of VLD Report that is already generated
fundsAvailable boolean	Indicates if sufficient funds are available in the Advertiser's account to generate the VLD Report (true)
effectiveVldRate integer	Margin rate set by the admin and workspace for generating VLD Report

---

Get List of VLD Reports

GET /api/v3/ins/vld-reports

Get a list of VLD Reports based on search filters.

Query Parameters
searchField string	Search results by keyword
noOfEntries integer	Maximum number of entries per page, default: 200
pageNo integer	Number of pages for retrieved data
sortBy string	Sorts by ascending (+) or descending (-), default: -vldId

JSON

Response 200

{
  "success": true,
  "data": {
    "totalRecords": 10,
    "vldReportDataList": [
      {
        "vldId": 10,
        "vldName": "530667_VLD_Insights_7",
        "campaignName": "prod-campaign-21145",
        "campaignId": 21145,
        "vldStatusId": 3,
        "startDate": 1603152000,
        "endDate": 1603411200,
        "ioId": 5,
        "ioName": "Corporate, Inc.",
        "isCampaignEligible": false,
        "vldCreatedOn": 1721253632,
        "creativeTypeId": 11,
        "campaignVldTimezoneId": 29,
        "ioTypeId": 1
      },
      {
        "vldId": 9,
        "vldName": "530667_VLD_Insights_6",
        "campaignName": "Campaign-4949",
        "campaignId": 4949,
        "vldStatusId": 3,
        "startDate": 1603152000,
        "endDate": 1603411200,
        "ioId": 15,
        "ioName": "Quinton for Mayor",
        "isCampaignEligible": false,
        "vldCreatedOn": 1720325578,
        "creativeTypeId": 14,
        "campaignVldTimezoneId": 29,
        "ioTypeId": 1
      }
    ],
    "filteredRecords": 10
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          totalRecords: number;
          vldReportDataList: {
            vldId: number;
            vldName: string;
            campaignName: string;
            campaignId: number;
            vldStatusId: number;
            startDate: number;
            endDate: number;
            ioId: number;
            ioName: string;
            isCampaignEligible: boolean;
            vldCreatedOn: number;
            creativeTypeId: number;
            campaignVldTimezoneId: number;
            ioTypeId: number;
          }[];
          filteredRecords: number;
        }
      }
    };
  };
};

function getVLDReportList(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/ins/vld-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 VLD Reports

GET /api/v3/ins/vld/campaigns

Get a list of Campaign IDs by status eligible for VLD Report generation.

Response Properties

running array of integers	Campaign IDs with "running" status
paused array of integers	Campaign IDs with "paused" status
expired array of integers	Campaign IDs with "expired" status

JSON

Response 200

{
  "success": true,
  "data": {
    "running": [
      12345,
      12543
    ],
    "paused": [
      54321,
      34521
    ],
    "expired": [
      33452,
      22453
    ]
  }
}

TypeScript

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 getStatusWiseCampaignsForVLDReports(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://app.iqm.com/api/v3/ins/vld/campaigns',
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Generate VLD Report

POST /api/v3/ins/vld-report

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

info

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

• Must be political Campaign
• "running", "expired" (within last two years), "paused" status
• Must have duration of 3 or more days
• Creation date: Sept. 16, 2024 or later
• Voter location: all US states (except Oregon)
• Audience type: Matched Audience

Request Schema
vldStartDate integer	Unix epoch timestamp of start date, in milliseconds
vldEndDate integer	Unix epoch timestamp of end date, in milliseconds
campaignId integer	Campaign ID
vldId integer	Generate Insights Report again for VLD ID

JSON

Request Sample

{
  "campaignId": 12345,
  "vldStartDate": 1722311000,
  "vldEndDate": 1722315000
}

Response 200

{
  "success": true,
  "data": {
    "vldReportCreated": true,
    "campaignId": 1,
    "campaignName": "Campaign Name",
    "campaignStatus": "running",
    "vldStartDate": 1722311000,
    "vldEndDate": 1722315000,
    "vldChargeableImps": 1000,
    "vldChargedImps": 100,
    "vldChargeableCost": 1000,
    "vldChargedCost": 100,
    "fundsAvailable": true
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          vldReportCreated: boolean;
          campaignId: number;
          campaignName: string;
          campaignStatus: string;
          vldStartDate: number;
          vldEndDate: number;
          vldChargeableImps: number;
          vldChargedImps: number;
          vldChargeableCost: number;
          vldChargedCost: number;
          fundsAvailable: boolean
        }
      }
    };
  };
};

function generateVLDReports(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ins/vld-report',
    requestBody: {
      content: {
        "application/json": {
          campaignId?: `number`,
          vldId?: `number`,
          vldStartDate?: `number`,
          vldEndDate?: `number`,
        }
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Get Cost Assessment for VLD Report

POST /api/v3/ins/vld-reports/computation

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

Request Schema
campaignId integer	Campaign ID
vldStartDate integer	Unix epoch timestamp of start date, in milliseconds
vldEndDate integer	Unix epoch timestamp of end date, in milliseconds

JSON

Request Sample

{
  "campaignId": 1,
  "vldStartDate": 1722311000,
  "vldEndDate": 1722315000
}

Response 200

{
  "success": true,
  "data": {
    "vldReportCreated": true,
    "campaignId": 1,
    "campaignName": "Campaign Name",
    "campaignStatus": "running",
    "vldStartDate": 1722311000,
    "vldEndDate": 1722315000,
    "vldChargeableImps": 1000,
    "vldChargedImps": 100,
    "vldChargeableCost": 1000,
    "vldChargedCost": 100,
    "fundsAvailable": true
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          vldReportCreated: boolean;
          campaignId: number;
          campaignName: string;
          campaignStatus: string;
          vldStartDate: number;
          vldEndDate: number;
          vldChargeableImps: number;
          vldChargedImps: number;
          vldChargeableCost: number;
          vldChargedCost: number;
          fundsAvailable: boolean
        }
      }
    };
  };
};

function getChargeableImpressionsDataForVLDReports(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ins/vld-reports/computation',
    requestBody: {
      content: {
        "application/json": {
          campaignId?: `number`,
          vldId?: `number`,
          vldStartDate?: `number`,
          vldEndDate?: `number`,
        }
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Download VLD Insight Report

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

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

Request Schema
fileTypeId integer	File type ID XLSX: 1 CSV: 2
vldId integer	VLD ID

Response Properties

vldReportUrl string

VLD Report File URL

JSON

Response 200

{
  "success": true,
  "data": {
    "vldReportUrl": "https://tem.domain.s3.amazonaws.com/vld-campaigns/ds/2024-08-20/503481_Insights_1.xlsx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240820T112818Z&X-Amz-"
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function getVLDReportDownloadUrl(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://app.iqm.com/api/v3/ins/vld-reports/download',
    requestBody: {
      content: {
        "application/json": {
          fileTypeId?: `number`,
          vldId?: `number`,
        }
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Delete VLD Report

DELETE /api/v3/ins/vld-report

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

Query Parameters
vldId integer	VLD ID

Response Properties

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

JSON

Response 200

{
  "success": true,
  "data": {
    "message": "255944_VLD_Insights_2 deleted successfully"
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function deleteFailedVLDReport(): Promise<Responses> {
  const options = {
    method: 'DELETE',
    url: 'https://app.iqm.com/api/v3/ins/vld-report',
    params: {
      query: {
        vldIds: `string`
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

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 /api/v3/ins/pld-reports

Get a list of PLD Reports.

Query Parameters
searchField string	Search results by keyword
noOfEntries integer	Maximum number of entries per page, default: 200
pageNo integer	Number of pages for retrieved data, default: 1
sortBy string	Sorts by ascending (+) or descending (-), default: -pldId

See PLD Resource Properties for response property descriptions.

JSON

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

TypeScript

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://app.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 /api/v3/ins/pld-reports/campaigns

Get a list of Campaign IDs by status eligible for PLD Report generation.

Response Properties

running array of integers	Campaign IDs with "running" status
paused array of integers	Campaign IDs with "paused" status
expired array of integers	Campaign IDs with "expired" status

See PLD Resource Properties for response property descriptions.

JSON

Response 200

{
  "success": true,
  "data": {
    "running": [
      12345,
      12543
    ],
    "paused": [
      54321,
      34521
    ],
    "expired": [
      33452,
      22453
    ]
  }
}

TypeScript

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://app.iqm.com/api/v3/ins/pld-reports/campaigns',
  };

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

---

Generate PLD Report

POST /api/v3/ins/pld-report

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

See PLD Resource Properties for response property descriptions.

JSON

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

TypeScript

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://app.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 /api/v3/ins/pld-reports/columns

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

Response 200

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

TypeScript

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://app.iqm.com/api/v3/ins/pld-reports/columns',
  };

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

---

Update PLD Reports Columns

POST /api/v3/ins/pld-reports/columns

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

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

TypeScript

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://app.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 /api/v3/ins/pld-report/download

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

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

TypeScript

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://app.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 /api/v3/ins/pld-reports

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

Response 200

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

TypeScript

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://app.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 /api/v3/ins/sls-reports

Get a list of SLS Reports.

Query Parameters
searchField string	Search results by keyword
noOfEntries integer	Maximum number of entries per page, default: 200
pageNo integer	Number of pages for retrieved data
sortBy string	Sorts by ascending (+) or descending (-), default: -slsId

JSON

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

TypeScript

See TypeScript Prerequisites for usage.

Generate SLS Report

POST /api/v3/ins/sls-reports

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

JSON

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

TypeScript

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://app.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 /api/v3/ins/sls-reports/computation

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

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

TypeScript

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://app.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 /api/v3/ins/sls-reports/validate/name

Validate a name for SLS Reports.

Query Parameters
reportName string	Report name

Response Properties

success boolean	Indicates successful validation
data string	Success message

JSON

Response 200

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

TypeScript

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://app.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 /api/v3/ins/sls-reports/campaigns

Get a list of Campaign IDs by status eligible for VLD Report generation.

Response Properties

running array of integers	Campaign IDs with "running" status
paused array of integers	Campaign IDs with "paused" status
expired array of integers	Campaign IDs with "expired" status

JSON

Response 200

{
  "success": true,
  "data": {
    "running": [
      12345,
      12543
    ],
    "paused": [
      54321,
      34521
    ],
    "expired": [
      33452,
      22453
    ]
  }
}

TypeScript

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://app.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 /api/v3/ins/sls-reports/download

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	Practitioner Level Data Report ID

Response Properties

slsReportUrl string

SLS Report File URL

JSON

Request Sample

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

TypeScript

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://app.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 /api/v3/ins/sls-reports

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 IDs

Response Properties

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

JSON

Response 200

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

TypeScript

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://app.iqm.com/api/v3/ins/sls-reports',
    params: {
      query: {
        slsIds: `string`,
      }
    }
  };

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

Get More Insights Details

Get List of Insights Types

GET /api/v3/ins/static/insights/type/list

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

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

TypeScript

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://app.iqm.com/api/v3/ins/static/insights/type/list',
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Get List of Insights Status

GET /api/v3/ins/static/insights/status/list

Get a list of Insights status types.

Insights Status IDs
1	Processing
2	Ready
3	Failed

JSON

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

TypeScript

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://app.iqm.com/api/v3/ins/static/insights/status/list',
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}