Skip to main content

Planner API

This page covers the methods and endpoints associated with Political proposal Planners. With the Planner API you can create, retrieve, update, and manage proposal Planners for Political campaigns.

Read more about Political Planners in our Help Center article.

For a step-by-step walkthrough, see the Political Planner tutorial.

Political proposal Planner details​

Political Planner resource properties​

Plan resource properties
id
integer		Plan ID.
name
string		Plan name.
objectiveId
integer		Plan objective ID.
Supported values
1Reach forecasting
2Budget estimation
3Voter TV+
graphId
string		Cross-screen graph ID from Get reach saturation graph. Required for Voter TV+ plans.
overview
object		Linear TV and CTV assumptions from Get reach saturation graph. Voter TV+ plans only; defaults are used if omitted.
overview object properties
linearTvCpm
number		Linear TV cost per thousand impressions.
ctvCpm
number		CTV cost per thousand impressions.
grp
number		Gross rating points.
linearTvPercentage
integer		Percentage of budget allocated to linear TV.
ctvFrequency
integer		Average CTV frequency.
totalBudget
number		Total plan budget.
details
object		Plan details object.
details object properties
startDate
integer		Unix epoch start date, in milliseconds.
endDate
integer		Unix epoch end date, in milliseconds.
timezoneId
integer		Timezone ID. Replaced with the Organization's timezone.
frequencyCap
integer		Frequency cap.
marginValue
integer		Margin applied on top of the base CPM, as a percentage from 0 to 100 (not a currency amount). Defaults to the Customer's margin.
statusId
integer		Plan status ID.
Supported values
1Draft
2Ready
cva
object		Custom Voter audience (CVA) to target. All five properties are required.
cva object properties
id
integer		CVA ID from Create CVA details.
equation
string		Segment equation sent when the CVA was created.
stateIds
array of integers		State IDs sent when the CVA was created.
segmentIds
array of integers		Numeric segmentId values of the segments in the equation, from Get Custom Voter audience segment details.
reach
integer		Audience reach: segment_num_voters from Get CVA reach.
targeting
object		Targeting object.
targeting object properties
whiteListedLocation
object		Whitelisted location targeting.
whiteListedLocation object properties
country
integer		Country ID.
states
array of integers		State IDs.
dma
array of integers		DMA IDs.
city
array of integers		City IDs.
county
array of integers		County IDs.
congressionalDistrict
array of integers		Congressional district IDs.
stateHouse
array of integers		State house IDs.
stateSenate
array of integers		State senate IDs.
zipCodes
array of strings		ZIP codes.
blackListedLocation
object		Blacklisted location targeting (same structure as whitelisted).
device
object		Device targeting.
device object properties
deviceTypeIds
array of integers		Device type IDs.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
channelTypeIds
array of integers		Channel type IDs.
Supported values
11App
14CTV
13OTT
12Web
inventory
object		Inventory targeting.
inventory object properties
openExchange
object		Open Exchange targeting.
inventoryGroupIds
array of integers		Inventory Group IDs.
creative
object		Creative targeting.
creative object properties
creativeTypeIds
array of integers		Creative type IDs.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
isTvAutoBuying
boolean		Indicates CTV auto-buying is enabled.
whitelistedAudiences
array of integers		Whitelisted audience IDs. Power Segment audiences are supported, except for Voter TV+ plans (objectiveId: 3).
blacklistedAudiences
array of integers		Blacklisted audience IDs. Power Segment audiences are supported, except for Voter TV+ plans (objectiveId: 3).
prebidSegments
array of integers		Prebid segment IDs.
audienceSegments
array of integers		Audience segment IDs.
ageGroupSegments
array of integers		Age group segment IDs (cross-screen plans only, see Get demographics keys).
genderSegments
array of integers		Gender segment IDs (cross-screen plans only, see Get demographics keys).
incomeRangeSegments
array of integers		Income range segment IDs (cross-screen plans only, see Get demographics keys).
ethnicitySegments
array of integers		Ethnicity segment IDs (cross-screen plans only, see Get demographics keys).
partyAffiliationSegments
array of integers		Party affiliation segment IDs (cross-screen plans only, see Get demographics keys).
advanced
object		Advanced targeting.
advanced object properties
splitTypeId
integer		Split type ID.
Supported values
1AI
2Manual
locations
array of integers		Targeting type IDs for locations.
Supported values
1Location
devices
array of integers		Device type IDs.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
inventoryGroupIds
array of integers		Inventory Group IDs.
audienceTypes
array of integers		Audience type IDs.
Supported values
1Matched audience
2Segmented audience
3Retargeted audience
4Geofarmed audience
5Contextual audience
6Lookalike audience
7Campaign audience
8Pre-bid audience
9Account Based Marketing (ABM) audience
10Custom Voter audience (CVA)
11Integrated Care Team (ICT) audience
12Power Segment audience
creatives
array of integers		Creative type IDs.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio

Proposal resource properties
id
integer		Proposal ID.
name
string		Proposal name.
objectiveId
integer		Plan objective ID.
Supported values
1Reach forecasting
2Budget estimation
3Voter TV+
planId
integer		Plan ID the proposal was created from.
planName
string		Plan name.
startTime
integer		Unix epoch start date, in milliseconds.
endTime
integer		Unix epoch end date, in milliseconds.
statusId
integer		Proposal status ID.
Supported values
1Converted
2Draft
3Expired
4Failed
5Processing
6Ready
7IO Created
ioId
integer		Insertion order (IO) ID, set when the proposal is converted.
reach
integer		Estimated reach.
impressions
integer		Estimated impressions.
budget
number		Proposal budget.
frequencyCap
integer		Frequency cap.
minReach
integer		Minimum reach.
minImpressions
integer		Minimum impressions.
minBudget
number		Minimum budget.
maxReach
integer		Maximum reach.
maxImpressions
integer		Maximum impressions.
maxBudget
number		Maximum budget.
minCpm
number		Minimum cost per thousand impressions; can be null at the proposal level.
cpm
number		Cost per thousand impressions; can be null at the proposal level. Each proposed campaign has its own CPM.
maxCpm
number		Maximum cost per thousand impressions; can be null at the proposal level.
campaignGeneratable
boolean		Whether an IO and campaigns can be generated from the proposal. Only meaningful while the proposal is Ready or Failed; it isn't reset after the proposal is converted.
timeZoneId
integer		Timezone ID.
timeZoneName
string		Timezone name.
linearTvReach
integer		Linear TV reach (cross-screen proposals only).
linearTvImpressions
integer		Linear TV impressions (cross-screen proposals only).
linearTvBudget
number		Linear TV budget (cross-screen proposals only).
linearTvMaxReach
integer		Maximum linear TV reach (cross-screen proposals only).
linearTvMaxImpressions
integer		Maximum linear TV impressions (cross-screen proposals only).
linearTvMaxBudget
number		Maximum linear TV budget (cross-screen proposals only).
linearTvCpm
number		Linear TV cost per thousand impressions (cross-screen proposals only).
proposedCampaigns
array of objects		Proposed campaigns.
proposedCampaigns object properties
id
integer		Proposed campaign ID.
name
string		Campaign name.
type
string		Voter TV+ proposals only: CTV or Linear TV. Only CTV campaigns are created when the IO is generated. null for other proposals.
startTime
integer		Unix epoch start date, in milliseconds.
endTime
integer		Unix epoch end date, in milliseconds.
creativeTypeId
integer		Creative type ID.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
duration
integer		Duration in days.
modelType
string		Bidding model type (e.g., CPM).
minTargetedReach
integer		Minimum targeted reach.
targetedReach
integer		Targeted reach.
maxTargetedReach
integer		Maximum targeted reach.
frequencyCap
integer		Campaign frequency cap.
minTargetedImpressions
integer		Minimum targeted impressions.
targetedImpressions
integer		Targeted impressions.
maxTargetedImpressions
integer		Maximum targeted impressions.
cpm
number		Cost per thousand impressions.
minCpm
number		Minimum CPM.
maxCpm
number		Maximum CPM.
minBudget
number		Minimum campaign budget.
budget
number		Campaign budget.
maxBudget
number		Maximum campaign budget.
strategy
string		Targeting dimensions the campaign was split by.

Get plan details by ID​

GET

Get Political proposal Planner details by plan ID.

