Planner API

The Planner API allows you to draft an ad strategy proposal that meets an Advertiser's requirements while also achieving campaign goals.

Planner proposals offer insight summaries for reach and impression parameters that can then be applied to campaigns to pre-optimize their success. The Planner API can also apply audience and targeting details to a campaign.

Once a proposal is drafted, the Planner API can generate an insertion order and campaign while also validating the proposal details.

This page covers the common endpoints and methods associated with the Planner API.

More resources

• Planner proposal overview Help Center articles
• Healthcare Professional (HCP) Planner guidelines
• Political Planner guidelines
• Healthcare Professional (HCP) Planner tutorial
• Political Planner tutorial

Authentication

Use the following header parameters for all requests:

Headers
Authentication string required	Authentication bearer token. See Sign up and authenticate.
X-IAA-OW-ID integer required	Organization Workspace ID header.

Proposal details

Get proposal details by ID

GET

Get proposal details by ID.

Path parameters
proposalId integer	Proposal ID.

Response properties

id string	Proposal ID.
name string	Proposal name.
startTime integer	Unix epoch timestamp (in milliseconds) of start time.
endTime integer	Unix epoch timestamp (in milliseconds) of end time.
status integer	Status ID. +Supported values 1 Converted 2 Draft 3 Expired 4 Failed 5 Processing 6 Ready 7 IO Created
targetedReach integer	Targeted reach.
targetedImpressions integer	Targeted impressions.
maxTargetedReach integer	Max targeted reach.
maxTargetedImpressions integer	Max targeted impressions.
budget integer	Budget.
maxBudget integer	Max budget.
proposedCampaigns object	Proposed campaigns list.
proposedCampaigns object properties id string Campaign ID. name string Campaign name. startTime integer Unix epoch timestamp (in milliseconds) of start time. endTime integer Unix epoch timestamp (in milliseconds) of end time. strategy string Strategy. creativeTypeId integer Creative type ID. +Supported values 0 All 11 Image 13 HTML 14 Video 15 Native 17 Audio duration integer Campaign duration. modelType string Model type. targetedReach integer Targeted reach. targetedImpressions integer Targeted impressions. maxTargetedReach integer Max targeted reach. maxTargetedImpressions integer Max targeted impressions. frequencyCap integer Frequency cap. cpm integer Cost per mille. minCpm integer Minimum CPM. maxCpm integer Maximum CPM. budget integer Budget. maxBudget integer Max budget.
margin integer	Margin percentage applied on top of base CPM, not a currency amount (range: 0-100).
location object	Location data.
location object properties country array of integers Country ID. states array of integers States ID. dma array of integers DMA ID. city array of integers City ID. county array of integers County ID. congressionalDistricts array of integers Congressional district ID. stateHouse array of integers State house ID. stateSenate array of integers State senate ID. zipCodes string Comma separated zip code IDs. isAdvanceTargeted boolean When true, indicates that a new campaign must be created for advanced audience and inventory targeting. locationAdvanceTargeted array of integers When true, indicates that a new campaign must be created for advanced location targeting.
audience object	Audience data.
audience object properties audienceSegmentIds array of integers Audience segment ID. isAdvanceTargeted boolean When true, indicates that a new campaign must be created for advanced audience and inventory targeting.
creative object	Creative data.
creative object properties creativeTypeIds array of integers Creative type ID. +Supported values 0 All 11 Image 13 HTML 14 Video 15 Native 17 Audio isTvAutoBuying boolean If true, indicates video creative is eligible for TV advertising.
inventory object	Inventory data.
inventory object properties openExchangeInventory object Open Exchange inventory data. openExchangeInventory object properties iabCategories array of integers IAB category ID. exchanges array of integers Exchange ID. inventoryGroupIds array of integers Inventory group ID. isAdvanceTargeted boolean When true, indicates that a new campaign must be created for advanced audience and inventory targeting.
device object	Device data.
device object properties deviceTypesTargetedIds array of integers Targeted device type IDs. +Supported values 20300001 Mobile 20300002 Desktop 20300003 Connected TV 20300004 Tablet 20399999 Unknown channelTypesTargetedIds array of integers Targeted channel type IDs. +Supported values 21100001 App 21100002 OTT App 21100003 Web isAdvanceTargeted boolean When true, indicates that a new campaign must be created for advanced audience and inventory targeting. deviceTypesAdvanceTargetedIds array of integers When true, indicates that a new campaign must be created for advanced device targeting.

JSON

Response 200 (Draft proposal)

{
    "success": true,
    "data":
    {
        "id": 14,
        "name": "sample",
        "startTime": 1730658720000,
        "endTime": 1733250720000,
        "status": 2,
        "politicalAdvertiserId": 0,
        "marginValue": null,
        "owId": 202500,
        "proposalTargeting":
        {
            "location":
            {
                "country": 1,
                "states":
                [
                    1,
                    2,
                    3
                ],
                "dma":
                [
                    1,
                    2,
                    3
                ],
                "city":
                [
                    1,
                    2,
                    3
                ],
                "county":
                [
                    1,
                    2,
                    3
                ],
                "congressionalDistricts":
                [
                    1,
                    2,
                    3
                ],
                "stateHouse":
                [
                    1,
                    2,
                    3
                ],
                "stateSenate":
                [
                    1,
                    2,
                    3
                ],
                "zipCodes": null,
                "locationAdvanceTargeted":
                [
                    "city",
                    "state"
                ],
                "advanceTargeted": false
            },
            "audience":
            {
                "audienceSegmentIds":
                [
                    6387630,
                    6387631,
                    6387632,
                    6387633,
                    6387634
                ],
                "advanceTargeted": false
            },
            "creative":
            {
                "creativeTypeIds":
                [
                    13
                ],
                "tvAutoBuying": false
            },
            "inventory":
            {
                "openExchangeInventory":
                {
                    "iabCategories":
                    [
                        1,
                        2
                    ],
                    "exchanges":
                    [
                        11,
                        16,
                        19
                    ]
                },
                "inventoryGroupIds":
                [],
                "advanceTargeted": false
            },
            "device":
            {
                "deviceTypesTargetedIds":
                [],
                "channelTypesTargetedIds":
                [],
                "deviceTypesAdvanceTargetedIds":
                [
                    1,
                    2
                ],
                "advanceTargeted": false
            }
        }
    }
}

Response 200 (Ready proposal)

{
    "success": "true",
    "data":
    {
        "id": 14,
        "name": "sample",
        "startTime": 1730658720000,
        "endTime": 1733250720000,
        "status": 6,
        "targetedReach": 2147483646,
        "targetedImpressions": 2147483646,
        "maxTargetedReach": 2147483646,
        "maxTargetedImpressions": 2147483646,
        "budget": 0.0,
        "maxBudget": 0.0,
        "owId": 202500,
        "proposedCampaigns":
        [
            {
                "id": 1234,
                "name": "Demo_Campaign_For_proposal",
                "startTime": 1730658720000,
                "endTime": 1733250720000,
                "strategy": "strategy",
                "creativeTypeId": 1,
                "duration": 30,
                "modelType": "cpm",
                "targetedReach": 1234,
                "maxTargetedReach": 12345566,
                "frequencyCap": 3,
                "targetedImpressions": 123,
                "maxTargetedImpressions": 12345,
                "cpm": 5.0,
                "minCpm": 3.5,
                "maxCpm": 1000.0,
                "budget": 1000.0,
                "maxBudget": 1000.0
            }
        ]
    }
}

Response 403

{
  "success": false,
  "errorObjects": [
    {
      "error": "Requested Resource is not accessible for the user"
    }
  ]
}

TypeScript

See TypeScript prerequisites for usage.

Draft proposal

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          id: number;
          name: string;
          startTime: number;
          endTime: number;
          status: number;
          politicalAdvertiserId: number;
          marginValue: number;
          owId: number;
          proposalTargeting: {
            location: {
              country: number;
              states: number[];
              dma: number[];
              city: number[];
              county: number[];
              congressionalDistricts: number[];
              stateHouse: number[];
              stateSenate: number[];
              zipCodes: string;
              locationAdvanceTargeted: string[];
              advanceTargeted: boolean;
            };
            audience: {
              audienceSegmentIds: number[];
              advanceTargeted: boolean;
            };
            creative: {
              creativeTypeIds: number[];
              tvAutoBuying: boolean;
            };
            inventory: {
              openExchangeInventory: {
                iabCategories: number[];
                exchanges: number[];
              };
              inventoryGroupIds: number[];
              advanceTargeted: boolean;
            };
            device: {
              deviceTypesTargetedIds: number[];
              channelTypesTargetedIds: number[];
              deviceTypesAdvanceTargetedIds: number[];
              advanceTargeted: boolean;
            }
          }
        };
      };
    };
  };
}

