Insights API

Overview

Audience insights provide in-depth Reports of audience characteristics, interests, and behaviors to give advertisers a deeper understanding of their 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. This section covers the methods and endpoints for managing VLD Reports.

This page covers the various methods and endpoints for insights details and management, as well as Voter Level Data Reports details and management.

Learn more about Audience and VLD 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`

JSON
TypeScript

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

See TypeScript Prerequisites page 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}

Gets the data required for bidding insights of Campaign by Campaign ID in a given date range (2 weeks maximum), along with the rejection reasons and rejection bids per reason. Also gets total wins during the date range.

Path Parameters
`campaignId` integer	Campaign ID

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

JSON
TypeScript

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

See TypeScript Prerequisites page 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 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`

JSON
TypeScript

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

See TypeScript Prerequisites page 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 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.

JSON
TypeScript

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

See TypeScript Prerequisites page 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);
}

Get Matched Audience Details

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

Get matched audience details by audience ID.

Path Parameters
`audienceId` integer	Audience ID

JSON
TypeScript

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

See TypeScript Prerequisites page 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}

JSON
TypeScript

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

See TypeScript Prerequisites page 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);
}

Insights Management

Create Insights for a Given Audience

POST /api/v3/ins/insights/add

Create an insight Report for a given audience ID.

Request Schema
`insightsTypeId` integer	Insights Type ID
`sourceIds` integer	Source IDs

JSON
TypeScript

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

See TypeScript Prerequisites page 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);
}

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

JSON
TypeScript

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

See TypeScript Prerequisites page 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
TypeScript

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

See TypeScript Prerequisites page 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);
}

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

JSON
TypeScript

Request Sample
{
    "customLogoFile": "string"
}

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

See TypeScript Prerequisites page 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);
}

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

JSON
TypeScript

Request Sample
{
  "file": "string"
}

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

See TypeScript Prerequisites page 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);
}

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 type ID
`vldCreatedOn` integer	Unix epoch timestamp of creation date, in milliseconds
`vldStartDate` integer	Unix epoch timestamp of start date, in milliseconds
`vldEndDate` 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
`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
TypeScript

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

See TypeScript Prerequisites page 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.

JSON
TypeScript

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

See TypeScript Prerequisites page 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 with the following endpoint:

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

JSON
TypeScript

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

See TypeScript Prerequisites page 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 with the following endpoint:

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
TypeScript

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

See TypeScript Prerequisites page 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

JSON
TypeScript

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

See TypeScript Prerequisites page 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. Use the following endpoint:

Query Parameters
`vldId` integer	VLD ID

JSON
TypeScript

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

See TypeScript Prerequisites page 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);
}

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

JSON
TypeScript

Response 200
{
  "success": true,
  "data": {
    "totalRecords": 2,
    "filteredRecords": 2,
    "insightsTypeData": [
      {
        "id": 1,
        "name": "audiences",
        "label": "Audience Insights",
        "order": 1
      },
      {
        "id": 3,
        "name": "voter_level_data",
        "label": "Voter Level Data",
        "order": 3
      }
    ]
  }
}

See TypeScript Prerequisites page 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
TypeScript

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

See TypeScript Prerequisites page 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);
}

Overview​

Authentication​

Get Insights Details​

Get a List of Insights​

Get Campaign Bidding Insights​

Get a List of Eligible Audiences​

Get Insights Count by Type​

Get Matched Audience Details​

Get Matched Audience File URL​

Insights Management​

Create Insights for a Given Audience​

Delete Insights Record​

Regenerate Insights Report​

Download Insights Report​

Send Insights Email​

Voter Level Data Reports​

VLD Resource Properties​

Get List of VLD Reports​

Get List of Campaigns Eligible for VLD Reports​

Generate VLD Report​

Get Cost Assessment for VLD Report​

Download VLD Insight Report​

Delete VLD Report​

Get More Insights Details​

Get List of Insights Types​

Get List of Insights Status​

Overview

Authentication

Get Insights Details

Get a List of Insights

Get Campaign Bidding Insights

Get a List of Eligible Audiences

Get Insights Count by Type

Get Matched Audience Details

Get Matched Audience File URL

Insights Management

Create Insights for a Given Audience

Delete Insights Record

Regenerate Insights Report

Download Insights Report

Send Insights Email

Voter Level Data Reports

VLD Resource Properties

Get List of VLD Reports

Get List of Campaigns Eligible for VLD Reports

Generate VLD Report

Get Cost Assessment for VLD Report

Download VLD Insight Report

Delete VLD Report

Get More Insights Details

Get List of Insights Types

Get List of Insights Status