Path parameters
planId
integer		Plan ID.
Response 200
{
  "success": true,
  "data": {
    "id": 1,
    "name": "Pollies Political Planner",
    "objectiveId": 1,
    "totalBudget": 120000,
    "details": {
      "startDate": 1747195200000,
      "endDate": 1777089600000,
      "timezoneId": 29,
      "frequencyCap": 3
    },
    "owId": 204366,
    "statusId": 1,
    "lastVisitedScreen": "Screen 1",
    "cva": {
      "id": 1,
      "equation": "((IQMCVAAL017144|IQMCVAAL086142))",
      "stateIds": [30200012, 30200013, 30200014, 30200015],
      "segmentIds": [88432, 18589],
      "reach": 293180
    },
    "targeting": {
      "whiteListedLocation": {
        "country": 30100001,
        "states": [30200035],
        "dma": [30900026],
        "city": [30436781, 30436782],
        "county": [30318981],
        "congressionalDistrict": [30617273],
        "stateHouse": [30803564],
        "stateSenate": [30718340],
        "zipCodes": ["10002"]
      },
      "blackListedLocation": {
        "country": 30100001,
        "states": [30200003],
        "dma": [30900139],
        "city": [30442811],
        "county": [30321244],
        "congressionalDistrict": [30601009],
        "stateHouse": [30800263],
        "stateSenate": [30701056],
        "zipCodes": ["10002"]
      },
      "device": {
        "deviceTypeIds": [20300004, 20300003],
        "channelTypeIds": [11, 12]
      },
      "inventory": {
        "openExchange": null,
        "inventoryGroupIds": [3904859, 3897153]
      },
      "creative": {
        "creativeTypeIds": [11, 13],
        "isTvAutoBuying": true
      },
      "whitelistedAudiences": [1142625, 1143191, 1156665, 1144602, 1157452, 1159375],
      "blacklistedAudiences": [1140931, 1142626, 1143189, 1144600, 1157451, 1159357, 1142239],
      "prebidSegments": [32, 422],
      "audienceSegments": [323, 232, 12],
      "advanced": {
        "splitTypeId": 1,
        "locations": [8, 9, 10],
        "devices": [20300004, 20300003],
        "inventoryGroupIds": [3904859, 3897153],
        "audienceTypes": [18, 19],
        "creatives": [11, 13]
      }
    }
  }
}
Response 200
{
  "success": true,
  "data": {
    "id": 1,
    "name": "Pollies Political Planner",
    "objectiveId": 3,
    "graphId": "550e8400-e29b-41d4-a716-446655440000",
    "overview": {
      "linearTvCpm": 12,
      "ctvCpm": 8,
      "grp": 45,
      "linearTvPercentage": 65,
      "ctvFrequency": 3
    },
    "totalBudget": 120000,
    "details": {
      "startDate": 1747195200000,
      "endDate": 1777089600000,
      "timezoneId": 29,
      "frequencyCap": 3
    },
    "owId": 204366,
    "statusId": 1,
    "lastVisitedScreen": "Screen 1",
    "cva": {
      "id": 1,
      "equation": "((IQMCVAAL017144|IQMCVAAL086142))",
      "stateIds": [30200012, 30200013, 30200014, 30200015],
      "segmentIds": [88432, 18589],
      "reach": 293180
    },
    "targeting": {
      "whiteListedLocation": {
        "country": 30100001,
        "states": [30200035],
        "dma": [30900026],
        "city": [30436781, 30436782],
        "county": [30318981],
        "congressionalDistrict": [30617273],
        "stateHouse": [30803564],
        "stateSenate": [30718340],
        "zipCodes": ["10002"]
      },
      "blackListedLocation": {
        "country": 30100001,
        "states": [30200003],
        "dma": [30900139],
        "city": [30442811],
        "county": [30321244],
        "congressionalDistrict": [30601009],
        "stateHouse": [30800263],
        "stateSenate": [30701056],
        "zipCodes": ["10002"]
      },
      "device": {
        "deviceTypeIds": [20300004, 20300003],
        "channelTypeIds": [11, 12]
      },
      "inventory": {
        "openExchange": null,
        "inventoryGroupIds": [3904859, 3897153]
      },
      "creative": {
        "creativeTypeIds": [11, 13],
        "isTvAutoBuying": true
      },
      "whitelistedAudiences": [1142625, 1143191, 1156665, 1144602, 1157452, 1159375],
      "blacklistedAudiences": [1140931, 1142626, 1143189, 1144600, 1157451, 1159357, 1142239],
      "prebidSegments": [32, 422],
      "audienceSegments": [323, 232, 12],
      "ageGroupSegments": [101, 102, 103],
      "genderSegments": [201, 202],
      "incomeRangeSegments": [301, 302, 303],
      "ethnicitySegments": [401, 402],
      "partyAffiliationSegments": [501, 502],
      "advanced": {
        "splitTypeId": 1,
        "locations": [8, 9, 10],
        "devices": [20300004, 20300003],
        "inventoryGroupIds": [3904859, 3897153],
        "audienceTypes": [18, 19],
        "creatives": [11, 13]
      }
    }
  }
}

Download plan​

GET

Generate a signed URL for downloading a Political plan report in PDF format.

Path parameters
planId
integer required		Plan ID to download.
Query parameters
fileType
integer required		File type ID.
Supported values
3PDF
Response 200
{
  "success": true,
  "data": {
    "planReportUrl": "https://example.s3.amazonaws.com/planner/plan/report/download/12345/plan_report.pdf"
  }
}
More responses
Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Invalid File type"
    }
  ]
}

Get list of Political plans​

GET

Get a paginated list of Political plans.

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

Query parameters
pageNo
integer		Page number of retrieved data, default: 1.
noOfEntries
integer		Number of entries returned per page, default: 50.
searchField
string		Search by plan name, ID, or created by user name.
sortBy
string		Sorts by ascending (+) or descending (-), default: -id.
Supported values: id, name, createdOn, createdBy, startDate, endDate, objectiveId, totalProposals, duration.
statusIds
string		Comma-separated status IDs.
Supported values
1Draft
2Ready
objectiveIds
string		Comma-separated objective IDs.
Supported values
1Reach forecasting
2Budget estimation
3Voter TV+
Response properties
id
integer		Plan ID.
name
string		Plan name.
statusId
integer		Plan status ID.
Supported values
1Draft
2Ready
createdOn
integer		Unix epoch created on date, in milliseconds.
createdBy
string		Created by user name.
userAvatarUrl
string		URL of the user avatar.
startDate
integer		Unix epoch start date, in milliseconds.
endDate
integer		Unix epoch end date, in milliseconds.
objectiveId
integer		Plan objective ID.
Supported values
1Reach forecasting
2Budget estimation
3Voter TV+
totalProposals
integer		Number of linked proposals.
proposals
array of integers		Linked proposal IDs.
Response 200
{
  "success": true,
  "data": {
    "data": [
      {
        "id": 1001,
        "name": "Q1 2026 Campaign Strategy",
        "statusId": 1,
        "createdOn": 1709654400000,
        "createdByUowId": 5001,
        "createdBy": "John Smith",
        "userAvatarUrl": "https://example.com/avatars/john-smith.png",
        "startDate": 1709654400000,
        "endDate": 1717430400000,
        "objectiveId": 1,
        "totalProposals": 3,
        "proposals": [12, 231, 245]
      },
      {
        "id": 1002,
        "name": "Voter Outreach Initiative",
        "statusId": 2,
        "createdOn": 1710259200000,
        "createdByUowId": 5002,
        "createdBy": "Jane Doe",
        "userAvatarUrl": "https://example.com/avatars/jane-doe.png",
        "startDate": 1710259200000,
        "endDate": 1718640000000,
        "objectiveId": 2,
        "totalProposals": 5,
        "proposals": [12, 231, 323, 445, 568]
      }
    ],
    "totalRecords": 25,
    "filteredRecords": 2
  }
}

Get list of proposals​

GET

Get a paginated list of Political proposals with comprehensive metadata including budget metrics, strategy type, creator details, and date ranges.