function getProposalDetailsById(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/plan/proposal/{proposalId}',
    params: {
      path: {
        proposalId: `number`
      }
    }
  };

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

Ready proposal

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          id: number;
          name: string;
          startTime: number;
          endTime: number;
          status: number;
          targetedReach: number;
          targetedImpressions: number;
          maxTargetedReach: number;
          maxTargetedImpressions: number;
          budget: number;
          maxBudget: number;
          owId: number;
          proposedCampaigns: {
            id: number;
            name: string;
            startTime: number;
            endTime: number;
            strategy: string;
            creativeTypeId: number;
            duration: number;
            modelType: string;
            targetedReach: number;
            maxTargetedReach: number;
            frequencyCap: number;
            targetedImpressions: number;
            maxTargetedImpressions: number;
            cpm: number;
            minCpm: number;
            maxCpm: number;
            budget: number;
            maxBudget: number;
          }[];
        };
      };
    };
  };
}

function getProposalDetailsById(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/plan/proposal/{proposalId}',
    params: {
      path: {
        proposalId: `number`
      }
    }
  };

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

---

Get list of proposals

GET

Get a list of proposal details.

A proposal id can be used in the Get proposal details by ID endpoint and to perform various actions in Proposal management endpoints.

Response properties

id string	Proposal ID.
name string	Proposal name.
statusId integer	Status ID. +Supported values 1 Converted 2 Draft 3 Expired 4 Failed 5 Processing 6 Ready 7 IO Created
createdOn integer	Unix epoch timestamp (in milliseconds) of creation date.
userAvatarUrl string	User avatar URL.
reach integer	Proposal reach.
impression integer	Proposal impression count.
ioId integer	Insertion order ID.
budget integer	Proposal budget.
startDate integer	Unix epoch timestamp (in milliseconds) of start date.
endDate integer	Unix epoch timestamp (in milliseconds) of end date.
createdBy string	User name.

JSON

Response 200

{
  "success": true,
  "data": {
    "proposalDetailList": [
      {
        "id": 6,
        "name": "planner-proposal-2",
        "statusId": 2,
        "createdOn": 1234567,
        "userAvatarUrl": "https://sample-c92d6b6cbde1.s3.com/avatar/sample.png",
        "reach": 4567,
        "impression": 345678,
        "ioId": null,
        "budget": 23423,
        "startDate": 1728890609000,
        "endDate": 1728990609000,
        "createdBy": "user1"
      },
      {
        "id": 7,
        "name": "planner-proposal-3",
        "statusId": 1,
        "createdOn": 1234567,
        "userAvatarUrl": "https://sample-c92d6b6cbde1.s3.com/avatar/sample.png",
        "reach": 4567,
        "impression": 345678,
        "ioId": 1,
        "budget": 23423,
        "startDate": 1728890609000,
        "endDate": 1728990609000,
        "createdBy": "user2"
      }
    ],
    "totalRecords": 7,
    "filteredRecords": 7,
    "recordsTotal": {
      "totalBudget": 23,
      "totalImpressions": 3865464
    }
  }
}

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: {
          proposalDetailList: {
            id: number;
            name: string;
            statusId: number;
            createdOn: number;
            userAvatarUrl: string;
            reach: number;
            impression: number;
            ioId: number;
            budget: number;
            startDate: number;
            endDate: number;
            createdBy: string;
          }[];
          totalRecords: number;
          filteredRecords: number;
          recordsTotal: {
            totalBudget: number;
            totalImpressions: number;
          }
        };
      };
    };
  };
}

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

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

---

Proposal reach and impressions summary

POST

Get summary of maximum reach and impressions for different targeting parameters in a proposal based on statistics and historical serving data.

Request schema
location object	Location data.
location object properties country array of integers Country ID. states array of integers States ID. dma array of integers DMA ID. city array of integers City ID. county array of integers County ID. congressionalDistricts array of integers Congressional district ID. stateHouse array of integers State house ID. stateSenate array of integers State senate ID. zipCodes string Comma separated zip code IDs.
audience object	Audience data.
audience object properties audienceSegmentIds array of integers Audience segment ID.
creative object	Creative data.
creative object properties creativeTypeIds array of integers Creative type IDs. +Supported values 0 All 11 Image 13 HTML 14 Video 15 Native 17 Audio
inventory object	Inventory data.
inventory object properties openExchangeInventory object Open Exchange inventory data. openExchangeInventory object properties iabCategories array of integers IAB category ID. exchanges array of integers Exchange ID. inventoryGroupIds array of integers Inventory group ID.
device object	Device data.
device object properties deviceTypesTargetedIds array of integers Targeted device type IDs. +Supported values 20300001 Mobile 20300002 Desktop 20300003 Connected TV 20300004 Tablet 20399999 Unknown channelTypesTargetedIds array of integers Targeted channel type IDs. +Supported values 21100001 App 21100002 OTT App 21100003 Web

Response properties

reach integer	Proposal reach.
impressions integer	Proposal impression count.

JSON

Request sample

{
  "location": {
    "country": 30100001,
    "states": [
      30200001,
      30200002,
      30200003
    ],
    "dma": [
      30900001,
      30900002
    ],
    "city": [
      30400001,
      30400002,
      30400003
    ],
    "county": [
      30300001,
      30300002,
      30300003
    ],
    "congressionalDistricts": [
      30600001
    ],
    "stateHouse": [
      30800001,
      30800002
    ],
    "stateSenate": [
      30700001,
      30700002,
      30700003
    ],
    "zipCodes": "167820,78656"
  },
  "audience": {
    "audienceSegmentIds": [
      6387630,
      6387631,
      6387632,
      6387633,
      6387634
    ]
  },
  "creative": {
    "creativeTypeIds": [
      11,
      13,
      14
    ]
  },
  "inventory": {
    "openExchangeInventory": {
      "iabCategories": [
        1,
        2
      ],
      "exchanges": [
        11,
        16,
        19,
        1
      ]
    },
    "inventoryGroupIds": [
      134523,
      134522,
      134436
    ]
  },
  "device": {
    "deviceTypesTargetedIds": [
      20300001,
      20300002,
      20300002,
      20300004
    ],
    "channelTypesTargetedIds": [
      11,
      12
    ]
  }
}

Response 200

{
  "success": true,
  "data": {
    "impressions": 105409776517,
    "reach": 210368111
  }
}

More responses

Response 403

{
  "success": false,
  "errorObjects": [
    {
      "error": "Requested proposal is not accessible for the user"
    }
  ]
}

Response 422

{
  "success": false,
  "errorObjects": [
    {
      "error": "Requested proposal with id [id] does not exist"
    }
  ]
}

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: {
          impressions: number;
          reach: number;
        };
      };
    };
  };
}

function getReachAndImpressions(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/plan/proposal-summary/reach-impressions',
    requestBody: {
      content: {
        "application/json": {
          proposalId?: `number`,
          location?: {
            country: `number`,
            states?: `array of numbers`,
            dma?: `array of numbers`,
            city?: `array of numbers`,
            county?: `array of numbers`,
            congressionalDistricts?: `array of numbers`,
            stateHouse?: `array of numbers`,
            stateSenate?: `array of numbers`,
            zipCodes?: `string`,
            isAdvanceTargeted?: `boolean`,
            locationAdvanceTargeted?: `array of numbers`,
          },
          audience?: {
            audienceSegmentIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          },
          creative?: {
            creativeTypeIds?: `array of numbers`,
            isTvAutoBuying?: `boolean`,
          },
          inventory?: {
            openExchangeInventory?: {
              iabCategories?: `array of numbers`,
              exchanges?: `array of numbers`,
            },
            inventoryGroupIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          },
          device?: {
            deviceTypesTargetedIds?: `array of numbers`,
            channelTypesTargetedIds?: `array of numbers`,
            deviceTypesAdvanceTargetedIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          }
        }
      }
    }
  };

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

