Insights API

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

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.

NOTE

Some Insights reports will need to be enabled by an administrator to access. By default VLD reports are not accessible to advertiser users.

You can check an advertiser's access to Insights reports with the Get Customer Config Details endpoint.

More Resources

• Reporting and Analytics Help Center articles
• Voter Level Data (VLD) Insights Reports Help Center articles
• Insights API Guidelines

Authentication

Use the following header parameters for all requests:

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

Voter Level Data Reports

VLD Eligibility Requirements

VLD reports are available for Campaigns that meet certain requirements.

Read more about these requirements in our Help Center article.

Requirement Type	Requirement Details	Notes
Campaign vertical	Political	Any Campaign created under a political advertiser account is a “Political” campaign.
Campaign status	Running, Expired (within the past two years), Paused
Campaign duration	3 or more days
Campaign creation date	September 16, 2024 or later (or earlier upon request to IQM's support team)
Voter location	All US states except Oregon	Due to privacy laws in the state of Oregon, we are unable to generate the VLD Insights Report on any voters located there. Contact your account representative for more detailed information on the legality of reidentifying voters at the user level.
Audience type	Matched audience created from L2 IDs, Matched audience created from raw data	Your campaign must only include the audience types listed in this requirements table. For example, you cannot generate a VLD report for a campaign if it includes a Matched Audience created from L2 IDs and a Retargeted Audience consisting of your website’s past visitors. The VLD report supports audiences you create using First Name, Last Name, Address, and Phone Number. IQM anonymizes the data in the matching process, encrypts the files, and stores them behind a firewall to protect them against information leaks.

VLD 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

Get a list of VLD Reports based on search filters.

A vldId can be used in the Generate VLD Report, Download VLD Insight Report, and Delete VLD Report endpoints.

Query Parameters
searchField string	Filter results by search field
noOfEntries integer	Number of entries returned per page, default: 200
pageNo integer	Page number of retrieved data
sortBy string	Sorts by ascending (+) or descending (-), default: -vldId

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://api.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

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

Response Properties

running, paused, expired array of objects	Object array of Campaign IDs mapped to each of these three Campaign statuses
object properties campaignId integer Campaign ID campaignTimezoneId integer Campaign timezone ID

JSON

Response 200

{
  "success": true,
  "data": {
    "running": [
      {
        "campaignId": 451351,
        "campaignTimezoneId": 29
      }
    ],
    "paused": [
      {
        "campaignId": 451350,
        "campaignTimezoneId": 29
      }
    ],
    "expired": [
      {
        "campaignId": 470839,
        "campaignTimezoneId": 29
      }
    ]
  }
}

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

---

Generate VLD Report

POST

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://api.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

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://api.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

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://api.iqm.com/api/v3/ins/vld-report/download',
    requestBody: {
      content: {
        "application/json": {
          fileTypeId?: `number`,
          vldId?: `number`,
        }
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Delete VLD Report

DELETE

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://api.iqm.com/api/v3/ins/vld-report',
    params: {
      query: {
        vldIds: `string`
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}