Query parameters
pageNo
integer		Page number of retrieved data, default: 1.
noOfEntries
integer		Number of entries returned per page, default: 50.
searchField
string		Search by proposal name, ID, or created by user name.
sortBy
string		Sorts by ascending (+) or descending (-), default: -id.
Supported values: id, name, createdOn, createdBy, startDate, endDate, reach, impressions, cpm, budget, frequency.
statusIds
string		Comma-separated status IDs.
Supported values
1Converted
2Draft
3Expired
4Failed
5Processing
6Ready
7IO Created
planId
integer		Filter proposals by plan ID.
Response properties
id
integer		Proposal ID.
name
string		Proposal name.
statusId
integer		Proposal status ID.
Supported values
1Converted
2Draft
3Expired
4Failed
5Processing
6Ready
7IO Created
ioId
integer		Insertion order ID.
createdOn
integer		Unix epoch created on date, in milliseconds.
createdBy
string		Created by user name.
userAvatarUrl
string		URL of the user avatar.
startDate
integer		Unix epoch start date, in milliseconds.
endDate
integer		Unix epoch end date, in milliseconds.
timezoneId
integer		Timezone ID of the proposal.
reach
integer		Estimated reach.
impressions
integer		Estimated impressions.
cpm
number		Cost per thousand impressions.
budget
number		Proposal budget.
frequency
integer		Frequency cap.
strategyTypeId
integer		Strategy type ID.
Supported values
1Maximum Reach
2Maximum Impressions
3Balanced
4Most Economical
5Custom
linearTvReach
integer		Linear TV reach (cross-screen proposals only, null otherwise).
linearTvImpressions
integer		Linear TV impressions (cross-screen proposals only, null otherwise).
linearTvBudget
number		Linear TV budget (cross-screen proposals only, null otherwise).
Response 200
{
  "success": true,
  "data": {
    "data": [
      {
        "id": 2001,
        "name": "Q1 2026 Digital Campaign",
        "statusId": 1,
        "ioId": 1,
        "createdOn": 1709654400000,
        "createdByUserId": 5001,
        "createdBy": "John Smith",
        "userAvatarUrl": "https://example.com/avatars/john-smith.png",
        "startDate": 1709654400000,
        "endDate": 1717430400000,
        "timezoneId": 29,
        "reach": 500000,
        "impressions": 2000000,
        "cpm": 15.50,
        "budget": 31000.00,
        "frequency": 3,
        "strategyTypeId": 1,
        "linearTvReach": null,
        "linearTvImpressions": null,
        "linearTvBudget": null
      },
      {
        "id": 2002,
        "name": "Voter Engagement Initiative",
        "statusId": 2,
        "ioId": null,
        "createdOn": 1710259200000,
        "createdByUserId": 5002,
        "createdBy": "Jane Doe",
        "userAvatarUrl": "https://example.com/avatars/jane-doe.png",
        "startDate": 1710259200000,
        "endDate": 1718640000000,
        "timezoneId": 5,
        "reach": 750000,
        "impressions": 3000000,
        "cpm": 12.75,
        "budget": 38250.00,
        "frequency": 4,
        "strategyTypeId": 2,
        "linearTvReach": null,
        "linearTvImpressions": null,
        "linearTvBudget": null
      }
    ],
    "totalRecords": 45,
    "filteredRecords": 2,
    "recordsAggregation": {
      "totalBudget": 69250
    }
  }
}
Response 200
{
  "success": true,
  "data": {
    "data": [
      {
        "id": 2001,
        "name": "Q1 2026 Digital Campaign",
        "statusId": 1,
        "ioId": 1,
        "createdOn": 1709654400000,
        "createdByUserId": 5001,
        "createdBy": "John Smith",
        "userAvatarUrl": "https://example.com/avatars/john-smith.png",
        "startDate": 1709654400000,
        "endDate": 1717430400000,
        "timezoneId": 29,
        "reach": 500000,
        "impressions": 2000000,
        "cpm": 15.50,
        "budget": 31000.00,
        "frequency": 3,
        "strategyTypeId": 1,
        "linearTvReach": 232322,
        "linearTvImpressions": 3245,
        "linearTvBudget": 23232323
      },
      {
        "id": 2002,
        "name": "Voter Engagement Initiative",
        "statusId": 2,
        "ioId": null,
        "createdOn": 1710259200000,
        "createdByUserId": 5002,
        "createdBy": "Jane Doe",
        "userAvatarUrl": "https://example.com/avatars/jane-doe.png",
        "startDate": 1710259200000,
        "endDate": 1718640000000,
        "timezoneId": 5,
        "reach": 750000,
        "impressions": 3000000,
        "cpm": 12.75,
        "budget": 38250.00,
        "frequency": 4,
        "strategyTypeId": 2,
        "linearTvReach": 232322,
        "linearTvImpressions": 3245,
        "linearTvBudget": 23232323
      }
    ],
    "totalRecords": 45,
    "filteredRecords": 2,
    "recordsAggregation": {
      "totalBudget": 69250
    }
  }
}

Get proposal details​

GET

Get the complete details of a Political proposal including budgeting metrics, timezone info, and proposed campaigns.

Path parameters
proposalId
integer		Proposal ID.
Response 200
{
  "success": true,
  "data": {
    "id": 14,
    "name": "sample",
    "planId": 2,
    "planName": "sample",
    "objectiveId": 1,
    "startTime": 1730658720000,
    "endTime": 1733250720000,
    "owId": 202500,
    "statusId": 1,
    "ioId": 1,
    "reach": 122344433,
    "impressions": 12232323,
    "budget": 1212233.23,
    "frequencyCap": 3,
    "maxReach": 200000000,
    "maxImpressions": 25000000,
    "maxBudget": 2500000,
    "minCpm": null,
    "cpm": null,
    "maxCpm": null,
    "campaignGeneratable": true,
    "timeZoneId": 29,
    "timeZoneName": "US/EASTERN",
    "proposedCampaigns": [
      {
        "id": 101,
        "name": "Sample Campaign",
        "type": null,
        "startTime": 1747195200000,
        "endTime": 1777089600000,
        "creativeTypeId": 13,
        "duration": 30,
        "modelType": "CPM",
        "targetedReach": 500000,
        "maxTargetedReach": 750000,
        "frequencyCap": 3,
        "targetedImpressions": 1500000,
        "maxTargetedImpressions": 2000000,
        "cpm": 2.5,
        "minCpm": 1.5,
        "maxCpm": 3.5,
        "budget": 10000,
        "maxBudget": 15000,
        "strategy": "Device + Channel"
      }
    ]
  }
}
Response 200
{
  "success": true,
  "data": {
    "id": 15,
    "name": "Voter TV+ Plan_Mix_01",
    "planId": 3,
    "planName": "Voter TV+ Plan",
    "objectiveId": 3,
    "startTime": 1730658720000,
    "endTime": 1733250720000,
    "owId": 202500,
    "statusId": 6,
    "ioId": null,
    "reach": 122344433,
    "impressions": 12232323,
    "budget": 1212233.23,
    "frequencyCap": 3,
    "maxReach": 200000000,
    "maxImpressions": 25000000,
    "maxBudget": 2500000,
    "minCpm": null,
    "cpm": null,
    "maxCpm": null,
    "campaignGeneratable": true,
    "timeZoneId": 29,
    "timeZoneName": "US/EASTERN",
    "linearTvReach": 1000,
    "linearTvImpressions": 2000,
    "linearTvBudget": 1001,
    "linearTvMaxReach": 10000,
    "linearTvMaxImpressions": 20000,
    "linearTvMaxBudget": 10002,
    "proposedCampaigns": [
      {
        "id": 101,
        "name": "Voter TV+ Plan_Mix_01_VTV + Video",
        "type": "Linear TV",
        "startTime": 1730658720000,
        "endTime": 1733250720000,
        "creativeTypeId": 14,
        "duration": 30,
        "modelType": "CPM",
        "targetedReach": 500000,
        "maxTargetedReach": 750000,
        "frequencyCap": 3,
        "targetedImpressions": 1500000,
        "maxTargetedImpressions": 2000000,
        "cpm": 20,
        "minCpm": 15,
        "maxCpm": 25,
        "budget": 10000,
        "maxBudget": 15000,
        "strategy": "VTV + Video"
      },
      {
        "id": 102,
        "name": "Voter TV+ Plan_Mix_01_Video",
        "type": "CTV",
        "startTime": 1730658720000,
        "endTime": 1733250720000,
        "creativeTypeId": 14,
        "duration": 30,
        "modelType": "CPM",
        "targetedReach": 500000,
        "maxTargetedReach": 750000,
        "frequencyCap": 3,
        "targetedImpressions": 1500000,
        "maxTargetedImpressions": 2000000,
        "cpm": 7,
        "minCpm": 5,
        "maxCpm": 9,
        "budget": 10000,
        "maxBudget": 15000,
        "strategy": "Video"
      }
    ]
  }
}

Download proposal​

GET

Generate a signed URL for downloading a Political proposal report in CSV, XLSX, or PDF format.

The target proposal must currently have status ID 1 (Converted), 3 (Expired), 4 (Failed), or 6 (Ready).

Path parameters
proposalId
integer		Proposal ID.
Query parameters
fileType
integer		Type of file to download.
Supported values
1Excel
2CSV
3PDF
Response 200
{
  "success": true,
  "data": {
    "proposalReportUrl": "https://example.s3.amazonaws.com/planner/proposal/report/download/12345/proposal_report.xlsx"
  }
}

Get proposal summary​

GET

Get a proposal summary including reach/impressions, bid landscape, device graph, and channel graph data.