---

Proposal device type summary

POST

Get summary of impressions distribution for different device types targeted in a proposal.

Request schema
location object	Location data.
location object properties country array of integers Country ID. states array of integers States ID. dma array of integers DMA ID. city array of integers City ID. county array of integers County ID. congressionalDistricts array of integers Congressional district ID. stateHouse array of integers State house ID. stateSenate array of integers State senate ID. zipCodes string Comma separated zip code IDs.
audience object	Audience data.
audience object properties audienceSegmentIds array of integers Audience segment ID.
creative object	Creative data.
creative object properties creativeTypeIds array of integers Creative type IDs. +Supported values 0 All 11 Image 13 HTML 14 Video 15 Native 17 Audio
inventory object	Inventory data.
inventory object properties openExchangeInventory object Open Exchange inventory data. openExchangeInventory object properties iabCategories array of integers IAB category ID. exchanges array of integers Exchange ID. inventoryGroupIds array of integers Inventory group ID.
device object	Device data.
device object properties deviceTypesTargetedIds array of integers Targeted device type IDs. +Supported values 20300001 Mobile 20300002 Desktop 20300003 Connected TV 20300004 Tablet 20399999 Unknown channelTypesTargetedIds array of integers Targeted channel type IDs. +Supported values 21100001 App 21100002 OTT App 21100003 Web

Response properties

deviceTypes object	Device types details.
deviceTypes object properties device string Device type name. percentage integer Impression distribution as a percentage. impressions integer Proposal impression count.

JSON

Request sample

{
  "location": {
    "country": 30100001,
    "states": [
      30200001,
      30200002,
      30200003
    ],
    "dma": [
      30900001,
      30900002
    ],
    "city": [
      30400001,
      30400002,
      30400003
    ],
    "county": [
      30300001,
      30300002,
      30300003
    ],
    "congressionalDistricts": [
      30600001
    ],
    "stateHouse": [
      30800001,
      30800002
    ],
    "stateSenate": [
      30700001,
      30700002,
      30700003
    ],
    "zipCodes": "167820,78656"
  },
  "audience": {
    "audienceSegmentIds": [
      6387630,
      6387631,
      6387632,
      6387633,
      6387634
    ]
  },
  "creative": {
    "creativeTypeIds": [
      11,
      13,
      14
    ]
  },
  "inventory": {
    "openExchangeInventory": {
      "iabCategories": [
        1,
        2
      ],
      "exchanges": [
        11,
        16,
        19,
        1
      ]
    },
    "inventoryGroupIds": [
      134523,
      134522,
      134436
    ]
  },
  "device": {
    "deviceTypesTargetedIds": [
      20300001,
      20300002,
      20300002,
      20300004
    ],
    "channelTypesTargetedIds": [
      11,
      12
    ]
  }
}

Response 200

{
  "success": true,
  "data": {
    "deviceTypes": [
      {
        "device": "Mobile",
        "percentage": 38.86,
        "impressions": 21402990540
      },
      {
        "device": "Desktop",
        "percentage": 11.63,
        "impressions": 6399597393
      },
      {
        "device": "CTV",
        "percentage": 47.89,
        "impressions": 26376959052
      },
      {
        "device": "Tablet",
        "percentage": 1.63,
        "impressions": 898221564
      }
    ]
  }
}

More responses

Response 403

{
  "success": false,
  "errorObjects": [
    {
      "error": "Requested proposal is not accessible for the user"
    }
  ]
}

Response 422

{
  "success": false,
  "errorObjects": [
    {
      "error": "Requested proposal with id [id] does not exist"
    }
  ]
}

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: {
          deviceTypes: {
            device: string;
            percentage: number;
            impressions: number;
          }[];
        };
      };
    };
  };
}

function getDeviceTypeData(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/plan/proposal-summary/device-type',
    requestBody: {
      content: {
        "application/json": {
          proposalId?: `number`,
          location?: {
            country: `number`,
            states?: `array of numbers`,
            dma?: `array of numbers`,
            city?: `array of numbers`,
            county?: `array of numbers`,
            congressionalDistricts?: `array of numbers`,
            stateHouse?: `array of numbers`,
            stateSenate?: `array of numbers`,
            zipCodes?: `string`,
            isAdvanceTargeted?: `boolean`,
            locationAdvanceTargeted?: `array of numbers`,
          },
          audience?: {
            audienceSegmentIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          },
          creative?: {
            creativeTypeIds?: `array of numbers`,
            isTvAutoBuying?: `boolean`,
          },
          inventory?: {
            openExchangeInventory?: {
              iabCategories?: `array of numbers`,
              exchanges?: `array of numbers`,
            },
            inventoryGroupIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          },
          device?: {
            deviceTypesTargetedIds?: `array of numbers`,
            channelTypesTargetedIds?: `array of numbers`,
            deviceTypesAdvanceTargetedIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          }
        }
      }
    }
  };

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

---

Proposal channel type summary

POST

Get summary of impressions distribution for different channel types targeted in a proposal.

Request schema
location object	Location data.
location object properties country array of integers Country ID. states array of integers States ID. dma array of integers DMA ID. city array of integers City ID. county array of integers County ID. congressionalDistricts array of integers Congressional district ID. stateHouse array of integers State house ID. stateSenate array of integers State senate ID. zipCodes string Comma separated zip code IDs.
audience object	Audience data.
audience object properties audienceSegmentIds array of integers Audience segment ID.
creative object	Creative data.
creative object properties creativeTypeIds array of integers Creative type IDs. +Supported values 0 All 11 Image 13 HTML 14 Video 15 Native 17 Audio
inventory object	Inventory data.
inventory object properties openExchangeInventory object Open Exchange inventory data. openExchangeInventory object properties iabCategories array of integers IAB category ID. exchanges array of integers Exchange ID. inventoryGroupIds array of integers Inventory group ID.
device object	Device data.
device object properties deviceTypesTargetedIds array of integers Targeted device type IDs. +Supported values 20300001 Mobile 20300002 Desktop 20300003 Connected TV 20300004 Tablet 20399999 Unknown channelTypesTargetedIds array of integers Targeted channel type IDs. +Supported values 21100001 App 21100002 OTT App 21100003 Web

Response properties

channelTypes object	Channel types details.
channelTypes object properties channel string Channel type name. percentage integer Impression distribution as a percentage. impressions integer Proposal impression count.

JSON

Request sample

{
  "location": {
    "country": 30100001,
    "states": [
      30200001,
      30200002,
      30200003
    ],
    "dma": [
      30900001,
      30900002
    ],
    "city": [
      30400001,
      30400002,
      30400003
    ],
    "county": [
      30300001,
      30300002,
      30300003
    ],
    "congressionalDistricts": [
      30600001
    ],
    "stateHouse": [
      30800001,
      30800002
    ],
    "stateSenate": [
      30700001,
      30700002,
      30700003
    ],
    "zipCodes": "167820,78656"
  },
  "audience": {
    "audienceSegmentIds": [
      6387630,
      6387631,
      6387632,
      6387633,
      6387634
    ]
  },
  "creative": {
    "creativeTypeIds": [
      11,
      13,
      14
    ]
  },
  "inventory": {
    "openExchangeInventory": {
      "iabCategories": [
        1,
        2
      ],
      "exchanges": [
        11,
        16,
        19,
        1
      ]
    },
    "inventoryGroupIds": [
      134523,
      134522,
      134436
    ]
  },
  "device": {
    "deviceTypesTargetedIds": [
      20300001,
      20300002,
      20300002,
      20300004
    ],
    "channelTypesTargetedIds": [
      11,
      12
    ]
  }
}

Response 200

{
  "success": true,
  "data": {
    "channelTypes": [
      {
        "channel": "App",
        "percentage": 22.36,
        "impressions": 12314443086
      },
      {
        "channel": "Web",
        "percentage": 29.65,
        "impressions": 16326324495
      },
      {
        "channel": "CTV",
        "percentage": 47.89,
        "impressions": 26376959052
      },
      {
        "channel": "OTT",
        "percentage": 0.11,
        "impressions": 60041916
      }
    ]
  }
}

More responses

Response 403

{
  "success": false,
  "errorObjects": [
    {
      "error": "Requested proposal is not accessible for the user"
    }
  ]
}

Response 422

