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 Power Segment Insights Reports and Voter Level Data Reports.

Power Segment Insights (PSI) Reports offer audience Insights for pre-defined political personality segments, such as office-holders, candidates, and other public figures.

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

Power Segment Insights

info

Power Segment Insights (PSI) is available to political vertical Advertisers only. All PSI endpoints return a 403 for non-political Organizations.

Generate PSI Report

POST

Initiates report generation for a power segment identified by its taxonomyId. The request is forwarded to the data team after validating the segment's current report status.

Only segments with a status of NotRequested or Failed can be triggered.

See Get Power Segment Insights List.

Request Schema
taxonomyId string	Taxonomy ID of the power segment

Response Properties

message string

Success message

JSON

Request Sample

{
  "taxonomyId": "IQMADV0002606"
}

Response 200

{
  "success": true,
  "data": {
    "message": "Report generation initiated successfully."
  }
}

Response 422 (report already in progress or ready)

{
  "success": false,
  "errorObjects": [
    {
      "error": "Report generation cannot be initiated. Current report status is: Processing"
    }
  ]
}

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 generatePsiReport(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/ins/psi/generate-report',
    requestBody: {
      content: {
        "application/json": {
          taxonomyId: `string`,
        }
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Get Power Segment Insights List

GET

Get a list of power segments and their available reports, based on search, sorting, and pagination criteria.

Query Parameters
searchField string	Search power segments by name
sortBy string	Sorts by ascending (+) or descending (-), allowed values: id, name, category
pageNo integer	Page number of retrieved data
noOfEntries integer	Number of entries returned per page, default: 20
categories array of strings	Filter power segments by category name, e.g. CABINET_MEMBERS

Response Properties

totalRecords integer	Total number of power segments
filteredRecords integer	Number of power segments matching the search/filter criteria
powerSegmentsReports array of objects	Power segments matching the search/filter criteria
object properties id integer Power Segment ID name string Power Segment name category string Power Segment category reports array of objects Reports available for this power segment object properties type string Report type status string Report status: NotRequested, Processing, Ready, or Failed generationTime number Estimated report generation time, in minutes sizeInBytes integer Report file size, in bytes taxonomyId string Taxonomy ID used to generate, download, or email this report

JSON

Response 200

{
  "success": true,
  "data": {
    "totalRecords": 2,
    "filteredRecords": 2,
    "powerSegmentsReports": [
      {
        "id": 1,
        "name": "Donald Trump",
        "category": "Neptune",
        "reports": [
          {
            "type": "SPHERE",
            "status": "NotRequested",
            "generationTime": 3.0,
            "sizeInBytes": null,
            "taxonomyId": "283230NNJW"
          },
          {
            "type": "ORBIT",
            "status": "NotRequested",
            "generationTime": 3.0,
            "sizeInBytes": null,
            "taxonomyId": "56329JJSH67"
          }
        ]
      },
      {
        "id": 2,
        "name": "Hillary Clinton",
        "category": null,
        "reports": [
          {
            "type": "SPHERE",
            "status": "NotRequested",
            "generationTime": 3.0,
            "sizeInBytes": null,
            "taxonomyId": "HHKNW972JL"
          }
        ]
      }
    ]
  }
}

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;
          powerSegmentsReports: {
            id: number;
            name: string;
            category: string | null;
            reports: {
              type: string;
              status: string;
              generationTime: number;
              sizeInBytes: number | null;
              taxonomyId: string;
            }[];
          }[];
        }
      }
    };
  };
};

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

---

Download PSI Report

GET

Get a presigned S3 URL for downloading the PSI Report PDF for the given taxonomyId. The report must be in Ready status.

Query Parameters
taxonomyId string required	Taxonomy ID of the power segment

Response Properties

reportURL string

Presigned URL for downloading the PSI Report PDF

JSON

Response 200

{
  "success": true,
  "data": {
    "reportURL": "https://s3.amazonaws.com/..."
  }
}

Response 422 (report not ready)

{
  "success": false,
  "errorObjects": [
    {
      "error": "Report is not ready for download."
    }
  ]
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function downloadPsiReport(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/ins/psi/download-report',
    params: {
      query: {
        taxonomyId: `string`,
      },
    },
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Email PSI Report

POST

Sends the PSI Report PDF for the given taxonomyId to the specified email addresses. If the file is 10 MB or smaller the PDF is attached directly; otherwise the email includes a download link only. The report must be in Ready status.

Query Parameters
taxonomyId string required	Taxonomy ID of the power segment

Request Schema
emailIds array of strings	Email addresses to send the report to, 1-15 addresses, each 1-320 characters

Response Properties

message string

Success message

JSON

Request Sample

{
  "emailIds": ["jane.doe@example.com"]
}

Response 200

{
  "success": true,
  "data": {
    "message": "Report email sent successfully."
  }
}

Response 422 (report not ready)

{
  "success": false,
  "errorObjects": [
    {
      "error": "Report is not ready for download."
    }
  ]
}

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 emailPsiReport(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/ins/psi/email',
    params: {
      query: {
        taxonomyId: `string`,
      },
    },
    requestBody: {
      content: {
        "application/json": {
          emailIds: `string[]`,
        }
      }
    }
  };
  
  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

---

Get Power Segment Insights Category Types

GET

Get all Power Segment Insights category types with their names, display names, and display orders.

Use name as the value for the categories filter on Get Power Segment Insights List.

JSON

Response 200

{
  "success": true,
  "data": [
    { "id": 1, "name": "CABINET_MEMBERS", "displayName": "Cabinet Members", "order": 10 },
    { "id": 2, "name": "GOVERNOR", "displayName": "Governor", "order": 20 },
    { "id": 3, "name": "HOUSE_OF_REPRESENTATIVE", "displayName": "House of Representative", "order": 30 },
    { "id": 4, "name": "SENATOR", "displayName": "Senator", "order": 40 },
    { "id": 5, "name": "MAYOR", "displayName": "Mayor", "order": 50 }
  ]
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

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

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

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