Path parameters
proposalId
integer		Proposal ID.
Response properties
reachImpressions
object		Reach and impressions summary.
reachImpressions object properties
impressions
integer		Total impressions.
reach
integer		Total reach.
iqmReach
integer		IQM estimated reach.
bidLandscape
object		Bid landscape data grouped by creative type.
bidLandscape object properties
cpm
number		CPM value.
percentile
integer		Percentile.
impressions
integer		Impressions at this CPM.
deviceGraph
object		Device type distribution.
deviceGraph object properties
device
string		Device type name.
impressions
integer		Impressions for device type.
percentage
number		Percentage of total.
channelGraph
object		Channel type distribution.
channelGraph object properties
channel
string		Channel type name.
impressions
integer		Impressions for channel type.
percentage
number		Percentage of total.
Response 200
{
  "success": true,
  "data": {
    "reachImpressions": {
      "impressions": 23213,
      "reach": 10,
      "iqmReach": 206567705
    },
    "bidLandscape": {
      "Audio": [
        { "cpm": 0, "percentile": 0, "impressions": 0 },
        { "cpm": 2, "percentile": 10, "impressions": 1261382900 }
      ]
    },
    "deviceGraph": {
      "deviceTypes": [
        { "device": "CTV", "impressions": 94828374242, "percentage": 50.53 }
      ]
    },
    "channelGraph": {
      "channelTypes": [
        { "channel": "CTV", "impressions": 47780138694, "percentage": 25.46 }
      ]
    }
  }
}

Get list of strategies​

GET

Get a list of strategies for a specific plan, including campaign metrics, budgeting data, and targeting arrays.

The forecasting service generates up to three strategies for a ready plan, and can return fewer. Strategies created with Generate custom strategies are also listed. Use the id from this endpoint as the strategyId in Activate proposal.

Query parameters
planId
integer required		The plan ID to retrieve strategies for.
Response properties
id
integer		Strategy ID.
name
string		Strategy name.
startDate
integer		Unix epoch start date, in milliseconds.
endDate
integer		Unix epoch end date, in milliseconds.
duration
integer		Duration in days.
strategyTypeId
integer		Strategy type ID.
Supported values
1Maximum Reach
2Maximum Impressions
3Balanced
4Most Economical
5Custom
campaignsCount
integer		Number of campaigns.
proposalId
integer		Proposal ID created from this strategy, or null if it hasn't been activated.
budget
number		Forecasted budget. Can differ from the plan's totalBudget.
frequency
integer		Forecasted frequency cap. Can differ from the plan's frequencyCap.
reach
integer		Estimated reach.
impressions
integer		Estimated impressions.
cpm
number		Cost per thousand impressions.
creatives
array of integers		Creative type IDs selected by the forecasting service. Can be a subset of the plan's creative types.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
devices
array of integers		Device type IDs.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
channels
array of integers		Channel type IDs.
Supported values
11App
14CTV
13OTT
12Web
isTvAutoBuying
boolean		Indicates CTV auto-buying is enabled.
Response 200
{
  "success": true,
  "data": [
    {
      "id": 3001,
      "name": "Maximum Reach",
      "startDate": 1793595600000,
      "endDate": 1796187600000,
      "duration": 30,
      "strategyTypeId": 1,
      "campaignsCount": 4,
      "proposalId": null,
      "budget": 50000,
      "frequency": 3,
      "reach": 1250000,
      "impressions": 2220000,
      "cpm": 22.52,
      "creatives": [11, 14],
      "devices": [20300001, 20300004],
      "channels": [11, 12, 13, 14],
      "isTvAutoBuying": false
    }
  ]
}

Get strategy details​

GET

Get the details of a single Political strategy by ID.

Path parameters
strategyId
integer		Strategy ID.
Response properties
id
integer		Strategy ID.
name
string		Strategy name.
startDate
integer		Unix epoch start date, in milliseconds.
endDate
integer		Unix epoch end date, in milliseconds.
duration
integer		Duration in days.
strategyTypeId
integer		Strategy type ID.
Supported values
1Maximum Reach
2Maximum Impressions
3Balanced
4Most Economical
5Custom
campaignsCount
integer		Number of campaigns.
budget
number		Strategy budget.
frequency
integer		Frequency cap.
reach
integer		Estimated reach.
impressions
integer		Estimated impressions.
cpm
number		Cost per thousand impressions.
creatives
array of integers		Creative type IDs.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
devices
array of integers		Device type IDs.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
channels
array of integers		Channel type IDs.
Supported values
11App
14CTV
13OTT
12Web
Response 200
{
  "success": true,
  "data": {
    "id": 3001,
    "name": "sample strategy",
    "startDate": 1709654400000,
    "endDate": 1717430400000,
    "duration": 10,
    "strategyTypeId": 1,
    "campaignsCount": 5,
    "budget": 50000,
    "frequency": 3,
    "reach": 750000,
    "impressions": 2250000,
    "cpm": 22.22,
    "creatives": [11, 14],
    "devices": [20300001, 20300004],
    "channels": [11, 12, 13, 14]
  }
}

Political proposal Planner management​

Create plan​

POST
POST

Create a new ready or draft Political plan. A ready plan requires name, details, and targeting. A Voter TV+ (objectiveId: 3) plan requires the graphId from Get reach saturation graph; overview is optional.

A draft plan requires only a name; all other fields are optional but validated if present.

note

The forecasting service decides which targeting and budget combinations can be planned, and there is no fixed list of valid combinations. A plausible request can still be rejected (response 422). If this happens, nothing is created: widen the targeting or change the budget and try again.

See resource properties for request schema.

Request sample
{
  "name": "Plan Name",
  "objectiveId": 2,
  "totalBudget": 120000,
  "details": {
    "startDate": 1747195200000,
    "endDate": 1777089600000,
    "frequencyCap": 3
  },
  "targeting": {
    "whiteListedLocation": {
      "country": 30100001,
      "states": [30200035],
      "dma": [30900026],
      "city": [30436781, 30436782],
      "county": [30318981],
      "congressionalDistrict": [30617273],
      "stateHouse": [30803564],
      "stateSenate": [30718340],
      "zipCodes": ["10001"]
    },
    "blackListedLocation": {
      "country": 30100001,
      "states": [30200003],
      "dma": [30900139],
      "city": [30442811],
      "county": [30321244],
      "congressionalDistrict": [30601009],
      "stateHouse": [30800263],
      "stateSenate": [30701056],
      "zipCodes": ["10002"]
    },
    "device": {
      "deviceTypeIds": [20300004, 20300003],
      "channelTypeIds": [11, 12]
    },
    "inventory": {
      "openExchange": null,
      "inventoryGroupIds": [3904859, 3897153]
    },
    "creative": {
      "creativeTypeIds": [11, 13],
      "isTvAutoBuying": true
    },
    "whitelistedAudiences": [1142625, 1143191, 1156665, 1144602, 1157452, 1159375],
    "blacklistedAudiences": [1140931, 1142626, 1143189, 1144600, 1157451, 1159357, 1142239],
    "prebidSegments": [32, 422],
    "audienceSegments": [323, 232, 12],
    "advanced": {
      "locations": [8, 9, 10],
      "devices": [20300004, 20300003],
      "inventoryGroupIds": [3904859, 3897153],
      "audienceTypes": [18, 19],
      "creatives": [11, 13]
    }
  }
}
Response 200
{
  "success": true,
  "data": {
    "planId": 123
  }
}
More responses
Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Power Segment audiences are not supported for Voter TV+. Remove the unsupported audience to proceed. Audience IDs: [1160231]"
    }
  ]
}

Edit plan​

PUT
PUT

Update an existing Political plan or draft plan by ID. Name, details, and targeting are required for ready plans.

See resource properties for request schema.

Path parameters
id
integer		Plan ID.
Response 200
{
  "success": true,
  "data": {
    "planId": 123
  }
}
More responses
Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Power Segment audiences are not supported for Voter TV+. Remove the unsupported audience to proceed. Audience IDs: [1160231]"
    }
  ]
}

Edit plan name​

PATCH

Update the name of an existing Political plan.

Request schema
id
integer required		Plan ID.
name
string required		Updated plan name.
Request sample
{
  "id": 1,
  "name": "Update Plan Name"
}
Response 200
{
  "success": true,
  "data": {
    "message": "Plan updated successfully."
  }
}

Delete plans​

DELETE

Delete one or more Political plans by IDs. Associated strategies are also deleted, but proposals and proposed campaigns are NOT deleted.

Query parameters
planIds
string		Comma-separated plan IDs to delete.
Response 200
{
  "success": true,
  "data": {
    "message": "Plans have been deleted successfully"
  }
}