{
  "success": false,
  "errorObjects": [
    {
      "error": "Requested proposal with id [id] does not exist"
    }
  ]
}

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: {
          channelTypes: {
            channel: string;
            percentage: number;
            impressions: number;
          }[];
        };
      };
    };
  };
}

function getChannelTypeData(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/plan/proposal-summary/channel-type',
    requestBody: {
      content: {
        "application/json": {
          proposalId?: `number`,
          location?: {
            country: `number`,
            states?: `array of numbers`,
            dma?: `array of numbers`,
            city?: `array of numbers`,
            county?: `array of numbers`,
            congressionalDistricts?: `array of numbers`,
            stateHouse?: `array of numbers`,
            stateSenate?: `array of numbers`,
            zipCodes?: `string`,
            isAdvanceTargeted?: `boolean`,
            locationAdvanceTargeted?: `array of numbers`,
          },
          audience?: {
            audienceSegmentIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          },
          creative?: {
            creativeTypeIds?: `array of numbers`,
            isTvAutoBuying?: `boolean`,
          },
          inventory?: {
            openExchangeInventory?: {
              iabCategories?: `array of numbers`,
              exchanges?: `array of numbers`,
            },
            inventoryGroupIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          },
          device?: {
            deviceTypesTargetedIds?: `array of numbers`,
            channelTypesTargetedIds?: `array of numbers`,
            deviceTypesAdvanceTargetedIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          }
        }
      }
    }
  };

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

---

Proposal bid landscape summary

POST

Get summary of impressions distribution for different bid landscapes targeted in a proposal.

Request schema
location object	Location data.
location object properties country array of integers Country ID. states array of integers States ID. dma array of integers DMA ID. city array of integers City ID. county array of integers County ID. congressionalDistricts array of integers Congressional district ID. stateHouse array of integers State house ID. stateSenate array of integers State senate ID. zipCodes string Comma separated zip code IDs.
audience object	Audience data.
audience object properties audienceSegmentIds array of integers Audience segment ID.
creative object	Creative data.
creative object properties creativeTypeIds array of integers Creative type IDs. +Supported values 0 All 11 Image 13 HTML 14 Video 15 Native 17 Audio
inventory object	Inventory data.
inventory object properties openExchangeInventory object Open Exchange inventory data. openExchangeInventory object properties iabCategories array of integers IAB category ID. exchanges array of integers Exchange ID. inventoryGroupIds array of integers Inventory group ID.
device object	Device data.
device object properties deviceTypesTargetedIds array of integers Targeted device type IDs. +Supported values 20300001 Mobile 20300002 Desktop 20300003 Connected TV 20300004 Tablet 20399999 Unknown channelTypesTargetedIds array of integers Targeted channel type IDs. +Supported values 21100001 App 21100002 OTT App 21100003 Web

Response properties

cpm integer	Cost per mille.
percentage integer	Impression distribution as a percentage.
impressions integer	Proposal impression count.

JSON

Request sample

{
  "location": {
    "country": 30100001,
    "states": [
      30200001,
      30200002,
      30200003
    ],
    "dma": [
      30900001,
      30900002
    ],
    "city": [
      30400001,
      30400002,
      30400003
    ],
    "county": [
      30300001,
      30300002,
      30300003
    ],
    "congressionalDistricts": [
      30600001
    ],
    "stateHouse": [
      30800001,
      30800002
    ],
    "stateSenate": [
      30700001,
      30700002,
      30700003
    ],
    "zipCodes": "167820,78656"
  },
  "audience": {
    "audienceSegmentIds": [
      6387630,
      6387631,
      6387632,
      6387633,
      6387634
    ]
  },
  "creative": {
    "creativeTypeIds": [
      11,
      13,
      14
    ]
  },
  "inventory": {
    "openExchangeInventory": {
      "iabCategories": [
        1,
        2
      ],
      "exchanges": [
        11,
        16,
        19,
        1
      ]
    },
    "inventoryGroupIds": [
      134523,
      134522,
      134436
    ]
  },
  "device": {
    "deviceTypesTargetedIds": [
      20300001,
      20300002,
      20300002,
      20300004
    ],
    "channelTypesTargetedIds": [
      11,
      12
    ]
  }
}

Response 200

{
  "success": true,
  "data": {
    "HTML": [
      {
        "percentile": 0,
        "cpm": 0,
        "impressions": 0
      },
      {
        "percentile": 10,
        "cpm": 0.001,
        "impressions": 2719219
      },
      {
        "percentile": 20,
        "cpm": 0.01,
        "impressions": 27192810
      },
      {
        "percentile": 100,
        "cpm": 3.0072,
        "impressions": 271029139123
      }
    ],
    "Video": [
      {
        "percentile": 0,
        "cpm": 0,
        "impressions": 0
      },
      {
        "percentile": 10,
        "cpm": 0.003,
        "impressions": 2719219
      },
      {
        "percentile": 20,
        "cpm": 0.05,
        "impressions": 27192810
      },
      {
        "percentile": 100,
        "cpm": 10.372,
        "impressions": 271029139123
      }
    ]
  }
}

More responses

Response 403

{
  "success": false,
  "errorObjects": [
    {
      "error": "Requested proposal is not accessible for the user"
    }
  ]
}

Response 422

{
  "success": false,
  "errorObjects": [
    {
      "error": "Requested proposal with id [id] does not exist"
    }
  ]
}

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: {
          HTML: {
            percentile: number;
            cpm: number;
            impressions: number;
          }[];
          Video: {
            percentile: number;
            cpm: number;
            impressions: number;
          }
        };
      };
    };
  };
}

function getBidLandscapeData(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/plan/proposal-summary/bid-landscape',
    requestBody: {
      content: {
        "application/json": {
          proposalId?: `number`,
          location?: {
            country: `number`,
            states?: `array of numbers`,
            dma?: `array of numbers`,
            city?: `array of numbers`,
            county?: `array of numbers`,
            congressionalDistricts?: `array of numbers`,
            stateHouse?: `array of numbers`,
            stateSenate?: `array of numbers`,
            zipCodes?: `string`,
            isAdvanceTargeted?: `boolean`,
            locationAdvanceTargeted?: `array of numbers`,
          },
          audience?: {
            audienceSegmentIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          },
          creative?: {
            creativeTypeIds?: `array of numbers`,
            isTvAutoBuying?: `boolean`,
          },
          inventory?: {
            openExchangeInventory?: {
              iabCategories?: `array of numbers`,
              exchanges?: `array of numbers`,
            },
            inventoryGroupIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          },
          device?: {
            deviceTypesTargetedIds?: `array of numbers`,
            channelTypesTargetedIds?: `array of numbers`,
            deviceTypesAdvanceTargetedIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          }
        }
      }
    }
  };

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

---

Download proposal

GET

Get download URL for proposals with statuses: ready, failed, converted, or expired.

Query parameters
fileType integer	Type of file to download. +Supported values 1 Excel 2 CSV 3 PDF
proposalId integer	Proposal ID.

Response properties

proposalReportUrl string

Proposal report URL.

JSON

Response 200

{
  "success": true,
  "data": {
    "proposalReportUrl": "https://example.s3.amazonaws.com/planner/proposal/report/34567890iuhgvbhjio987654456789oijhbvbjio9876"
  }
}

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: {
          proposalReportUrl: string;
        };
      };
    };
  };
}

function generateS3LinkForDownloadProposal(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/plan/proposal/{proposalId}/download',
    params: {
      path: {
        proposalId: `number`
      },
      query: {
        fileType: `string`
      }
    }
  };

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

Proposal management

Create proposal

POST