Activate proposal​

POST

Activate a proposal and all of its proposed campaigns. Send strategyId for Reach forecasting (objectiveId: 1) and Budget estimation (objectiveId: 2) plans, or planId for Voter TV+ (objectiveId: 3) plans. Send one, not both. The proposal is created in Ready (6) status.

Request schema
strategyId
integer		Strategy ID to activate. Required for Reach forecasting and Budget estimation plans.
planId
integer		Plan ID to activate. Required for Voter TV+ plans.
Request sample
{
  "strategyId": 42
}
Response 200
{
  "success": true,
  "data": {
    "id": 7,
    "message": "Plan A saved successfully."
  }
}
Request sample
{
  "planId": 124
}
Response 200
{
  "success": true,
  "data": {
    "id": 8,
    "message": "Voter TV+ Plan_Mix_01 saved successfully."
  }
}

Edit proposal​

PUT

Update a proposal's name, date range, and campaign budgeting details, and soft-delete specified campaigns.

Path parameters
proposalId
integer		Proposal ID.
Request schema
name
string		Updated proposal name.
startTime
integer		Unix epoch start date, in milliseconds.
endTime
integer		Unix epoch end date, in milliseconds.
reach
integer		Estimated reach.
impressions
integer		Estimated impressions.
budget
number		Proposal budget.
frequencyCap
integer		Frequency cap.
maxReach
integer		Maximum reach.
maxImpressions
integer		Maximum impressions.
maxBudget
number		Maximum budget.
cpm
number		Cost per thousand impressions.
minCpm
number		Minimum cost per thousand impressions.
maxCpm
number		Maximum cost per thousand impressions.
minImpressions
integer		Minimum impressions.
minReach
integer		Minimum reach.
minBudget
number		Minimum budget.
proposedCampaigns
array of objects		Updated proposed campaign details.
proposedCampaigns object properties
id
integer		Campaign ID.
name
string		Campaign name.
startTime
integer		Unix epoch start date, in milliseconds.
endTime
integer		Unix epoch end date, in milliseconds.
targetedReach
integer		Targeted reach.
targetedImpressions
integer		Targeted impressions.
budget
number		Campaign budget.
frequencyCap
integer		Frequency cap.
maxTargetedReach
integer		Maximum targeted reach.
maxTargetedImpressions
integer		Maximum targeted impressions.
maxBudget
number		Maximum campaign budget.
cpm
number		Cost per thousand impressions.
minCpm
number		Minimum cost per thousand impressions.
maxCpm
number		Maximum cost per thousand impressions.
minTargetedImpressions
integer		Minimum targeted impressions.
minTargetedReach
integer		Minimum targeted reach.
minBudget
number		Minimum campaign budget.
deletedCampaignIds
array of integers		Campaign IDs to soft-delete.
Request sample
{
  "name": "Updated Proposal Name",
  "startTime": 1778434118000,
  "endTime": 1780162118000,
  "reach": 600000,
  "impressions": 2500000,
  "budget": 50000.00,
  "frequencyCap": 4,
  "maxReach": 650000,
  "maxImpressions": 3000000,
  "maxBudget": 60000.00,
  "cpm": 16.67,
  "minCpm": 1,
  "maxCpm": 50,
  "minImpressions": 100000,
  "minReach": 50000,
  "minBudget": 10000.00,
  "proposedCampaigns": [
    {
      "id": 1,
      "name": "Proposed Campaign ID",
      "startTime": 1778434118000,
      "endTime": 1780162118000,
      "targetedReach": 300000,
      "targetedImpressions": 1500000,
      "budget": 30000.00,
      "frequencyCap": 3,
      "maxTargetedReach": 350000,
      "maxTargetedImpressions": 2000000,
      "maxBudget": 35000.00,
      "cpm": 20.00,
      "minCpm": 1,
      "maxCpm": 50,
      "minTargetedImpressions": 50000,
      "minTargetedReach": 25000,
      "minBudget": 5000.00
    }
  ],
  "deletedCampaignIds": [102, 103]
}
Response 200
{
  "success": true,
  "data": {
    "id": 42,
    "message": "Proposal updated successfully."
  }
}

Edit proposal name​

PATCH

Update the name of an existing Political proposal.

Request schema
id
integer required		Proposal ID.
name
string required		Updated proposal name.
Request sample
{
  "id": 1,
  "name": "Update Proposal Name"
}
Response 200
{
  "success": true,
  "data": {
    "message": "Proposal updated successfully."
  }
}

Generate IO and campaigns​

POST

Convert a Political proposal into an insertion order (IO) with draft campaigns. The target proposal must be in Ready (6) or Failed (4) status.

The request returns immediately and the proposal moves to Processing (5) while the IO and campaigns are created. When generation finishes, the proposal moves to Converted (1) and its ioId is set. If generation fails, the proposal moves to Failed (4). For Voter TV+ proposals, only the CTV proposed campaigns become campaigns.

To find the created campaigns, call Get basic details of campaigns with the proposal's ioId in ioIdsList.

Path parameters
proposalId
integer		Proposal ID.
Request schema
politicalAdvertiserId
integer required		Political Advertiser profile ID.
startTime
integer required		Unix epoch start date for the campaigns, in milliseconds; can't be in the past.
endTime
integer		Unix epoch end date, in milliseconds. If omitted, the proposal's current duration is kept from the new startTime. Must keep the current duration in days.
Request sample
{
  "politicalAdvertiserId": 123,
  "startTime": 1778434118000,
  "endTime": 1780162118000
}
Response 200
{
  "success": true,
  "data": {
    "message": "Campaign generation is in progress"
  }
}

Delete proposals​

DELETE

Delete one or more Political proposals by IDs. Associated proposed campaigns are also deleted.

Query parameters
proposalIds
string		Comma-separated proposal IDs to delete.
Response 200
{
  "success": true,
  "data": {
    "message": "Proposals have been deleted successfully"
  }
}

Restore proposals​

PATCH

Restore Expired (3) proposals to Ready (6) status with new flight dates. The new dates are applied to the proposals and their proposed campaigns. The new flight can be a different length from the original.

Request schema
proposalIds
array of integers required		Proposal IDs to restore. Each proposal must be in Expired (3) status.
startTime
integer required		New Unix epoch start date, in milliseconds; can't be in the past.
endTime
integer required		New Unix epoch end date, in milliseconds; must be at least 30 minutes after startTime.
Request sample
{
  "proposalIds": [2, 3],
  "startTime": 1778434118000,
  "endTime": 1780162118000
}
Response 200
{
  "success": true,
  "data": {
    "message": "Proposals restored successfully"
  }
}

Create CVA details​

POST

Create a new Custom Voter audience (CVA) definition. This targeting equation is used to build an audience for a Political plan. The CVA details are stored and can be referenced by ID in future requests. This endpoint doesn't create an audience (see Create Custom Voter audience), but it does validate the equation.

Build the equation from the taxonomy IDs of segments from Get Custom Voter audience segment details. Taxonomy IDs in parentheses, separated by a vertical bar (|), are in an OR relationship, which combines the sets of segments. Groups of segments in parentheses, separated by an ampersand (&), are in an AND relationship, which builds an audience from the intersection of those groups.

Use the returned id to estimate reach for a Political plan with Estimate plan reach, or as the id of the cva object when you create a plan.

Request schema
equation
string required		Segment equation.
stateIds
array of integers		State IDs to limit the audience to.
reach
integer		Audience reach: segment_num_voters from Get CVA reach. Stored and passed to the forecasting service as provided; it isn't calculated.
Response properties
id
integer		CVA ID.
Request sample
{
  "equation": "((IQMCVACA069112|(IQMCVACA080323))&(IQMCVACA101616))",
  "stateIds": [30200005],
  "reach": 1629051
}
Response 200
{
  "success": true,
  "data": {
    "id": 12345
  }
}

Update CVA details​

PATCH

Update an existing Custom Voter audience (CVA) detail record with new state IDs, reach value, and an equation string.

Path parameters
cvaId
integer		CVA ID.
Request schema
equation
string		Segment equation.
stateIds
array of integers		State IDs to limit the audience to.
reach
integer		Audience reach: segment_num_voters from Get CVA reach. Stored and passed to the forecasting service as provided; it isn't calculated.
Request sample
{
  "equation": "((IQMCVACA069112|(IQMCVACA080323))&(IQMCVACA101616))",
  "stateIds": [30200005],
  "reach": 1629051
}
Response 200
{
  "success": true,
  "data": {
    "id": 12345
  }
}

Estimate plan reach​

POST

Estimate the reach for a Political plan based on optional CVA details and targeting criteria. If a cvaId is provided, CVA details are fetched from the database. The targeting and CVA data are forwarded to the data API for reach estimation.