Request schema
id string	Proposal ID.
name string	Proposal name.
startTime integer	Unix epoch timestamp (in milliseconds) of start time.
endTime integer	Unix epoch timestamp (in milliseconds) of end time.
politicalAdvertiserId integer	Advertiser ID.
margin integer	Margin percentage applied on top of base CPM, not a currency amount, valid range: 0-100.
location object	Location data.
location object properties country array of integers Country ID. states array of integers States ID. dma array of integers DMA ID. city array of integers City ID. county array of integers County ID. congressionalDistricts array of integers Congressional district ID. stateHouse array of integers State house ID. stateSenate array of integers State senate ID. zipCodes string Comma separated zip code IDs. isAdvanceTargeted boolean When true, indicates that a new campaign must be created for advanced audience and inventory targeting. locationAdvanceTargeted array of integers When true, indicates that a new campaign must be created for advanced location targeting.
audience object	Audience data.
audience object properties audienceSegmentIds array of integers Audience segment ID. isAdvanceTargeted boolean When true, indicates that a new campaign must be created for advanced audience and inventory targeting.
creative object	Creative data.
creative object properties creativeTypeIds array of integers Creative type ID. +Supported values 0 All 11 Image 13 HTML 14 Video 15 Native 17 Audio isTvAutoBuying boolean If true, indicates video creative is eligible for TV advertising.
inventory object	Inventory data.
inventory object properties openExchangeInventory object Open Exchange inventory data. openExchangeInventory object properties iabCategories array of integers IAB category ID. exchanges array of integers Exchange ID. inventoryGroupIds array of integers Inventory group ID. isAdvanceTargeted boolean When true, indicates that a new campaign must be created for advanced audience and inventory targeting.
device object	Device data.
device object properties deviceTypesTargetedIds array of integers Targeted device type IDs. +Supported values 20300001 Mobile 20300002 Desktop 20300003 Connected TV 20300004 Tablet 20399999 Unknown channelTypesTargetedIds array of integers Targeted channel type IDs. +Supported values 21100001 App 21100002 OTT App 21100003 Web isAdvanceTargeted boolean When true, indicates that a new campaign must be created for advanced audience and inventory targeting. deviceTypesAdvanceTargetedIds array of integers When true, indicates that a new campaign must be created for advanced device targeting.

Response properties

id integer	Proposal ID.
message string	Success message.

JSON

Request sample

{
  "id": "11",
  "name": "sample_planner",
  "startTime": 1730658720000,
  "endTime": 1733250720000,
  "politicalAdvertiserId": 644,
  "margin": 10,
  "location": {
    "country": 30100001,
    "states": [
      30200001,
      30200002,
      30200003
    ],
    "dma": [
      30900001,
      30900002
    ],
    "city": [
      30400001,
      30400002,
      30400003
    ],
    "county": [
      30300001,
      30300002,
      30300003
    ],
    "congressionalDistricts": [
      30600001
    ],
    "stateHouse": [
      30800001,
      30800002
    ],
    "stateSenate": [
      30700001,
      30700002,
      30700003
    ],
    "zipCodes": "167820,78656",
    "isAdvanceTargeted": true,
    "locationAdvanceTargeted": [
      302,
      304,
      309
    ]
  },
  "audience": {
    "audienceSegmentIds": [
      6387630,
      6387631,
      6387632,
      6387633,
      6387634
    ],
    "isAdvanceTargeted": true
  },
  "creative": {
    "creativeTypeIds": [
      11,
      13,
      14
    ],
    "isTvAutoBuying": true
  },
  "inventory": {
    "openExchangeInventory": {
      "iabCategories": [
        1,
        2
      ],
      "exchanges": [
        11,
        16,
        19,
        1
      ]
    },
    "inventoryGroupIds": [
      134523,
      134522,
      134436
    ],
    "isAdvanceTargeted": true
  },
  "device": {
    "deviceTypesTargetedIds": [
      20300001,
      20300002,
      20300002,
      20300004
    ],
    "channelTypesTargetedIds": [],
    "isAdvanceTargeted": true,
    "deviceTypesAdvanceTargetedIds": [
      20300002,
      20300004
    ]
  }
}

Response 200

{
  "success": true,
  "data": {
    "id": 11,
    "message": "sample_planner generated successfully"
  }
}

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: {
          id: number;
          message: string;
        };
      };
    };
  };
}

function createProposal(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/plan/proposal/add',
    requestBody: {
      content: {
        "application/json": {
          name?: `string`,
          startTime?: `number`,
          endTime?: `number`,
          politicalAdvertiserId?: `number`,
          location?: {
            country: `number`,
            states?: `array of numbers`,
            dma?: `array of numbers`,
            city?: `array of numbers`,
            county?: `array of numbers`,
            congressionalDistricts?: `array of numbers`,
            stateHouse?: `array of numbers`,
            stateSenate?: `array of numbers`,
            zipCodes?: `string`,
            isAdvanceTargeted?: `boolean`,
            locationAdvanceTargeted?: `array of numbers`,
          },
          margin?: `number`,
          audience?: {
            audienceSegmentIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          },
          creative?: {
            creativeTypeIds?: `array of numbers`,
            isTvAutoBuying?: `boolean`,
          },
          inventory?: {
            openExchangeInventory?: {
              iabCategories?: `array of numbers`,
              exchanges?: `array of numbers`,
            },
            inventoryGroupIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          },
          device?: {
            deviceTypesTargetedIds?: `array of numbers`,
            channelTypesTargetedIds?: `array of numbers`,
            deviceTypesAdvanceTargetedIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          },
          id?: `number`,
          reach?: `number`,
          maxReach?: `number`,
          impressions?: `number`,
          maxImpressions?: `number`,
          frequencyCap?: `number`,
          budget?: `number`,
          maxBudget?: `number`,
          isPoliticalAdvertiser?: `boolean`,
        }
      }
    }
  };

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

---

Create draft proposal

POST

Request schema
id string	Proposal ID.
name string	Proposal name.
startTime integer	Unix epoch timestamp (in milliseconds) of start time.
endTime integer	Unix epoch timestamp (in milliseconds) of end time.
politicalAdvertiserId integer	Advertiser ID.
margin integer	Margin percentage applied on top of base CPM, not a currency amount, valid range: 0-100.
location object	Location data.
location object properties country array of integers Country ID. states array of integers States ID. dma array of integers DMA ID. city array of integers City ID. county array of integers County ID. congressionalDistricts array of integers Congressional district ID. stateHouse array of integers State house ID. stateSenate array of integers State senate ID. zipCodes string Comma separated zip code IDs. isAdvanceTargeted boolean When true, indicates that a new campaign must be created for advanced audience and inventory targeting. locationAdvanceTargeted array of integers When true, indicates that a new campaign must be created for advanced location targeting.
audience object	Audience data.
audience object properties audienceSegmentIds array of integers Audience segment ID. isAdvanceTargeted boolean When true, indicates that a new campaign must be created for advanced audience and inventory targeting.
creative object	Creative data.
creative object properties creativeTypeIds array of integers Creative type ID. +Supported values 0 All 11 Image 13 HTML 14 Video 15 Native 17 Audio isTvAutoBuying boolean If true, indicates video creative is eligible for TV advertising.
inventory object	Inventory data.
inventory object properties openExchangeInventory object Open Exchange inventory data. openExchangeInventory object properties iabCategories array of integers IAB category ID. exchanges array of integers Exchange ID. inventoryGroupIds array of integers Inventory group ID. isAdvanceTargeted boolean When true, indicates that a new campaign must be created for advanced audience and inventory targeting.
device object	Device data.
device object properties deviceTypesTargetedIds array of integers Device types targeted ID. channelTypesTargetedIds array of integers Targeted channel type IDs. +Supported values 21100001 App 21100002 OTT App 21100003 Web isAdvanceTargeted boolean When true, indicates that a new campaign must be created for advanced audience and inventory targeting. deviceTypesAdvanceTargetedIds array of integers When true, indicates that a new campaign must be created for advanced device targeting.

Response properties

id integer	Proposal ID.
message string	Success message.

JSON

Request sample

{
  "id": "11",
  "name": "sample_planner",
  "startTime": 1730658720000,
  "endTime": 1733250720000,
  "politicalAdvertiserId": 644,
  "margin": 10,
  "location": {
    "country": 30100001,
    "states": [
      30200001,
      30200002,
      30200003
    ],
    "dma": [
      30900001,
      30900002
    ],
    "city": [
      30400001,
      30400002,
      30400003
    ],
    "county": [
      30300001,
      30300002,
      30300003
    ],
    "congressionalDistricts": [
      30600001
    ],
    "stateHouse": [
      30800001,
      30800002
    ],
    "stateSenate": [
      30700001,
      30700002,
      30700003
    ],
    "zipCodes": "167820,78656",
    "isAdvanceTargeted": true,
    "locationAdvanceTargeted": [
      302,
      304,
      309
    ]
  },
  "audience": {
    "audienceSegmentIds": [
      6387630,
      6387631,
      6387632,
      6387633,
      6387634
    ],
    "isAdvanceTargeted": true
  },
  "creative": {
    "creativeTypeIds": [
      11,
      13,
      14
    ],
    "isTvAutoBuying": true
  },
  "inventory": {
    "openExchangeInventory": {
      "iabCategories": [
        1,
        2
      ],
      "exchanges": [
        11,
        16,
        19,
        1
      ]
    },
    "inventoryGroupIds": [
      134523,
      134522,
      134436
    ],
    "isAdvanceTargeted": true
  },
  "device": {
    "deviceTypesTargetedIds": [
      20300001,
      20300002,
      20300002,
      20300004
    ],
    "channelTypesTargetedIds": [],
    "isAdvanceTargeted": true,
    "deviceTypesAdvanceTargetedIds": [
      20300002,
      20300004
    ]
  }
}