Request schema
cvaId
integer		CVA ID (optional, fetches CVA details if provided).
targeting
object		Targeting object.
targeting object properties
whiteListedLocation
object		Whitelisted location targeting.
whiteListedLocation object properties
country
integer		Country ID.
states
array of integers		State IDs.
dma
array of integers		DMA IDs.
city
array of integers		City IDs.
county
array of integers		County IDs.
congressionalDistrict
array of integers		Congressional district IDs.
stateHouse
array of integers		State house IDs.
stateSenate
array of integers		State senate IDs.
zipCodes
array of strings		ZIP codes.
blackListedLocation
object		Blacklisted location targeting (same structure as whitelisted).
device
object		Device targeting.
device object properties
deviceTypeIds
array of integers		Device type IDs.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
channelTypeIds
array of integers		Channel type IDs.
Supported values
11App
14CTV
13OTT
12Web
inventory
object		Inventory targeting.
inventory object properties
openExchange
object		Open Exchange targeting.
inventoryGroupIds
array of integers		Inventory Group IDs.
creative
object		Creative targeting.
creative object properties
creativeTypeIds
array of integers		Creative type IDs.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
isTvAutoBuying
boolean		Indicates CTV auto-buying is enabled.
whitelistedAudiences
array of integers		Whitelisted audience IDs. Power Segment audiences are supported, except for Voter TV+ plans (objectiveId: 3).
blacklistedAudiences
array of integers		Blacklisted audience IDs. Power Segment audiences are supported, except for Voter TV+ plans (objectiveId: 3).
prebidSegments
array of integers		Prebid segment IDs.
audienceSegments
array of integers		Audience segment IDs.
ageGroupSegments
array of integers		Age group segment IDs (cross-screen plans only, see Get demographics keys).
genderSegments
array of integers		Gender segment IDs (cross-screen plans only, see Get demographics keys).
incomeRangeSegments
array of integers		Income range segment IDs (cross-screen plans only, see Get demographics keys).
ethnicitySegments
array of integers		Ethnicity segment IDs (cross-screen plans only, see Get demographics keys).
partyAffiliationSegments
array of integers		Party affiliation segment IDs (cross-screen plans only, see Get demographics keys).
advanced
object		Advanced targeting.
advanced object properties
splitTypeId
integer		Split type ID.
Supported values
1AI
2Manual
locations
array of integers		Targeting type IDs for locations.
Supported values
1Location
devices
array of integers		Device type IDs.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
inventoryGroupIds
array of integers		Inventory Group IDs.
audienceTypes
array of integers		Audience type IDs.
Supported values
1Matched audience
2Segmented audience
3Retargeted audience
4Geofarmed audience
5Contextual audience
6Lookalike audience
7Campaign audience
8Pre-bid audience
9Account Based Marketing (ABM) audience
10Custom Voter audience (CVA)
11Integrated Care Team (ICT) audience
12Power Segment audience
creatives
array of integers		Creative type IDs.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
Request sample
{
  "cvaId": 12234,
  "targeting": {
    "whiteListedLocation": {
      "country": 30100001,
      "states": [30200035],
      "dma": [30900026],
      "city": [30436781],
      "county": [30318981],
      "congressionalDistrict": [30617273],
      "stateHouse": [30803564],
      "stateSenate": [30718340],
      "zipCodes": ["10002"]
    },
    "blackListedLocation": {
      "country": 30100001,
      "states": [30200003],
      "dma": [30900139],
      "city": [30442811],
      "county": [30321244],
      "congressionalDistrict": [30601009],
      "stateHouse": [30800263],
      "stateSenate": [30701056],
      "zipCodes": ["10001"]
    },
    "whitelistedAudiences": [1101831, 1101829],
    "blacklistedAudiences": [1101826],
    "prebidSegments": [323212],
    "audienceSegments": [2133],
    "creative": {
      "creativeTypeIds": [11, 13, 14],
      "isTvAutoBuying": true
    },
    "device": {
      "deviceTypeIds": [20300001, 20300002],
      "channelTypeIds": [11]
    },
    "inventory": {
      "openExchange": {
        "iabCategories": [123],
        "exchanges": [90, 93]
      },
      "inventoryGroupIds": []
    }
  }
}
Response 200
{
  "success": true,
  "data": {
    "reach": 10
  }
}

Generate custom strategies​

POST

Generate custom strategies for an existing plan by calling the forecasting service with the provided targeting and budget parameters. This endpoint persists the resulting strategies, proposals, and campaigns, then returns strategy summaries.

The id in the response is the forecasting service's own ID, not the saved strategy ID, and can't be activated. To get the saved strategy IDs, call Get list of strategies for this planId.

Request schema
planId
integer		Plan ID.
strategyName
string		Custom strategy name.
name
string		Plan name.
objectiveId
integer		Plan objective ID.
Supported values
1Reach forecasting
2Budget estimation
3Voter TV+
totalBudget
number		Total budget.
details
object		Plan details object.
details object properties
startDate
integer		Unix epoch start date, in milliseconds.
endDate
integer		Unix epoch end date, in milliseconds.
timezoneId
integer		Timezone ID. Replaced with the Organization's timezone.
frequencyCap
integer		Frequency cap.
marginValue
integer		Margin applied on top of the base CPM, as a percentage from 0 to 100 (not a currency amount). Defaults to the Customer's margin.
targeting
object		Targeting object.
targeting object properties
whiteListedLocation
object		Whitelisted location targeting.
whiteListedLocation object properties
country
integer		Country ID.
states
array of integers		State IDs.
dma
array of integers		DMA IDs.
city
array of integers		City IDs.
county
array of integers		County IDs.
congressionalDistrict
array of integers		Congressional district IDs.
stateHouse
array of integers		State house IDs.
stateSenate
array of integers		State senate IDs.
zipCodes
array of strings		ZIP codes.
blackListedLocation
object		Blacklisted location targeting (same structure as whitelisted).
device
object		Device targeting.
device object properties
deviceTypeIds
array of integers		Device type IDs.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
channelTypeIds
array of integers		Channel type IDs.
Supported values
11App
14CTV
13OTT
12Web
inventory
object		Inventory targeting.
inventory object properties
openExchange
object		Open Exchange targeting.
inventoryGroupIds
array of integers		Inventory Group IDs.
creative
object		Creative targeting.
creative object properties
creativeTypeIds
array of integers		Creative type IDs.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
isTvAutoBuying
boolean		Indicates CTV auto-buying is enabled.
whitelistedAudiences
array of integers		Whitelisted audience IDs. Power Segment audiences are supported, except for Voter TV+ plans (objectiveId: 3).
blacklistedAudiences
array of integers		Blacklisted audience IDs. Power Segment audiences are supported, except for Voter TV+ plans (objectiveId: 3).
prebidSegments
array of integers		Prebid segment IDs.
audienceSegments
array of integers		Audience segment IDs.
ageGroupSegments
array of integers		Age group segment IDs (cross-screen plans only, see Get demographics keys).
genderSegments
array of integers		Gender segment IDs (cross-screen plans only, see Get demographics keys).
incomeRangeSegments
array of integers		Income range segment IDs (cross-screen plans only, see Get demographics keys).
ethnicitySegments
array of integers		Ethnicity segment IDs (cross-screen plans only, see Get demographics keys).
partyAffiliationSegments
array of integers		Party affiliation segment IDs (cross-screen plans only, see Get demographics keys).
advanced
object		Advanced targeting.
advanced object properties
splitTypeId
integer		Split type ID.
Supported values
1AI
2Manual
locations
array of integers		Targeting type IDs for locations.
Supported values
1Location
devices
array of integers		Device type IDs.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
inventoryGroupIds
array of integers		Inventory Group IDs.
audienceTypes
array of integers		Audience type IDs.
Supported values
1Matched audience
2Segmented audience
3Retargeted audience
4Geofarmed audience
5Contextual audience
6Lookalike audience
7Campaign audience
8Pre-bid audience
9Account Based Marketing (ABM) audience
10Custom Voter audience (CVA)
11Integrated Care Team (ICT) audience
12Power Segment audience
creatives
array of integers		Creative type IDs.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
cva
object		Custom Voter audience (CVA) to target. All five properties are required.
cva object properties
id
integer		CVA ID from Create CVA details.
equation
string		Segment equation sent when the CVA was created.
stateIds
array of integers		State IDs sent when the CVA was created.
segmentIds
array of integers		Numeric segmentId values of the segments in the equation, from Get Custom Voter audience segment details.
reach
integer		Audience reach: segment_num_voters from Get CVA reach.
Response properties
id
integer		The forecasting service's ID for the strategy, not the saved strategy ID.
name
string		Strategy name.
startDate
integer		Unix epoch start date, in milliseconds.
endDate
integer		Unix epoch end date, in milliseconds.
duration
integer		Duration in days.
strategyTypeId
integer		Strategy type ID.
Supported values
1Maximum Reach
2Maximum Impressions
3Balanced
4Most Economical
5Custom
campaignsCount
integer		Number of campaigns.
proposalId
integer		Linked proposal ID.
budget
number		Strategy budget.
frequency
integer		Frequency cap.
reach
integer		Estimated reach.
impressions
integer		Estimated impressions.
cpm
number		Cost per thousand impressions.
creatives
array of integers		Creative type IDs.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
devices
array of integers		Device type IDs.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
channels
array of integers		Channel type IDs.
Supported values
11App
14CTV
13OTT
12Web
Request sample
{
  "planId": 1,
  "strategyName": "Maximum Reach",
  "totalBudget": 120000,
  "details": {
    "startDate": 1747195200000,
    "endDate": 1777089600000,
    "timezoneId": 29,
    "frequencyCap": 3
  },
  "targeting": {
    "device": {
      "deviceTypeIds": [20300004, 20300003],
      "channelTypeIds": [11, 12]
    }
  }
}
Response 200
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Maximum Reach",
      "startDate": 1747195200000,
      "endDate": 1777089600000,
      "duration": 30,
      "strategyTypeId": 1,
      "campaignsCount": 3,
      "proposalId": 1,
      "budget": 40000,
      "frequency": 3,
      "reach": 500000,
      "impressions": 2000000,
      "cpm": 15.5,
      "creatives": [11, 13],
      "devices": [20300004, 20300003],
      "channels": [11, 12]
    }
  ]
}

Delete strategy​

DELETE

Delete a custom strategy by ID. Associated proposals and proposed campaigns are not deleted. Only custom strategies can be deleted.

Path parameters
strategyId
integer		Strategy ID.
Response 200
{
  "success": true,
  "data": {
    "message": "Custom Strategy 1 has been deleted successfully"
  }
}

More Political Planner details​

Get supported parameters​

GET

Get the supported parameters for Political plan configuration including CVA and targeting options. Each parameter value indicates whether it is supported (true) or unsupported (false).

Response 200
{
  "success": true,
  "data": {
    "cva": {
      "equation": false,
      "stateIds": false,
      "segmentIds": false,
      "id": true,
      "reach": true
    },
    "targeting": {
      "whitelistedLocation": true,
      "blacklistedLocation": true,
      "whitelistedAudiences": true,
      "blacklistedAudiences": true,
      "prebidSegments": false,
      "audienceSegments": true,
      "creative": {
        "creativeTypeIds": true
      },
      "device": {
        "deviceTypeIds": true,
        "channelTypeIds": true
      },
      "inventory": true
    }
  }
}

Get targeting types​

GET

Get the list of available targeting types for Political Planners.

Response properties
id
integer		Targeting type ID.
name
string		Targeting type name.
order
integer		Display order.
displayName
string		Targeting type display name.
Response 200
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Location",
      "order": 1,
      "displayName": "Location"
    }
  ]
}

Get strategy types​

GET

Get the list of available strategy types for Political Planners.

Response properties
id
integer		Strategy type ID.
name
string		Strategy type name.
order
integer		Display order.
displayName
string		Strategy type display name.
Response 200
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "maximum_reach",
      "order": 1,
      "displayName": "Maximum Reach"
    },
    {
      "id": 2,
      "name": "maximum_impressions",
      "order": 2,
      "displayName": "Maximum Impressions"
    }
  ]
}

Get split types​

GET

Get the list of available split types for Political Planners.

Response properties
id
integer		Split type ID.
name
string		Split type name.
order
integer		Display order.
displayName
string		Split type display name.
Response 200
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "ai",
      "order": 1,
      "displayName": "AI"
    },
    {
      "id": 2,
      "name": "manual",
      "order": 2,
      "displayName": "Manual"
    }
  ]
}

Get plan statuses​

GET

Get the list of available plan statuses for Political Planners.

Response properties
id
integer		Plan status ID.
name
string		Plan status name.
order
integer		Display order.
displayName
string		Plan status display name.
Response 200
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "draft",
      "order": 1,
      "displayName": "Draft"
    },
    {
      "id": 2,
      "name": "ready",
      "order": 2,
      "displayName": "Ready"
    }
  ]
}

Get plan objectives​

GET

Get the list of available plan objectives for Political Planners.

Response properties
id
integer		Plan objective ID.
name
string		Plan objective name.
order
integer		Display order.
displayName
string		Plan objective display name.
Response 200
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "reach forecasting",
      "order": 1,
      "displayName": "Reach Forecasting"
    },
    {
      "id": 2,
      "name": "budget estimation",
      "order": 2,
      "displayName": "Budget Estimation"
    },
    {
      "id": 3,
      "name": "voter_tv+",
      "order": 3,
      "displayName": "Voter TV+"
    }
  ]
}

Cross-screen Planner​

Get reach saturation graph​

POST

Fetch cross-screen Planner graph data based on the targeting and budgeting criteria provided, including a Venn-diagram audience overlap breakdown and a line graph of linear TV and CTV reach over time.

To adjust the forecast, call this endpoint again with the same graphId and new overview values. Use the graphId and overview from the response to create a Voter TV+ plan.

If audienceOverlap.totalReach is 0, a plan created from the graph produces a proposal with 0 budgets. Narrow the location targeting, for example to states or DMAs, and request a new graph.

info

The first request for a new graph calls an external data service and can take more than 60 seconds. Allow sufficient time for the request to complete. Later requests with the same graphId are calculated without the external call.