Response 200

{
  "success": true,
  "data": {
    "id": 11,
    "message": "sample_planner generated successfully"
  }
}

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: {
          id: number;
          message: string;
        };
      };
    };
  };
}

function addDraftProposal(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/plan/proposal/draft',
    requestBody: {
      content: {
        "application/json": {
          name?: `string`,
          startTime?: `number`,
          endTime?: `number`,
          politicalAdvertiserId?: `number`,
          location?: {
            country: `number`,
            states?: `array of numbers`,
            dma?: `array of numbers`,
            city?: `array of numbers`,
            county?: `array of numbers`,
            congressionalDistricts?: `array of numbers`,
            stateHouse?: `array of numbers`,
            stateSenate?: `array of numbers`,
            zipCodes?: `string`,
            isAdvanceTargeted?: `boolean`,
            locationAdvanceTargeted?: `array of numbers`,
          },
          margin?: `number`,
          audience?: {
            audienceSegmentIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          },
          creative?: {
            creativeTypeIds?: `array of numbers`,
            isTvAutoBuying?: `boolean`,
          },
          inventory?: {
            openExchangeInventory?: {
              iabCategories?: `array of numbers`,
              exchanges?: `array of numbers`,
            },
            inventoryGroupIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          },
          device?: {
            deviceTypesTargetedIds?: `array of numbers`,
            channelTypesTargetedIds?: `array of numbers`,
            deviceTypesAdvanceTargetedIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          },
          isPoliticalAdvertiser?: `boolean`,
        }
      }
    }
  };

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

---

Update proposal

PATCH

Update proposal details. The target proposal must currently be in ready or failed status; any other status (draft, processing, converted, expired) is rejected with the error "Proposal Status is invalid".

Path parameters
proposalId integer	Proposal ID.

Request schema
proposalName string	Proposal name.
proposalStartTime integer	Unix epoch timestamp (in milliseconds) of start time.
proposalEndTime integer	Unix epoch timestamp (in milliseconds) of end time.
politicalAdvertiserId integer	Political Advertiser ID.
proposalStatusId integer	Proposal status ID. +Supported values 1 Converted 2 Draft 3 Expired 4 Failed 5 Processing 6 Ready 7 IO Created
proposalReach integer	Proposal reach.
proposalMaxReach integer	Proposal max reach.
proposalImpressions integer	Proposal impressions.
proposalMaxImpressions integer	Proposal max impressions.
proposalBudget integer	Proposal budget.
proposalMaxBudget integer	Proposal max budget.
campaigns object	Campaign data.
campaigns object properties id integer Campaign ID. name string Campaign name. startTime integer Unix epoch timestamp (in milliseconds) of start time. endTime integer Unix epoch timestamp (in milliseconds) of end time. reach integer Reach. frequencyCap integer Frequency cap. impressions integer Impressions. cpm integer CPM. budget integer Campaign budget.
deletedCampaignIds array of integers	Deleted campaign IDs.

Response properties

message string

Success message.

JSON

Request sample

{
  "proposalName": "proposalName",
  "proposalStartTime": 1729449000000,
  "proposalEndTime": 1730313000000,
  "politicalAdvertiserId": 644,
  "proposalStatusId": 6,
  "proposalReach": 150000,
  "proposalMaxReach": 150000,
  "proposalImpressions": 112500000,
  "proposalMaxImpressions": 112500000,
  "proposalBudget": 1125000,
  "proposalMaxBudget": 1125000,
  "campaigns": [
    {
      "id": 1,
      "name": "Proposal",
      "startTime": 1729449000000,
      "endTime": 1730313000000,
      "reach": 150000,
      "frequencyCap": 3,
      "impressions": 4500000,
      "cpm": 1,
      "budget": 4500
    }
  ],
  "deletedCampaignIds": [
    3,
    4
  ]
}

Response 200

{
  "success": true,
  "data": {
    "message": "Proposal updated successfully"
  }
}

More responses

Response 403

{
  "success": false,
  "errorObjects": [
    {
      "error": "Requested Proposal details is not accessible to logged-in user"
    }
  ]
}

Response 422

{
  "success": false,
  "errorObjects": [
    {
      "error": "Proposal not found",
      "field": "proposalId"
    }
  ]
}

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: {
          message: string;
        };
      };
    };
  };
}

function editReadyProposal(): Promise<Responses> {
  const options = {
    method: 'PATCH',
    url: 'https://api.iqm.com/api/v3/plan/proposal/{proposalId}',
    params: {
      path: {
        proposalId: `number`
      }
    },
    requestBody: {
      content: {
        "application/json": {

          proposalId?: `number`,
          proposalName?: `string`,
          proposalStartTime?: `number`,
          proposalEndTime?: `number`,
          proposalStatusId?: `number`,
          proposalReach?: `number`,
          proposalMaxReach?: `number`,
          proposalImpressions?: `number`,
          proposalMaxImpressions?: `number`,
          politicalAdvertiserId?: `number`,
          proposalBudget?: `number`,
          proposalMaxBudget?: `number`,
          proposalOwId?: `number`,
          campaigns?: {
            id?: `number`,
            name?: `string`,
            startTime?: `number`,
            endTime?: `number`,
            durationInDays?: `number`,
            reach?: `number`,
            maxReach?: `number`,
            impressions?: `number`,
            maxImpressions?: `number`,
            cpm?: `number`,
            minCpm?: `number`,
            frequencyCap?: `number`,
            budget?: `number`,
            maxBudget?: `number`,
            proposalId?: `number`,
            campaignId?: `number`,
            timeZoneId?: `number`,
            owId?: `number`,
            strategy?: `string`,
            location?: {
              country: `number`,
              states?: `array of numbers`,
              dma?: `array of numbers`,
              city?: `array of numbers`,
              county?: `array of numbers`,
              congressionalDistricts?: `array of numbers`,
              stateHouse?: `array of numbers`,
              stateSenate?: `array of numbers`,
              zipCodes?: `string`,
              isAdvanceTargeted?: `boolean`,
              locationAdvanceTargeted?: `array of numbers`,
            },
            audience?: {
              audienceSegmentIds?: `array of numbers`,
              isAdvanceTargeted?: `boolean`,
            },
            creative?: {
              creativeTypeIds?: `array of numbers`,
              isTvAutoBuying?: `boolean`,
            },
            inventory?: {
              openExchangeInventory?: {
                iabCategories?: `array of numbers`,
                exchanges?: `array of numbers`,
              },
              inventoryGroupIds?: `array of numbers`,
              isAdvanceTargeted?: `boolean`;
            },
            device?: {
              deviceTypesTargetedIds?: `array of numbers`,
              channelTypesTargetedIds?: `array of numbers`,
              deviceTypesAdvanceTargetedIds?: `array of numbers`,
              isAdvanceTargeted?: `boolean`,
            },
            locationStrategy?: `string`,
            audienceStrategy?: `string`,
            inventoryStrategy?: `string`,
            deviceStrategy?: `string`,
            deleted?: `boolean`,
          }[],
          deletedCampaignIds?: `array of numbers`,
          proposalMargin?: `number`,
          ioId?: `number`,
          proposalCreatedByUowId?: `number`,
          isPoliticalAdvertiser?: `boolean`,
        }
      }
    }
  };

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

---

Update draft proposal

PATCH

Update draft proposal details.

Path parameters
proposalId integer	Proposal ID.

Request schema
id string	Proposal ID.
name string	Proposal name.
startTime integer	Unix epoch timestamp (in milliseconds) of start time.
endTime integer	Unix epoch timestamp (in milliseconds) of end time.
politicalAdvertiserId integer	Advertiser ID.
margin integer	Margin percentage applied on top of base CPM, not a currency amount, valid range: 0-100.
location object	Location data.
location object properties country array of integers Country ID. states array of integers States ID. dma array of integers DMA ID. city array of integers City ID. county array of integers County ID. congressionalDistricts array of integers Congressional district ID. stateHouse array of integers State house ID. stateSenate array of integers State senate ID. zipCodes string Comma separated zip code IDs. isAdvanceTargeted boolean When true, indicates that a new campaign must be created for advanced audience and inventory targeting. locationAdvanceTargeted array of integers When true, indicates that a new campaign must be created for advanced location targeting.
audience object	Audience data.
audience object properties audienceSegmentIds array of integers Audience segment ID. isAdvanceTargeted boolean When true, indicates that a new campaign must be created for advanced audience and inventory targeting.
creative object	Creative data.
creative object properties creativeTypeIds array of integers Creative type ID. +Supported values 0 All 11 Image 13 HTML 14 Video 15 Native 17 Audio isTvAutoBuying boolean If true, indicates video creative is eligible for TV advertising.
inventory object	Inventory data.
inventory object properties openExchangeInventory object Open Exchange inventory data. openExchangeInventory object properties iabCategories array of integers IAB category ID. exchanges array of integers Exchange ID. inventoryGroupIds array of integers Inventory group ID. isAdvanceTargeted boolean When true, indicates that a new campaign must be created for advanced audience and inventory targeting.
device object	Device data.
device object properties deviceTypesTargetedIds array of integers Device types targeted ID. channelTypesTargetedIds array of integers Targeted channel type IDs. +Supported values 21100001 App 21100002 OTT App 21100003 Web isAdvanceTargeted boolean When true, indicates that a new campaign must be created for advanced audience and inventory targeting. deviceTypesAdvanceTargetedIds array of integers When true, indicates that a new campaign must be created for advanced device targeting.

Response properties

id integer	Proposal ID.
message string	Success message.

JSON

Request sample

{
  "name": "sample_planner",
  "startTime": 1730658720000,
  "endTime": 1733250720000,
  "politicalAdvertiserId": 644,
  "margin": 10,
  "location": {
    "country": 30100001,
    "states": [
      30200001,
      30200002,
      30200003
    ],
    "dma": [
      30900001,
      30900002
    ],
    "city": [
      30400001,
      30400002,
      30400003
    ],
    "county": [
      30300001,
      30300002,
      30300003
    ],
    "congressionalDistricts": [
      30600001
    ],
    "stateHouse": [
      30800001,
      30800002
    ],
    "stateSenate": [
      30700001,
      30700002,
      30700003
    ],
    "zipCodes": "167820,78656",
    "isAdvanceTargeted": true,
    "locationAdvanceTargeted": [
      302,
      304,
      309
    ]
  },
  "audience": {
    "audienceSegmentIds": [
      6387630,
      6387631,
      6387632,
      6387633,
      6387634
    ],
    "isAdvanceTargeted": true
  },
  "creative": {
    "creativeTypeIds": [
      11,
      13,
      14
    ],
    "isTvAutoBuying": true
  },
  "inventory": {
    "openExchangeInventory": {
      "iabCategories": [
        1,
        2
      ],
      "exchanges": [
        11,
        16,
        19,
        1
      ]
    },
    "inventoryGroupIds": [
      134523,
      134522,
      134436
    ],
    "isAdvanceTargeted": true
  },
  "device": {
    "deviceTypesTargetedIds": [
      20300001,
      20300002,
      20300002,
      20300004
    ],
    "channelTypesTargetedIds": [],
    "isAdvanceTargeted": true,
    "deviceTypesAdvanceTargetedIds": [
      20300002,
      20300004
    ]
  }
}

Response 200

{
  "success": true,
  "data": {
    "id": 11,
    "message": "sample_planner updated successfully"
  }
}

More responses

Response 403

{
  "success": false,
  "errorObjects": [
    {
      "error": "Requested Proposal details is not accessible to logged-in user"
    }
  ]
}

Response 422

{
  "success": false,
  "errorObjects": [
    {
      "error": "Proposal not found",
      "field": "proposalId"
    }
  ]
}

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: {
          id: number;
          message: string;
        };
      };
    };
  };
}

function updateDraftProposal(): Promise<Responses> {
  const options = {
    method: 'PATCH',
    url: 'https://api.iqm.com/api/v3/plan/proposal/draft/{proposalId}',
    params: {
      path: {
        proposalId: `number`
      }
    },
    requestBody: {
      content: {
        "application/json": {
          name?: `string`,
          startTime?: `number`,
          endTime?: `number`,
          politicalAdvertiserId?: `number`,
          location?: {
            country: `number`,
            states?: `array of numbers`,
            dma?: `array of numbers`,
            city?: `array of numbers`,
            county?: `array of numbers`,
            congressionalDistricts?: `array of numbers`,
            stateHouse?: `array of numbers`,
            stateSenate?: `array of numbers`,
            zipCodes?: `string`,
            isAdvanceTargeted?: `boolean`,
            locationAdvanceTargeted?: `array of numbers`,
          },
          margin?: `number`,
          audience?: {
            audienceSegmentIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          },
          creative?: {
            creativeTypeIds?: `array of numbers`,
            isTvAutoBuying?: `boolean`,
          },
          inventory?: {
            openExchangeInventory?: {
              iabCategories?: `array of numbers`,
              exchanges?: `array of numbers`,
            },
            inventoryGroupIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          },
          device?: {
            deviceTypesTargetedIds?: `array of numbers`,
            channelTypesTargetedIds?: `array of numbers`,
            deviceTypesAdvanceTargetedIds?: `array of numbers`,
            isAdvanceTargeted?: `boolean`,
          },
          isPoliticalAdvertiser?: `boolean`,
        }
      }
    }
  };

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

---

Generate campaigns for ready proposal

POST

Convert a proposal into an insertion order with draft campaigns. The proposal status updates to processing and triggers async campaign generation; once completed the status becomes converted. The target proposal must be in ready or failed status. Converting to converted is a one-way transition: once a proposal has converted, any further edit or restore operation that requires ready, failed, or expired status will fail, though downloading the proposal remains available.

Path parameters
proposalId integer	Proposal ID.

Response properties

message string

Success message.

JSON

Response 200

{
  "success": true,
  "data": {
    "message": "Campaign generation is in progress"
  }
}

More responses

Response 403

{
  "success": false,
  "errorObjects": [
    {
      "error": "Requested Proposal details is not accessible to logged-in user"
    }
  ]
}

Response 422

{
  "success": false,
  "errorObjects": [
    {
      "error": "Proposal not found"
    }
  ]
}

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: {
          message: string;
        };
      };
    };
  };
}

function generateIOCampaigns(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/plan/proposal/{proposalId}/campaigns',
    params: {
      path: {
        proposalId: `number`
      }
    }
  };

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

---

Restore proposal

PATCH

Restore expired proposals back to ready status by recalculating their budgeting based on new start and end dates. This is not an undo for a soft-deleted proposal; Delete proposal and this restore operation are unrelated.

Request schema
proposalIds array of integers	Proposal IDs.
startTime integer	Unix epoch timestamp (in milliseconds) of start time.
endTime integer	Unix epoch timestamp (in milliseconds) of end time.

Response properties

message string

Success message.

JSON

Request sample

{
  "proposalIds": [
    2,
    3
  ],
  "startTime": 1212121212,
  "endTime": 1512121212
}

Response 200

{
  "success": true,
  "data": {
    "message": "Proposal restored successfully"
  }
}

More responses

Response 403

{
  "success": false,
  "errorObjects": [
    {
      "error": "Requested Proposal details is not accessible to logged-in user"
    }
  ]
}

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: {
          message: string;
        };
      };
    };
  };
}