Request schema
name
string		Plan name.
objectiveId
integer		Plan objective ID.
Supported values
1Reach forecasting
2Budget estimation
3Voter TV+
totalBudget
number		Total plan budget.
lastVisitedScreen
string		Last visited screen in plan creation.
details
object		Plan details object.
details object properties
startDate
integer		Unix epoch start date, in milliseconds.
endDate
integer		Unix epoch end date, in milliseconds.
timezoneId
integer		Timezone ID specifies data collection start time.
frequencyCap
integer		Frequency cap.
marginValue
integer		Margin applied on top of the base CPM, as a percentage from 0 to 100 (not a currency amount). Defaults to the Customer's margin.
targeting
object		Locations, demographics, and audiences to forecast reach for.
targeting object properties
whiteListedLocation
object		Whitelisted location targeting.
whiteListedLocation object properties
country
integer		Country ID.
states
array of integers		State IDs.
dma
array of integers		DMA IDs.
city
array of integers		City IDs.
county
array of integers		County IDs.
congressionalDistrict
array of integers		Congressional district IDs.
stateHouse
array of integers		State house IDs.
stateSenate
array of integers		State senate IDs.
zipCodes
array of strings		ZIP codes.
blackListedLocation
object		Blacklisted location targeting (same structure as whitelisted).
device
object		Device targeting.
device object properties
deviceTypeIds
array of integers		Device type IDs.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
channelTypeIds
array of integers		Channel type IDs.
Supported values
11App
14CTV
13OTT
12Web
inventory
object		Inventory targeting.
inventory object properties
openExchange
object		Open Exchange targeting.
inventoryGroupIds
array of integers		Inventory Group IDs.
creative
object		Creative targeting.
creative object properties
creativeTypeIds
array of integers		Creative type IDs.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
isTvAutoBuying
boolean		Indicates CTV auto-buying is enabled.
whitelistedAudiences
array of integers		Whitelisted audience IDs. Power Segment audiences are supported, except for Voter TV+ plans (objectiveId: 3).
blacklistedAudiences
array of integers		Blacklisted audience IDs. Power Segment audiences are supported, except for Voter TV+ plans (objectiveId: 3).
prebidSegments
array of integers		Prebid segment IDs.
audienceSegments
array of integers		Audience segment IDs.
ageGroupSegments
array of integers		Age group segment IDs.
genderSegments
array of integers		Gender segment IDs.
incomeRangeSegments
array of integers		Income range segment IDs.
ethnicitySegments
array of integers		Ethnicity segment IDs.
partyAffiliationSegments
array of integers		Party affiliation segment IDs.
advanced
object		Advanced targeting.
advanced object properties
splitTypeId
integer		Split type ID.
Supported values
1AI
2Manual
locations
array of integers		Targeting type IDs for locations.
Supported values
1Location
devices
array of integers		Device type IDs.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
inventoryGroupIds
array of integers		Inventory Group IDs.
audienceTypes
array of integers		Audience type IDs.
Supported values
1Matched audience
2Segmented audience
3Retargeted audience
4Geofarmed audience
5Contextual audience
6Lookalike audience
7Campaign audience
8Pre-bid audience
9Account Based Marketing (ABM) audience
10Custom Voter audience (CVA)
11Integrated Care Team (ICT) audience
12Power Segment audience
creatives
array of integers		Creative type IDs.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
graphId
string		ID of a graph you already created, to recalculate it with new overview values. Omit to create a new graph.
overview
object		Linear TV and CTV assumptions for the forecast. Defaults are used if omitted.
overview object properties
linearTvCpm
number		Linear TV cost per thousand impressions; 0 or more.
ctvCpm
number		CTV cost per thousand impressions; 0 or more.
grp
number		Linear TV gross rating points (GRP); 0 or more.
linearTvPercentage
integer		Percentage of the budget allocated to linear TV, 0 to 100. The rest goes to CTV.
ctvFrequency
integer		Average CTV frequency, 1 to 99.
Response properties
graphId
string		Graph ID (UUID). Use it as the plan's graphId when you create a Voter TV+ plan.
overview
object		Overview metrics.
overview object properties
linearTvCpm
number		Linear TV cost per thousand impressions.
ctvCpm
number		CTV cost per thousand impressions.
grp
number		Gross rating points.
linearTvPercentage
integer		Percentage of budget allocated to linear TV.
ctvFrequency
integer		Average CTV frequency.
audienceOverlap
object		Venn-diagram audience overlap data for the requested targeting and budget.
audienceOverlap object properties
population
integer		Total addressable population.
totalReach
integer		Total combined reach.
linearTvReach
integer		Linear TV reach.
ctvReach
integer		CTV reach.
overlapReach
integer		Reach overlapping between linear TV and CTV.
ctvIncrementalReach
integer		Incremental reach contributed by CTV.
maximumAudienceOverlap
object		Same shape as audienceOverlap, representing the maximum achievable overlap for the requested targeting and budget.
maximumAudienceOverlap object properties
population
integer		Total addressable population.
totalReach
integer		Total combined reach.
linearTvReach
integer		Linear TV reach.
ctvReach
integer		CTV reach.
overlapReach
integer		Reach overlapping between linear TV and CTV.
ctvIncrementalReach
integer		Incremental reach contributed by CTV.
reachSaturation
array of objects		Daily reach saturation data points.
reachSaturation object properties
day
integer		Day number in the flight.
ctvReach
integer		Cumulative CTV reach on this day.
linearTvReach
integer		Cumulative linear TV reach on this day.
overallReach
integer		Cumulative overall reach on this day.
Request sample
{
  "name": "Voter TV+ Plan",
  "objectiveId": 3,
  "totalBudget": 100000,
  "lastVisitedScreen": "graph",
  "details": {
    "startDate": 1793595600000,
    "endDate": 1794805200000,
    "frequencyCap": 3
  },
  "targeting": {
    "whiteListedLocation": {
      "country": 30100001,
      "states": [30200036, 30200039]
    },
    "ageGroupSegments": [6073147, 6073145],
    "genderSegments": [6189394, 6189395]
  }
}
Response 200
{
  "success": true,
  "data": {
    "graphId": "0f6c7400-a8f5-4a1b-ab65-af15372cc0ff",
    "overview": {
      "linearTvCpm": 20,
      "ctvCpm": 7,
      "grp": 180,
      "linearTvPercentage": 50,
      "ctvFrequency": 3
    },
    "audienceOverlap": {
      "population": 16100000,
      "totalReach": 1470000,
      "linearTvReach": 1020000,
      "ctvReach": 778000,
      "overlapReach": 328000,
      "ctvIncrementalReach": 450000
    },
    "maximumAudienceOverlap": {
      "population": 16100000,
      "totalReach": 2150000,
      "linearTvReach": 1480000,
      "ctvReach": 1150000,
      "overlapReach": 480000,
      "ctvIncrementalReach": 670000
    },
    "reachSaturation": [
      { "day": 1, "ctvReach": 12, "linearTvReach": 14, "overallReach": 20 },
      { "day": 2, "ctvReach": 24, "linearTvReach": 28, "overallReach": 54 },
      { "day": 3, "ctvReach": 36, "linearTvReach": 32, "overallReach": 66 },
      { "day": 4, "ctvReach": 48, "linearTvReach": 34, "overallReach": 78 },
      { "day": 5, "ctvReach": 60, "linearTvReach": 34, "overallReach": 90 },
      { "day": 6, "ctvReach": 72, "linearTvReach": 34, "overallReach": 112 },
      { "day": 7, "ctvReach": 84, "linearTvReach": 34, "overallReach": 114 }
    ]
  }
}

Get demographics keys​

GET

Get active demographics segment definitions used for cross-screen planning audience mapping (e.g. age, gender, income, and ethnicity groupings). Call without parentIds to get the top-level segment keys (categories like Age Group, Income Level). Call with parentIds set to one or more of those keys' ids to get the specific demographics values nested under them (e.g. 65+ under Age Group), each with its own parentId, reach, and display order.

Query parameters
parentIds
array of integers		Segment key ids to fetch demographics values for. Omit to get the top-level segment keys instead.
Response properties
id
integer		Demographics segment ID.
segmentId
integer		Segment ID used for audience targeting.
name
string		Segment display name.
parentId
integer		id of the parent segment key. Only present when parentIds was supplied in the request.
reach
integer		Reach for this demographics value. Only present when parentIds was supplied in the request.
order
integer		Display order of this demographics value. Only present when parentIds was supplied in the request.
Response 200 (segment keys, no parentIds)
{
  "success": true,
  "data": [
    {
      "id": 1,
      "segmentId": 10,
      "name": "Age Group"
    },
    {
      "id": 2,
      "segmentId": 2,
      "name": "Income Range"
    }
  ]
}
Response 200 (demographics values, parentIds=1,2)
{
  "success": true,
  "data": [
    {
      "id": 4,
      "segmentId": 10,
      "name": "65+",
      "parentId": 1,
      "reach": 5012322,
      "order": 1
    },
    {
      "id": 5,
      "segmentId": 20,
      "name": "100K+",
      "parentId": 2,
      "reach": 603242,
      "order": 1
    }
  ]
}

Split proposal​

POST

Split a Voter TV+ proposal's CTV campaigns into one campaign per value of a targeting dimension, such as one campaign per state. Only works for cross-screen proposals with a plan objective ID of 3. The existing CTV campaigns are replaced. Send an empty locations list to merge them back into a single CTV campaign.

A split only has an effect for dimensions that the plan targets with more than one value. Split campaigns are named with a numbered suffix, such as _Video + Loc_1 and _Loc_2.

info

Computation time for this endpoint may take more than 60 seconds depending on the complexity of the targeting criteria and the size of the proposal being split. Please allow for sufficient time for the request to complete.

Path parameters
proposalId
integer required		Proposal ID to split.
Request schema
splitTypeId
integer		Split type ID.
Supported values
1AI
2Manual
locations
array of integers		Targeting type IDs to split by. These are targeting dimension IDs, not location IDs, for example 8 (state), 12 (DMA), 15 (ZIP code), or 29 (device).
Supported values
1Location
devices
array of integers		Device type IDs.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
inventoryGroupIds
array of integers		Inventory group IDs.
audienceTypes
array of integers		Audience type IDs.
Supported values
1Matched audience
2Segmented audience
3Retargeted audience
4Geofarmed audience
5Contextual audience
6Lookalike audience
7Campaign audience
8Pre-bid audience
9Account Based Marketing (ABM) audience
10Custom Voter audience (CVA)
11Integrated Care Team (ICT) audience
12Power Segment audience
creatives
array of integers		Creative type IDs.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio

Returns the proposal details as they were before the split. To see the new campaigns, call Get proposal details.

Request sample
{
  "locations": [8]
}
Response 200 (abbreviated)
{
  "success": true,
  "data": {
    "id": 8,
    "name": "Voter TV+ Plan_Mix_01",
    "startTime": 1793595600000,
    "endTime": 1794805200000,
    "owId": 202500,
    "statusId": 6,
    "reach": 778000,
    "impressions": 7140000,
    "budget": 100000,
    "frequencyCap": 3,
    "campaignGeneratable": true,
    "proposedCampaigns": [
      {
        "id": 501,
        "name": "Voter TV+ Plan_Mix_01_VTV + Video",
        "type": "Linear TV",
        "budget": 50000
      },
      {
        "id": 502,
        "name": "Voter TV+ Plan_Mix_01_Video",
        "type": "CTV",
        "budget": 50000
      }
    ]
  }
}
Have a question?
Ask the community
Was this page helpful?