function restoreReadyProposal(): Promise<Responses> {
  const options = {
    method: 'PATCH',
    url: 'https://api.iqm.com/api/v3/plan/proposals/restore',
    requestBody: {
      content: {
        "application/json": {
          proposalIds: `array of numbers`,
          startTime: `number`,
          endTime: `number`,
        }
      }
    }
  };

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

---

Duplicate proposal

POST

Duplicate an existing proposal.

Path parameters
proposalId integer	Proposal ID.

Response properties

proposalName string	Proposal name.
startTime integer	Unix epoch timestamp (in milliseconds) of start time.
endTime integer	Unix epoch timestamp (in milliseconds) of end time.

JSON

Response 200

{
  "proposalName": "Copy of proposal 3",
  "startTime": 1732023982000,
  "endTime": 1732053982000
}

TypeScript

See TypeScript prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        proposalName: string;
        startTime: number;
        endTime: number;
      };
    };
  };
}

function createDuplicateProposal(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/plan/proposal/{proposalId}/duplicate',
    params: {
      path: {
        proposalId: `number`
      }
    }
  };

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

---

Delete proposal

DELETE

Delete an existing proposal.

Query parameters
proposalIds string	Comma separated proposal IDs.

Response properties

message string

Success message.

JSON

Response 200 (single proposal)

{
  "success": true,
  "data": {
    "message": "sampleProposal deleted successfully."
  }
}

Response 200 (multiple proposals)

{
  "success": true,
  "data": {
    "message": "2 Proposals deleted successfully"
  }
}

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: {
          message: string
        }
      };
    };
  };
}

function softDeleteProposal(): Promise<Responses> {
  const options = {
    method: 'DELETE',
    url: 'https://api.iqm.com/api/v3/plan/proposal',
    params: {
      query: {
        proposalIds: `string`
      }
    }
  };

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

More details

Proposal status list

GET

Get a list of proposal status IDs.

Query parameters
plannerTypeId integer	Planner type ID. Supported values: 1 (Political Planner) and 2 (HCP Planner).

Response properties

proposalStatusList object	Proposal status list details.
proposalStatusList object properties name string Status name. id integer Status ID. label string Status label. order integer Order.

JSON

Response 200 (plannerTypeId=1, Generic Planner)

{
  "success": true,
  "data": {
    "totalRecords": 6,
    "filteredRecords": 6,
    "proposalStatusList": [
      {
        "name": "draft",
        "id": 2,
        "label": "Draft",
        "order": 1
      },
      {
        "name": "ready",
        "id": 6,
        "label": "Ready",
        "order": 2
      },
      {
        "name": "expired",
        "id": 3,
        "label": "Expired",
        "order": 3
      },
      {
        "name": "processing",
        "id": 5,
        "label": "Processing",
        "order": 4
      },
      {
        "name": "converted",
        "id": 1,
        "label": "Converted",
        "order": 5
      },
      {
        "name": "failed",
        "id": 4,
        "label": "Failed",
        "order": 6
      }
    ]
  }
}

Response 200 (plannerTypeId=2, HCP Planner)

{
  "success": true,
  "data": {
    "totalRecords": 5,
    "filteredRecords": 5,
    "proposalStatusList": [
      {
        "id": 2,
        "name": "draft",
        "order": 1,
        "label": "Draft"
      },
      {
        "id": 6,
        "name": "ready",
        "order": 2,
        "label": "Ready"
      },
      {
        "id": 5,
        "name": "processing",
        "order": 4,
        "label": "Processing"
      },
      {
        "id": 4,
        "name": "failed",
        "order": 6,
        "label": "Failed"
      },
      {
        "id": 7,
        "name": "io_created",
        "order": 7,
        "label": "IO Created"
      }
    ]
  }
}

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;
          proposalStatusList: {
            name: string;
            id: number;
            label: string;
            order: number;
          }[];
        }
      };
    };
  };
}

function ProposalStatusList(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/plan/static/proposal/status',
    params: {
      query: {
        plannerTypeId: `number`,
      },
    },
  };

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

---

Proposal summary parameters list

GET

Get a list of supported parameters for proposal summaries.

JSON

Response 200

{
  "success": true,
  "data": {
    "bidLandscape": {
      "location": {
        "countryIds": true,
        "cityIds": true,
        "countyIds": true,
        "senateDistrictIds": true,
        "houseDistrictIds": true,
        "congressionalDistrictIds": true,
        "dmaIds": true,
        "zipCodes": true
      },
      "deviceTypes": true,
      "creativeTypes": true,
      "channelTypes": true,
      "segmentIds": true,
      "inventory": false
    },
    "deviceGraph": {
      "location": {
        "countryIds": true,
        "cityIds": true,
        "countyIds": true,
        "senateDistrictIds": true,
        "houseDistrictIds": true,
        "congressionalDistrictIds": true,
        "dmaIds": true,
        "zipCodes": true
      },
      "deviceTypes": true,
      "creativeTypes": true,
      "channelTypes": true,
      "segmentIds": true,
      "inventory": false
    },
    "channelGraph": {
      "location": {
        "countryIds": true,
        "cityIds": true,
        "countyIds": true,
        "senateDistrictIds": true,
        "houseDistrictIds": true,
        "congressionalDistrictIds": true,
        "dmaIds": true,
        "zipCodes": true
      },
      "deviceTypes": true,
      "creativeTypes": true,
      "channelTypes": true,
      "segmentIds": true,
      "inventory": false
    },
    "reachImpressions": {
      "location": {
        "countryIds": true,
        "cityIds": true,
        "countyIds": true,
        "senateDistrictIds": true,
        "houseDistrictIds": true,
        "congressionalDistrictIds": true,
        "dmaIds": true,
        "zipCodes": true
      },
      "deviceTypes": true,
      "creativeTypes": true,
      "channelTypes": true,
      "segmentIds": true,
      "inventory": false
    }
  }
}

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: {
          bidLandscape: {
            location: {
              countryIds: boolean;
              cityIds: boolean;
              countyIds: boolean;
              senateDistrictIds: boolean;
              houseDistrictIds: boolean;
              congressionalDistrictIds: boolean;
              dmaIds: boolean;
              zipCodes: boolean;
            };
            deviceTypes: boolean;
            creativeTypes: boolean;
            channelTypes: boolean;
            segmentIds: boolean;
            inventory: boolean;
          };
          deviceGraph: {
            location: {
              countryIds: boolean;
              cityIds: boolean;
              countyIds: boolean;
              senateDistrictIds: boolean;
              houseDistrictIds: boolean;
              congressionalDistrictIds: boolean;
              dmaIds: boolean;
              zipCodes: boolean;
            };
            deviceTypes: boolean;
            creativeTypes: boolean;
            channelTypes: boolean;
            segmentIds: boolean;
            inventory: boolean;
          };
          channelGraph: {
            location: {
              countryIds: boolean;
              cityIds: boolean;
              countyIds: boolean;
              senateDistrictIds: boolean;
              houseDistrictIds: boolean;
              congressionalDistrictIds: boolean;
              dmaIds: boolean;
              zipCodes: boolean;
            };
            deviceTypes: boolean;
            creativeTypes: boolean;
            channelTypes: boolean;
            segmentIds: boolean;
            inventory: boolean;
          };
          reachImpressions: {
            location: {
              countryIds: boolean;
              cityIds: boolean;
              countyIds: boolean;
              senateDistrictIds: boolean;
              houseDistrictIds: boolean;
              congressionalDistrictIds: boolean;
              dmaIds: boolean;
              zipCodes: boolean;
            };
            deviceTypes: boolean;
            creativeTypes: boolean;
            channelTypes: boolean;
            segmentIds: boolean;
            inventory: boolean;
          }
        }
      };
    };
  };
}

function getSupportedParameters(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/plan/proposal-summary/supported-params',
  };

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

---

Get user access details

GET

Get user access details of logged-in Organization's parent Organizations.

Response properties

parentOrganisationAccess boolean	Checks if user has access to the Advertiser: true.
adminOrganisationAccess boolean	Checks if user has access to the Workspace and Advertiser: true.
marginValue integer	The Customer/Workspace's default gross margin percentage, sourced from Finance, a suggested default to pre-fill when creating a proposal, not the same field as a specific proposal's own margin/marginValue (see Create proposal).

JSON

Response 200

{
  "success": true,
  "data": {
    "parentOrganisationAccess": true,
    "adminOrganisationAccess": true,
    "marginValue": 6
  }
}

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: {
          parentOrganisationAccess: boolean;
          adminOrganisationAccess: boolean;
          marginValue: number;
        }
      };
    };
  };
}

function getDefaultCustomerMargin(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/plan/proposal/margin',
  };

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