Skip to main content

Planner API

This page covers the methods and endpoints associated with the Healthcare Professional (HCP) Planner. With the Planner API you can create, retrieve, update, publish, and manage HCP plans.

Read more about the HCP Planner in our Help Center article.

For a step-by-step walkthrough, see the Healthcare Professional (HCP) Planner tutorial.

HCP Planner details​

HCP Planner resource properties​

Resource properties
id
integer		Plan ID.
name
string		Plan name; must be unique in the Workspace.
statusId
integer		Status ID, with plannerTypeId set to 2. Set by IQM when the plan is created. On edit and publish, must equal the plan's current status.
Supported values
2Draft
3Expired
4Failed
5Processing
6Ready
7IO Created
startTime
integer		Unix epoch start time in milliseconds; can't be in the past.
endTime
integer		Unix epoch end time in milliseconds; must be at least 30 minutes after startTime.
timezoneId
integer		Timezone ID.
budgetTypeId
integer		Budget type ID.
Supported values
1Budget
2Impression
minBudget
number		Minimum plan budget, from the generate campaigns response. Required for Ready plans; Draft plans accept null. Returned as null in plan details.
budget
number		Plan budget; must be between minBudget and maxBudget.
maxBudget
number		Maximum plan budget.
reach
integer		Forecasted reach.
maxReach
integer		Maximum forecasted reach.
minImpressions
integer		Minimum plan impressions, from the generate campaigns response. Required for Ready plans; Draft plans accept null. Returned as null in plan details.
impressions
integer		Plan impressions; must be between minImpressions and maxImpressions.
maxImpressions
integer		Maximum plan impressions.
frequencyCap
integer		Frequency cap, 1 to 99. Applies to every campaign in the plan.
frequencyCapTypeId
integer		Frequency cap type ID. Applies to every campaign in the plan.
Supported values
1Day(s)
2Week(s)
3Month(s)
4Campaign duration
owId
integer		Organization Workspace ID. Set by IQM.
createdAt
integer		Unix epoch creation time in milliseconds. Set by IQM.
updatedAt
integer		Unix epoch last update time in milliseconds. Set by IQM.
ioId
integer		ID of the insertion order (IO) created when the plan is published; 0 until then. Set by IQM.
npiTypeIds
array of integers		NPI type IDs.
Supported values
3HCP
4NPI nurse
audienceBlocks
array of objects		Audience blocks, at most one per audience selection method. IQM sets each block's audience type from its method.
audienceBlocks object properties
audienceSelectionMethodId
integer		Audience selection method ID.
Supported values
1Filter based
2Upload NPI list
3Existing audience
4Account based
speciality
object		Specialties to target. Required for filter based, upload NPI list, and account based blocks.
speciality object properties
specialityIds
array of integers		Specialty IDs to target. Must be empty when allSpecialitiesSelected is true.
allSpecialitiesSelected
boolean		Set to true to target all specialties, with an empty specialityIds list.
account
object		Accounts to target. Required for account based blocks.
account object properties
accountIds
array of integers		Account IDs to target. Must be empty when allAccountsSelected is true.
allAccountsSelected
boolean		Set to true to target all accounts, with an empty accountIds list.
accountType
object		Account types to target. Required for account based blocks.
accountType object properties
accountTypeIds
array of integers		Account type IDs to target. Must be empty when allAccountTypesSelected is true.
allAccountTypesSelected
boolean		Set to true to target all account types, with an empty accountTypeIds list.
healthSystem
object		Health systems to target. Required for account based blocks.
healthSystem object properties
healthSystemIds
array of integers		Health system IDs to target. Must be empty when allHealthSystemsSelected is true.
allHealthSystemsSelected
boolean		Set to true to target all health systems, with an empty healthSystemIds list.
title
object		Titles to target. Required for account based blocks.
title object properties
titleIds
array of integers		Title IDs to target. Must be empty when allTitlesSelected is true.
allTitlesSelected
boolean		Set to true to target all titles, with an empty titleIds list.
locations
object		Locations to target. Required for filter based, upload NPI list, and account based blocks.
locations object properties
countryId
integer		Country ID; must be 30100001 (United States).
whiteListedStateIds
array of integers		State IDs to target.
blackListedStateIds
array of integers		State IDs to exclude.
whiteListedCityIds
array of integers		City IDs to target.
blackListedCityIds
array of integers		City IDs to exclude.
whiteListedZipcodes
array of strings		ZIP codes to target.
blackListedZipcodes
array of strings		ZIP codes to exclude. Targeted and excluded locations can't overlap.
dataPartners
array of objects		Data partners to match the audience with. At least one must be selected. Required for filter based, upload NPI list, and account based blocks.
dataPartners object properties
id
integer		Data partner ID. Account based blocks support only 7 and 12.
Supported values
7Healthlink ID
8Data360 ID
11Purple Lab ID
12RevOptimal ID
selected
boolean		Set to true to use this data partner.
priority
integer		Order of preference, starting at 1; can't be higher than the number of data partners in the block.
reach
integer		Data partner reach.
incrementalReach
integer		Reach this data partner adds on top of higher-priority data partners; 0 to reach.
storagePathId
integer		Upload NPI list blocks only: file ID of the uploaded NPI list.
storagePath
string		Upload NPI list blocks only: storage path of the uploaded NPI list file.
storageFileName
string		Upload NPI list blocks only: name of the uploaded NPI list file.
storageFileSize
integer		Upload NPI list blocks only: size of the uploaded NPI list file.
storageFileRows
integer		Upload NPI list blocks only: number of rows in the uploaded NPI list file.
includeAudienceIds
array of integers		Existing audience blocks only: audience IDs to include. Up to 14 included and excluded audiences in total.
excludeAudienceIds
array of integers		Existing audience blocks only: audience IDs to exclude. Can't overlap with includeAudienceIds.
planLevelTargeting
object		Creative type, device, channel, and inventory targeting for the whole plan. All four objects are required.
planLevelTargeting object properties
devices
object		Devices to target.
devices object properties
deviceTypeIds
array of integers		Device type IDs to target. Must be empty when allDeviceTypesSelected is true.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
allDeviceTypesSelected
boolean		Set to true to target all device types, with an empty deviceTypeIds list.
channels
object		Channels to target.
channels object properties
channelTypeIds
array of integers		Channel type IDs to target. Must be empty when allChannelTypesSelected is true.
Supported values
11App
14CTV
13OTT
12Web
allChannelTypesSelected
boolean		Set to true to target all channels, with an empty channelTypeIds list.
creativeTypes
object		Creative types to target.
creativeTypes object properties
creativeTypeIds
array of integers		Creative type IDs to target. Must be empty when allCreativeTypesSelected is true.
Supported values
11Image
13HTML
14Video
15Native
17Audio
allCreativeTypesSelected
boolean		Set to true to target all creative types, with an empty creativeTypeIds list.
isTvAutoBuying
boolean		Whether TV auto buying is enabled; requires video creatives (14).
inventory
object		Inventory to target.
inventory object properties
openExchanges
object		Open Exchange inventory to target.
openExchanges object properties
exchangeIds
array of integers		Exchange IDs to target. Must be empty when allExchangesSelected is true.
allExchangesSelected
boolean		Set to true to target all exchanges, with an empty exchangeIds list.
iabCategoryIds
array of integers		IAB category IDs to target. Must be empty when allIabCategoriesSelected is true.
allIabCategoriesSelected
boolean		Set to true to target all IAB categories, with an empty iabCategoryIds list.
inventoryGroup
object		Inventory groups to target. Send null unless you target inventory groups. Returned as an empty object in plan details when none are targeted.
inventoryGroup object properties
inventoryGroupIds
array of integers		Inventory group IDs to target.
allInventoryGroupsSelected
boolean		Set to true to target all inventory groups, with an empty inventoryGroupIds list.
splitStrategy
array of objects		Split dimensions used to divide the plan into campaigns. Must include the creative type dimension, and the NPI type dimension unless the only audience block is an existing audience block.
splitStrategy object properties
splitDimensionTypeId
integer		Split dimension ID. Each dimension can appear once.
Supported values
1Creative type
2NPI type
3Partner
4Device type
5Audience type
selectedValueIds
array of integers		Values to split by. For creative type, must exactly match the plan-level creative types; for other dimensions, must be a subset of the matching targeting. Ignored when generating campaigns.
campaigns
array of objects		Proposed campaigns, up to 250. Required for Ready plans, with every minimum and maximum field. Each campaign's media CPM, reach, and budget (or impressions, when budgetTypeId is 2) must be within its own range.
campaigns object properties
id
integer		Proposed campaign ID. Set by IQM and re-created on each edit and publish.
campaignId
integer		Campaign ID of the campaign created when the plan is published; 0 until then. Set by IQM.
name
string		Campaign name.
strategy
string		Targeting values the campaign is split by. Set by IQM.
startTime
integer		Unix epoch start time in milliseconds.
endTime
integer		Unix epoch end time in milliseconds.
frequencyCap
integer		Frequency cap. Taken from the plan; values sent here are ignored.
frequencyCapTypeId
integer		Frequency cap type ID. Taken from the plan; values sent here are ignored.
Supported values
1Day(s)
2Week(s)
3Month(s)
4Campaign duration
minMediaCpm
number		Minimum media cost per mille (CPM).
mediaCpm
number		Media CPM, based on the campaign's creative type; must be between minMediaCpm and maxMediaCpm.
maxMediaCpm
number		Maximum media CPM.
dataCpm
number		Data CPM: the average data cost of the campaign's selected data partners.
minBudget
number		Minimum campaign budget.
budget
number		Campaign budget; must be between minBudget and maxBudget.
maxBudget
number		Maximum campaign budget.
minReach
integer		Minimum campaign reach.
reach
integer		Campaign reach; must be between minReach and maxReach.
maxReach
integer		Maximum campaign reach.
minImpressions
integer		Minimum campaign impressions.
impressions
integer		Campaign impressions; must be between minImpressions and maxImpressions.
maxImpressions
integer		Maximum campaign impressions.
isAbm
boolean		Whether the campaign targets an Account Based Marketing (ABM) audience.
targeting
object		Campaign targeting: the values for this campaign's slice of the split strategy.
targeting object properties
creativeTypeId
integer		Creative type ID. One creative type per campaign.
Supported values
11Image
13HTML
14Video
15Native
17Audio
npiTypeId
integer		NPI type ID. One NPI type per campaign.
Supported values
3HCP
4NPI nurse
dataPartnerIds
array of integers		Data partner IDs.
Supported values
7Healthlink ID
8Data360 ID
11Purple Lab ID
12RevOptimal ID
deviceTypeIds
array of integers		Device type IDs.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
audienceTypeIds
array of integers		Audience type IDs.
Supported values
1Matched audience
2Segmented audience
4Geofarmed audience
5Contextual audience
9Account Based Marketing (ABM) audience

Targeting consistency rule​

The selectedValueIds in each splitStrategy entry must agree with the plan's targeting for that dimension. The creative type split must exactly match the plan-level creative types. The other dimensions must be a subset of the matching targeting.

The rule is checked when you create a plan (ready or draft), edit it, or publish it. Generate campaigns plan doesn't check it: it ignores selectedValueIds and splits by every plan-level value of each listed dimension. Campaign targeting isn't checked against the split strategy, so use the campaigns that generate campaigns returns.

DimensionsplitDimensionTypeIdselectedValueIds must agree withRuleCampaign field
Creative type1creativeTypeIds in planLevelTargeting.Exact match.creativeTypeId
NPI type2Top-level npiTypeIds.Subset.npiTypeId
Data partner3Data partner IDs across all audience blocks.Subset.dataPartnerIds
Device type4deviceTypeIds in planLevelTargeting.Subset.deviceTypeIds
Audience type5Audience types of all audience blocks, set by IQM from each block's selection method.Subset.audienceTypeIds

When "select all" is used for creative types or devices, compare against the full list: creative types 11, 13, 14, 15, and 17; devices 20300001 to 20300004. Filter based and upload NPI list blocks have the Matched audience type (1), and account based blocks have the Account Based Marketing (ABM) audience type (9). Existing audience blocks take the types of their audiences.

HCP example request with targeting consistency

Highlighted lines show the same IDs recurring across the plan-level selection, the matching splitStrategy entry, and the campaign's own targeting.

{
  "name": "Q4 Cardiology Awareness",
  "startTime": 1793505600000,
  "endTime": 1796101199000,
  "timezoneId": 29,
  "budgetTypeId": 1,
  "minBudget": 98.00,
  "budget": 8820.00,
  "maxBudget": 8820.00,
  "reach": 60000,
  "maxReach": 60000,
  "minImpressions": 4000,
  "impressions": 360000,
  "maxImpressions": 360000,
  "frequencyCap": 3,
  "frequencyCapTypeId": 1,
  "npiTypeIds": [3, 4],
  "audienceBlocks": [
    {
      "audienceSelectionMethodId": 1,
      "speciality": {
        "specialityIds": [],
        "allSpecialitiesSelected": true
      },
      "locations": {
        "countryId": 30100001,
        "whiteListedStateIds": [],
        "blackListedStateIds": [],
        "whiteListedCityIds": [],
        "blackListedCityIds": [],
        "whiteListedZipcodes": [],
        "blackListedZipcodes": []
      },
      "dataPartners": [
        { "id": 7, "selected": true, "priority": 1, "reach": 120000, "incrementalReach": 120000 },
        { "id": 8, "selected": true, "priority": 2, "reach": 90000, "incrementalReach": 30000 }
      ]
    }
  ],
  "planLevelTargeting": {
    "devices": {
      "deviceTypeIds": [20300001, 20300004],
      "allDeviceTypesSelected": false
    },
    "creativeTypes": {
      "creativeTypeIds": [11, 14],
      "allCreativeTypesSelected": false,
      "isTvAutoBuying": false
    },
    "channels": {
      "channelTypeIds": [],
      "allChannelTypesSelected": true
    },
    "inventory": {
      "openExchanges": {
        "exchangeIds": [],
        "allExchangesSelected": true,
        "iabCategoryIds": [],
        "allIabCategoriesSelected": true
      },
      "inventoryGroup": null
    }
  },
  "splitStrategy": [
    {
      "splitDimensionTypeId": 1,
      "selectedValueIds": [11, 14]
    },
    {
      "splitDimensionTypeId": 2,
      "selectedValueIds": [3, 4]
    },
    {
      "splitDimensionTypeId": 3,
      "selectedValueIds": [7, 8]
    },
    {
      "splitDimensionTypeId": 4,
      "selectedValueIds": [20300001, 20300004]
    },
    {
      "splitDimensionTypeId": 5,
      "selectedValueIds": [1]
    }
  ],
  "campaigns": [
    {
      "name": "Image - Physicians - Healthlink - Mobile",
      "startTime": 1793505600000,
      "endTime": 1796101199000,
      "frequencyCap": 3,
      "frequencyCapTypeId": 1,
      "minMediaCpm": 6.00,
      "mediaCpm": 6.00,
      "maxMediaCpm": 6.00,
      "dataCpm": 10.00,
      "minBudget": 16.00,
      "budget": 336.00,
      "maxBudget": 336.00,
      "minReach": 10,
      "reach": 7000,
      "maxReach": 7000,
      "minImpressions": 1000,
      "impressions": 21000,
      "maxImpressions": 21000,
      "isAbm": false,
      "targeting": {
        "creativeTypeId": 11,
        "npiTypeId": 3,
        "dataPartnerIds": [7],
        "deviceTypeIds": [20300001],
        "audienceTypeIds": [1]
      }
    }
  ]
}

HCP Planner details by ID​

GET

Get HCP plan details by ID. The response uses the same fields as the request body for Create HCP Planner, plus the fields set by IQM.

Path parameters
planId
integer		Plan ID.
Response 200
{
  "success": true,
  "data": {
    "id": 4512,
    "name": "Q4 Cardiology Awareness",
    "startTime": 1793505600000,
    "endTime": 1796101199000,
    "timezoneId": 29,
    "budgetTypeId": 1,
    "owId": 200001,
    "createdAt": 1791800000000,
    "updatedAt": 1791800000000,
    "minBudget": null,
    "budget": 8820.00,
    "maxBudget": 8820.00,
    "reach": 60000,
    "maxReach": 60000,
    "minImpressions": null,
    "impressions": 360000,
    "maxImpressions": 360000,
    "frequencyCap": 3,
    "frequencyCapTypeId": 1,
    "statusId": 6,
    "npiTypeIds": [3, 4],
    "audienceBlocks": [
      {
        "audienceSelectionMethodId": 1,
        "speciality": {
          "specialityIds": [],
          "allSpecialitiesSelected": true
        },
        "locations": {
          "countryId": 30100001,
          "whiteListedStateIds": [],
          "blackListedStateIds": [],
          "whiteListedCityIds": [],
          "blackListedCityIds": [],
          "whiteListedZipcodes": [],
          "blackListedZipcodes": []
        },
        "dataPartners": [
          { "id": 7, "selected": true, "priority": 1, "reach": 120000, "incrementalReach": 120000 },
          { "id": 8, "selected": true, "priority": 2, "reach": 90000, "incrementalReach": 30000 }
        ],
        "storagePathId": null,
        "storagePath": null,
        "storageFileName": null,
        "storageFileSize": null,
        "storageFileRows": null,
        "includeAudienceIds": [],
        "excludeAudienceIds": []
      }
    ],
    "planLevelTargeting": {
      "devices": {
        "deviceTypeIds": [20300001, 20300004],
        "allDeviceTypesSelected": false
      },
      "channels": {
        "channelTypeIds": [],
        "allChannelTypesSelected": true
      },
      "creativeTypes": {
        "creativeTypeIds": [11, 14],
        "allCreativeTypesSelected": false,
        "isTvAutoBuying": false
      },
      "inventory": {
        "openExchanges": {
          "exchangeIds": [],
          "allExchangesSelected": true,
          "iabCategoryIds": [],
          "allIabCategoriesSelected": true
        },
        "inventoryGroup": {
          "inventoryGroupIds": [],
          "allInventoryGroupsSelected": false
        }
      }
    },
    "splitStrategy": [
      { "splitDimensionTypeId": 1, "selectedValueIds": [11, 14] },
      { "splitDimensionTypeId": 2, "selectedValueIds": [3, 4] }
    ],
    "campaigns": [
      {
        "id": 90001,
        "name": "Image - Physicians",
        "startTime": 1793505600000,
        "endTime": 1796101199000,
        "frequencyCap": 3,
        "frequencyCapTypeId": 1,
        "minMediaCpm": 6.00,
        "mediaCpm": 6.00,
        "maxMediaCpm": 6.00,
        "dataCpm": 12.50,
        "minBudget": 18.50,
        "budget": 2331.00,
        "maxBudget": 2331.00,
        "minReach": 10,
        "reach": 42000,
        "maxReach": 42000,
        "minImpressions": 1000,
        "impressions": 126000,
        "maxImpressions": 126000,
        "isAbm": false,
        "targeting": {
          "dataPartnerIds": [7, 8],
          "creativeTypeId": 11,
          "deviceTypeIds": [20300001, 20300004],
          "npiTypeId": 3,
          "audienceTypeIds": [1]
        },
        "campaignId": 0
      }
    ],
    "ioId": 0
  }
}
More responses
Response 403
{
  "success": false,
  "errorObjects": [
    {
      "error": "Plan with plan id 3104 does not exist"
    }
  ]
}
Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Invalid Plan Id",
      "field": "planId"
    }
  ]
}

Get list of HCP Planners​

GET

Get a list of HCP plans.

A plan id can be used in the HCP Planner details by ID endpoint and to perform various actions in HCP 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		Filter results by search field: account name.
sortBy
string		Sorts by ascending (+) or descending (-), default: -id.
Supported values: id, name, createdBy, createdOn, startDate, endDate, reach, impressions, budget, duration.
statusIds
string		Comma separated status IDs.
Supported values
2Draft
3Expired
4Failed
5Processing
6Ready
7IO Created
budgetTypeIds
string		Comma separated budget type IDs.
Supported values
1Budget
2Impression
startDate
integer		Epoch time in milliseconds.
endDate
integer		Epoch time in milliseconds.
Response properties
id
integer		Plan ID.
name
string		Plan name.
statusId
integer		Status ID.
Supported values
2Draft
3Expired
4Failed
5Processing
6Ready
7IO Created
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 plan.
reach
integer		Reach.
impression
integer		Impression.
budget
integer		Budget.
ioId
integer		IO ID; 0 until the plan is published.
budgetTypeId
integer		Budget type ID.
Supported values
1Budget
2Impression
campaignCount
integer		Number of campaigns associated with the plan.
lastUpdated
integer		Unix epoch last updated date, in milliseconds.
Response 200
{
  "success": true,
  "data": {
    "data": [
      {
        "id": 2016,
        "name": "test",
        "statusId": 3,
        "createdOn": 1752836679704,
        "createdBy": "Harshita Bhambhani",
        "userAvatarUrl": "https://iqm-web-assets-c92d6b6cbde1-stage.s3.amazonaws.com/avatar/HB.png",
        "startDate": 1752838419000,
        "endDate": 1753934400000,
        "timezoneId": 29,
        "reach": 206567705,
        "impression": 37182186900,
        "budget": 334639683,
        "ioId": 0,
        "budgetTypeId": 1,
        "campaignCount": 0,
        "lastUpdated": 1752816878383
      }
    ],
    "totalRecords": 1,
    "filteredRecords": 1
  }
}

Get list of accounts​

GET

Get a list of HCP accounts.

Query parameters
pageNo
integer		Page number of retrieved data, default: 1.
noOfEntries
integer		Number of entries returned per page, default: 50.
searchField
string		Filter results by search field: account name.
sortBy
string		Sorts by ascending (+) or descending (-), default: +displayName.
Supported values: id, name, createdOn.
accountTypeIds
array of integer		Account type IDs.
Supported values
1Individual
2Organization
accountIds
array of integer		Account IDs.
Response properties
id
integer		Account ID.
name
string		Account name.
displayName
string		Account display name.
displayOrder
integer		Account display order.
accountTypeId
integer		Account type ID.
reach
integer		Account reach.
Response 200
{
  "success": true,
  "data": {
    "accountsList": [
      {
        "id": 1,
        "name": "Account 1",
        "displayName": "Account 1",
        "displayOrder": 1,
        "accountTypeId": 1,
        "reach": 1000
      },
      {
        "id": 2,
        "name": "Account 2",
        "displayName": "Account 2",
        "displayOrder": 2,
        "accountTypeId": 1,
        "reach": 1000
      }
    ],
    "totalRecords": 2,
    "filteredRecords": 2
  }
}

Download HCP Planner​

POST

Download the HCP Planner file.

Request schema
planId
integer		Plan ID.
fileTypeId
integer		File type ID.
Supported values
1Excel
3PDF
Request sample
{
  "planId": 123,
  "fileTypeId": 1
}
Response 200
{
  "success": true,
  "data": {
    "downloadUrl": "https://iqm-web-assets-c92d6b6cbde1-stage.s3.amazonaws.com/plan_exports/hcp_planner_20240101120000.xlsx"
  }
}

HCP Planner management​

Create HCP Planner​

POST
POST

Create an HCP plan from the Generate campaigns plan response. Send the generate campaigns response data unchanged, apart from any budgets and impressions you adjust within their ranges.

/proposal/add saves the plan in Ready (6) status. /proposal/draft saves it in Draft (2) status and skips the budget and campaign checks.

The response id is the plan ID used in later requests.

Response properties
message
string		Success message.
id
integer		Plan ID.
Request sample
{
  "name": "Q4 Cardiology Awareness",
  "startTime": 1793505600000,
  "endTime": 1796101199000,
  "timezoneId": 29,
  "budgetTypeId": 1,
  "minBudget": 98.00,
  "budget": 8820.00,
  "maxBudget": 8820.00,
  "reach": 60000,
  "maxReach": 60000,
  "minImpressions": 4000,
  "impressions": 360000,
  "maxImpressions": 360000,
  "frequencyCap": 3,
  "frequencyCapTypeId": 1,
  "npiTypeIds": [3, 4],
  "audienceBlocks": [
    {
      "audienceSelectionMethodId": 1,
      "speciality": {
        "specialityIds": [],
        "allSpecialitiesSelected": true
      },
      "locations": {
        "countryId": 30100001,
        "whiteListedStateIds": [],
        "blackListedStateIds": [],
        "whiteListedCityIds": [],
        "blackListedCityIds": [],
        "whiteListedZipcodes": [],
        "blackListedZipcodes": []
      },
      "dataPartners": [
        { "id": 7, "selected": true, "priority": 1, "reach": 120000, "incrementalReach": 120000 },
        { "id": 8, "selected": true, "priority": 2, "reach": 90000, "incrementalReach": 30000 }
      ]
    }
  ],
  "planLevelTargeting": {
    "devices": {
      "deviceTypeIds": [20300001, 20300004],
      "allDeviceTypesSelected": false
    },
    "creativeTypes": {
      "creativeTypeIds": [11, 14],
      "allCreativeTypesSelected": false,
      "isTvAutoBuying": false
    },
    "channels": {
      "channelTypeIds": [],
      "allChannelTypesSelected": true
    },
    "inventory": {
      "openExchanges": {
        "exchangeIds": [],
        "allExchangesSelected": true,
        "iabCategoryIds": [],
        "allIabCategoriesSelected": true
      },
      "inventoryGroup": null
    }
  },
  "splitStrategy": [
    { "splitDimensionTypeId": 1, "selectedValueIds": [11, 14] },
    { "splitDimensionTypeId": 2, "selectedValueIds": [3, 4] }
  ],
  "campaigns": [
    {
      "id": null,
      "name": "Image - Physicians",
      "startTime": 1793505600000,
      "endTime": 1796101199000,
      "frequencyCap": 3,
      "frequencyCapTypeId": 1,
      "minMediaCpm": 6.00,
      "mediaCpm": 6.00,
      "maxMediaCpm": 6.00,
      "dataCpm": 12.50,
      "minBudget": 18.50,
      "budget": 2331.00,
      "maxBudget": 2331.00,
      "minReach": 10,
      "reach": 42000,
      "maxReach": 42000,
      "minImpressions": 1000,
      "impressions": 126000,
      "maxImpressions": 126000,
      "isAbm": false,
      "targeting": {
        "dataPartnerIds": [7, 8],
        "creativeTypeId": 11,
        "deviceTypeIds": [20300001, 20300004],
        "npiTypeId": 3,
        "audienceTypeIds": [1]
      }
    },
    ...
  ]
}
Response 200
{
  "success": true,
  "data": {
    "message": "Q4 Cardiology Awareness generated successfully",
    "id": 4512
  }
}
More responses
Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Selected creative type IDs and split IDs do not match."
    }
  ]
}

Update HCP Planner​

PUT

Update an HCP plan by ID. Send the full plan; the saved plan is replaced with the request body. Editing doesn't change the plan's status. Plans in Processing (5) or IO Created (7) status can't be edited.

To edit a plan, get it with HCP Planner details by ID, change the fields you need, and send it back. The request schema is the same as Create HCP Planner, except for the fields in the following table.

Path parameters
planId
integer		Plan ID.
Request schema
id
integer required		Plan ID of the plan to update; must be the same as the planId path parameter.
statusId
integer required		The plan's current status ID. Send it back unchanged.
Supported values
2Draft
3Expired
4Failed
5Processing
6Ready
7IO Created
minBudget
number		Minimum plan budget, from the generate campaigns response. Required for Ready plans; Draft plans accept null.
minImpressions
integer		Minimum plan impressions, from the generate campaigns response. Required for Ready plans; Draft plans accept null.
planLevelTargeting
object required		Creative type, device, channel, and inventory targeting for the whole plan.
planLevelTargeting object properties
inventory
object required		Inventory to target.
inventory object properties
inventoryGroup
object		Inventory groups to target. Send null unless you target inventory groups.
campaigns
array of objects required		Proposed campaigns. Each edit re-creates the campaigns with new id values. Each campaign's frequencyCap and frequencyCapTypeId are ignored; the plan's values apply.
Request sample (abbreviated)
{
  "id": 4512,
  "statusId": 6,
  "name": "Q4 Cardiology Awareness",
  "startTime": 1793505600000,
  "endTime": 1796101199000,
  "timezoneId": 29,
  "budgetTypeId": 1,
  "minBudget": 98.00,
  "budget": 8820.00,
  "maxBudget": 8820.00,
  "minImpressions": 4000,
  "impressions": 360000,
  "maxImpressions": 360000,
  "frequencyCap": 5,
  "frequencyCapTypeId": 2,
  "npiTypeIds": [3, 4],
  "audienceBlocks": [ ... ],
  "planLevelTargeting": {
    "devices": { ... },
    "creativeTypes": { ... },
    "channels": { ... },
    "inventory": {
      "openExchanges": { ... },
      "inventoryGroup": null
    }
  },
  "splitStrategy": [ ... ],
  "campaigns": [ ... ]
}
Response 200
{
  "success": true,
  "data": {
    "message": "Q4 Cardiology Awareness updated successfully",
    "id": 4512
  }
}
More responses
Response 403
{
  "success": false,
  "errorObjects": [
    {
      "error": "Plan with plan id 3104 does not exist"
    }
  ]
}
Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Invalid Plan Id",
      "field": "planId"
    }
  ]
}
Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Proposal cannot be edited in its current status."
    }
  ]
}

Delete HCP Planner​

DELETE

Delete one or more HCP plans by ID.

Query parameters
planIds
string		Comma separated plan IDs to delete.
Response properties
message
string		Success message.
Response 200
{
  "success": true,
  "data": {
    "message": "Sample deleted successfully"
  }
}

Validate Planner name​

POST

Check if an HCP plan name is available for use within the Organization. This endpoint also validates the name's character limit and vertical type.

Request schema
name
string		Plan name to validate.

Response properties
available
boolean		Indicates if the plan name is available.
Request sample
{
  "name": "Q4 Diabetes Awareness Campaign"
}
Response 200
{
  "success": true,
  "data": {
    "available": false
  }
}

Get targeting graphs​

POST

This endpoint calculates distribution statistics for devices, creative types, and channels across the entire plan configuration. The payload accepts multiple audience blocks and plan-level targeting and returns aggregated distribution data for each targeting dimension.

Use this endpoint to visualize how different targeting dimensions are distributed across audience blocks and plan-level targeting in an HCP plan.

Request schema
npiTypeIds
array of integers		NPI type IDs.
Supported values
3HCP
4NPI nurse
audienceBlocks
array of objects		Array of audience block objects.
audienceBlocks object properties
audienceSelectionMethodId
integer		Audience selection method ID.
Supported values
1Filter based
2Upload NPI list
3Existing audience
4Account based
speciality
object		Specialties to target. Required for filter based, upload NPI list, and account based blocks.
speciality object properties
specialityIds
array of integers		Specialty IDs to target. Must be empty when allSpecialitiesSelected is true.
allSpecialitiesSelected
boolean		Set to true to target all specialties, with an empty specialityIds list.
account
object		Accounts to target. Required for account based blocks.
account object properties
accountIds
array of integers		Account IDs to target. Must be empty when allAccountsSelected is true.
allAccountsSelected
boolean		Set to true to target all accounts, with an empty accountIds list.
accountType
object		Account types to target. Required for account based blocks.
accountType object properties
accountTypeIds
array of integers		Account type IDs to target. Must be empty when allAccountTypesSelected is true.
allAccountTypesSelected
boolean		Set to true to target all account types, with an empty accountTypeIds list.
healthSystem
object		Health systems to target. Required for account based blocks.
healthSystem object properties
healthSystemIds
array of integers		Health system IDs to target. Must be empty when allHealthSystemsSelected is true.
allHealthSystemsSelected
boolean		Set to true to target all health systems, with an empty healthSystemIds list.
title
object		Titles to target. Required for account based blocks.
title object properties
titleIds
array of integers		Title IDs to target. Must be empty when allTitlesSelected is true.
allTitlesSelected
boolean		Set to true to target all titles, with an empty titleIds list.
locations
object		Locations to target. Required for filter based, upload NPI list, and account based blocks.
locations object properties
countryId
integer		Country ID; must be 30100001 (United States).
whiteListedStateIds
array of integers		State IDs to target.
blackListedStateIds
array of integers		State IDs to exclude.
whiteListedCityIds
array of integers		City IDs to target.
blackListedCityIds
array of integers		City IDs to exclude.
whiteListedZipcodes
array of strings		ZIP codes to target.
blackListedZipcodes
array of strings		ZIP codes to exclude. Targeted and excluded locations can't overlap.
dataPartners
array of objects		Data partners to match the audience with. At least one must be selected. Required for filter based, upload NPI list, and account based blocks.
dataPartners object properties
id
integer		Data partner ID. Account based blocks support only 7 and 12.
Supported values
7Healthlink ID
8Data360 ID
11Purple Lab ID
12RevOptimal ID
selected
boolean		Set to true to use this data partner.
priority
integer		Order of preference, starting at 1; can't be higher than the number of data partners in the block.
reach
integer		Data partner reach.
incrementalReach
integer		Reach this data partner adds on top of higher-priority data partners; 0 to reach.
storagePathId
integer		Upload NPI list blocks only: file ID of the uploaded NPI list.
storagePath
string		Upload NPI list blocks only: storage path of the uploaded NPI list file.
storageFileName
string		Upload NPI list blocks only: name of the uploaded NPI list file.
storageFileSize
integer		Upload NPI list blocks only: size of the uploaded NPI list file.
storageFileRows
integer		Upload NPI list blocks only: number of rows in the uploaded NPI list file.
includeAudienceIds
array of integers		Existing audience blocks only: audience IDs to include. Up to 14 included and excluded audiences in total.
excludeAudienceIds
array of integers		Existing audience blocks only: audience IDs to exclude. Can't overlap with includeAudienceIds.
planLevelTargeting
object		Plan level targeting object.
planLevelTargeting object properties
devices
object		Devices to target.
devices object properties
deviceTypeIds
array of integers		Device type IDs to target. Must be empty when allDeviceTypesSelected is true.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
allDeviceTypesSelected
boolean		Set to true to target all device types, with an empty deviceTypeIds list.
channels
object		Channels to target.
channels object properties
channelTypeIds
array of integers		Channel type IDs to target. Must be empty when allChannelTypesSelected is true.
Supported values
11App
14CTV
13OTT
12Web
allChannelTypesSelected
boolean		Set to true to target all channels, with an empty channelTypeIds list.
creativeTypes
object		Creative types to target.
creativeTypes object properties
creativeTypeIds
array of integers		Creative type IDs to target. Must be empty when allCreativeTypesSelected is true.
Supported values
11Image
13HTML
14Video
15Native
17Audio
allCreativeTypesSelected
boolean		Set to true to target all creative types, with an empty creativeTypeIds list.
isTvAutoBuying
boolean		Whether TV auto buying is enabled; requires video creatives (14).
inventory
object		Inventory to target.
inventory object properties
openExchanges
object		Open Exchange inventory to target.
openExchanges object properties
exchangeIds
array of integers		Exchange IDs to target. Must be empty when allExchangesSelected is true.
allExchangesSelected
boolean		Set to true to target all exchanges, with an empty exchangeIds list.
iabCategoryIds
array of integers		IAB category IDs to target. Must be empty when allIabCategoriesSelected is true.
allIabCategoriesSelected
boolean		Set to true to target all IAB categories, with an empty iabCategoryIds list.
inventoryGroup
object		Inventory groups to target. Send null unless you target inventory groups. Returned as an empty object in plan details when none are targeted.
inventoryGroup object properties
inventoryGroupIds
array of integers		Inventory group IDs to target.
allInventoryGroupsSelected
boolean		Set to true to target all inventory groups, with an empty inventoryGroupIds list.
owId
integer		Organization Workspace ID.

Response properties
deviceTypeDistribution
object		Device type distribution object.
deviceTypeDistribution object properties
totalNPIs
integer		Total NPIs.
breakdown
array of objects		Breakdown array.
breakdown object properties
deviceTypeId
integer		Device type ID.
percentage
number		Percentage.
creativeTypeDistribution
array of objects		Creative type distribution array.
creativeTypeDistribution object properties
creativeTypeId
integer		Creative type ID.
Supported values
11Image
13HTML
14Video
15Native
17Audio
impressions
integer		Impressions.
cpm
number		CPM.
channelTypeDistribution
object		Channel type distribution object.
channelTypeDistribution object properties
totalNPIs
integer		Total NPIs.
breakdown
array of objects 		Breakdown array.
breakdown object properties
channelTypeId
integer		Channel type ID.
Supported values
11App
14CTV
13OTT
12Web
percentage
number		Percentage.
Request sample
{
  "npiTypeIds": [3, 4],
  "audienceBlocks": [
    {
      "audienceSelectionMethodId": 1,
      "speciality": {
        "specialityIds": [406000001, 406000002],
        "allSpecialitiesSelected": false
      },
      "locations": {
        "countryId": 30100001,
        "whiteListedStateIds": [],
        "blackListedStateIds": [],
        "whiteListedCityIds": [],
        "blackListedCityIds": [],
        "whiteListedZipcodes": [],
        "blackListedZipcodes": []
      },
      "dataPartners": [
        { "id": 7, "selected": true, "priority": 1 },
        { "id": 8, "selected": true, "priority": 2 }
      ]
    }
  ],
  "planLevelTargeting": {
    "devices": {
      "deviceTypeIds": [20300001, 20300002],
      "allDeviceTypesSelected": false
    },
    "channels": {
      "channelTypeIds": [21100001, 21100003],
      "allChannelTypesSelected": false
    },
    "creativeTypes": {
      "creativeTypeIds": [11, 14, 15],
      "allCreativeTypesSelected": false
    },
    "inventory": {
      "openExchanges": {
        "exchangeIds": [16, 19],
        "allExchangesSelected": false,
        "iabCategoryIds": [11, 21],
        "allIabCategoriesSelected": false
      }
    }
  }
}
Response 200
{
  "success": true,
  "data": {
    "deviceTypeDistribution": {
      "totalNPIs": 2025510,
      "breakdown": [
        { "deviceTypeId": 20300001, "percentage": 20 },
        { "deviceTypeId": 20300002, "percentage": 35 },
        { "deviceTypeId": 20300003, "percentage": 15 },
        { "deviceTypeId": 20300004, "percentage": 30 }
      ]
    },
    "creativeTypeDistribution": [
      {
        "creativeTypeId": 11,
        "impressions": 1600000,
        "cpm": 72.0
      },
      {
        "creativeTypeId": 14,
        "impressions": 1200000,
        "cpm": 65.0
      }
    ],
    "channelTypeDistribution": {
      "totalNPIs": 2025510,
      "breakdown": [
        { "channelTypeId": 21100001, "percentage": 60 },
        { "channelTypeId": 21100003, "percentage": 40 }
      ]
    }
  }
}

Get audience graph​

POST

This endpoint accepts an audience block and NPI types and returns an audience graph for an HCP plan. The audience graph contains granular reach data broken down by NPI types, specialties, and data partner overlap.

Use this endpoint to get an audience composition analysis for a single targeting configuration, which is especially useful for understanding data partner overlap and incremental reach.

Request schema
npiTypeIds
array of integers		NPI type IDs.
Supported values
3HCP
4NPI nurse
audienceBlock
object		Audience block object.
audienceBlock object properties
audienceSelectionMethodId
integer		Audience selection method ID.
Supported values
1Filter based
2Upload NPI list
3Existing audience
4Account based
speciality
object		Specialties to target. Required for filter based, upload NPI list, and account based blocks.
speciality object properties
specialityIds
array of integers		Specialty IDs to target. Must be empty when allSpecialitiesSelected is true.
allSpecialitiesSelected
boolean		Set to true to target all specialties, with an empty specialityIds list.
account
object		Accounts to target. Required for account based blocks.
account object properties
accountIds
array of integers		Account IDs to target. Must be empty when allAccountsSelected is true.
allAccountsSelected
boolean		Set to true to target all accounts, with an empty accountIds list.
accountType
object		Account types to target. Required for account based blocks.
accountType object properties
accountTypeIds
array of integers		Account type IDs to target. Must be empty when allAccountTypesSelected is true.
allAccountTypesSelected
boolean		Set to true to target all account types, with an empty accountTypeIds list.
healthSystem
object		Health systems to target. Required for account based blocks.
healthSystem object properties
healthSystemIds
array of integers		Health system IDs to target. Must be empty when allHealthSystemsSelected is true.
allHealthSystemsSelected
boolean		Set to true to target all health systems, with an empty healthSystemIds list.
title
object		Titles to target. Required for account based blocks.
title object properties
titleIds
array of integers		Title IDs to target. Must be empty when allTitlesSelected is true.
allTitlesSelected
boolean		Set to true to target all titles, with an empty titleIds list.
locations
object		Locations to target. Required for filter based, upload NPI list, and account based blocks.
locations object properties
countryId
integer		Country ID; must be 30100001 (United States).
whiteListedStateIds
array of integers		State IDs to target.
blackListedStateIds
array of integers		State IDs to exclude.
whiteListedCityIds
array of integers		City IDs to target.
blackListedCityIds
array of integers		City IDs to exclude.
whiteListedZipcodes
array of strings		ZIP codes to target.
blackListedZipcodes
array of strings		ZIP codes to exclude. Targeted and excluded locations can't overlap.
dataPartners
array of objects		Data partners to match the audience with. At least one must be selected. Required for filter based, upload NPI list, and account based blocks.
dataPartners object properties
id
integer		Data partner ID. Account based blocks support only 7 and 12.
Supported values
7Healthlink ID
8Data360 ID
11Purple Lab ID
12RevOptimal ID
selected
boolean		Set to true to use this data partner.
priority
integer		Order of preference, starting at 1; can't be higher than the number of data partners in the block.
reach
integer		Data partner reach.
incrementalReach
integer		Reach this data partner adds on top of higher-priority data partners; 0 to reach.
storagePathId
integer		Upload NPI list blocks only: file ID of the uploaded NPI list.
storagePath
string		Upload NPI list blocks only: storage path of the uploaded NPI list file.
storageFileName
string		Upload NPI list blocks only: name of the uploaded NPI list file.
storageFileSize
integer		Upload NPI list blocks only: size of the uploaded NPI list file.
storageFileRows
integer		Upload NPI list blocks only: number of rows in the uploaded NPI list file.
includeAudienceIds
array of integers		Existing audience blocks only: audience IDs to include. Up to 14 included and excluded audiences in total.
excludeAudienceIds
array of integers		Existing audience blocks only: audience IDs to exclude. Can't overlap with includeAudienceIds.

Response properties
npiTypes
array of objects		NPI types array.
npiTypes object properties
id
integer		ID.
reach
integer		Reach.
specialties
array of objects		Specialties array.
specialties object properties
id
integer		ID.
reach
integer		Reach.
accountStats
object		Account stats object.
accountStats object properties
accountsTypeCount
integer		Accounts type count.
accountsCount
integer		Accounts count.
accounts
array of objects		Accounts array.
accounts object properties
id
integer		ID.
reach
integer		Reach.
dataPartnerStats
object		Data partner stats object.
dataPartnerStats object properties
partners
array of objects		Partners array.
partners object properties
id
integer		ID.
reach
integer		Reach.
coverage
number		Coverage.
venn
array of objects		Venn array.
venn object properties
partnerIds
array of integers		Partner IDs.
count
integer		Count.
reach
integer		Reach.
coveragePercentage
number		Coverage percentage.
intersectionPercentage
number		Intersection percentage.
Request sample
{
  "npiTypeIds": [3],
  "audienceBlock": {
    "audienceSelectionMethodId": 4,
    "speciality": {
      "specialityIds": [],
      "allSpecialitiesSelected": true
    },
    "account": {
      "accountIds": [440016, 440023],
      "allAccountsSelected": false
    },
    "accountType": {
      "accountTypeIds": [],
      "allAccountTypesSelected": true
    },
    "healthSystem": {
      "healthSystemIds": [],
      "allHealthSystemsSelected": true
    },
    "title": {
      "titleIds": [],
      "allTitlesSelected": true
    },
    "locations": {
      "countryId": 30100001,
      "whiteListedStateIds": [],
      "blackListedStateIds": [],
      "whiteListedCityIds": [],
      "blackListedCityIds": [],
      "whiteListedZipcodes": [],
      "blackListedZipcodes": []
    },
    "dataPartners": [
      { "id": 7, "selected": true, "priority": 1 },
      { "id": 12, "selected": true, "priority": 2 }
    ]
  }
}
Response 200
{
  "success": true,
  "data": {
    "npiTypes": [
      {
        "id": 3,
        "reach": 2
      }
    ],
    "specialties": [
      {
        "id": 406099999,
        "reach": 2
      },
      {
        "id": 406000018,
        "reach": 2
      },
      {
        "id": 406000136,
        "reach": 1
      },
      {
        "id": 406000106,
        "reach": 1
      }
    ],
    "accountStats": {
      "accountsTypeCount": 1,
      "accountsCount": 2,
      "accounts": [
        {
          "id": 440023,
          "reach": 1
        },
        {
          "id": 440016,
          "reach": 1
        }
      ]
    },
    "dataPartnerStats": {
      "partners": [
        {
          "id": 7,
          "reach": 2,
          "coverage": 100
        },
        {
          "id": 8,
          "reach": 2,
          "coverage": 100
        },
        {
          "id": 10,
          "reach": 2,
          "coverage": 100
        }
      ],
      "venn": [
        {
          "partnerIds": [
            7
          ],
          "count": 0,
          "reach": 2,
          "coveragePercentage": 100,
          "intersectionPercentage": 100
        },
        {
          "partnerIds": [
            8
          ],
          "count": 0,
          "reach": 2,
          "coveragePercentage": 100,
          "intersectionPercentage": 100
        },
        {
          "partnerIds": [
            10
          ],
          "count": 0,
          "reach": 2,
          "coveragePercentage": 100,
          "intersectionPercentage": 100
        },
        {
          "partnerIds": [
            7,
            8
          ],
          "count": 0,
          "reach": 2,
          "coveragePercentage": 100,
          "intersectionPercentage": 100
        },
        {
          "partnerIds": [
            7,
            10
          ],
          "count": 0,
          "reach": 2,
          "coveragePercentage": 100,
          "intersectionPercentage": 100
        },
        {
          "partnerIds": [
            8,
            10
          ],
          "count": 0,
          "reach": 2,
          "coveragePercentage": 100,
          "intersectionPercentage": 100
        },
        {
          "partnerIds": [
            7,
            8,
            10
          ],
          "count": 2,
          "reach": 2,
          "coveragePercentage": 100,
          "intersectionPercentage": 100
        }
      ]
    }
  }
}

Get audience summary​

POST

This endpoint retrieves aggregated audience reach and audience count per audience block based on the provided plan configuration. It validates user access and the Healthcare vertical before processing.

Use this endpoint to preview the size and composition of each audience block before generating campaigns.

Request schema
npiTypeIds
array of integers		NPI type IDs.
Supported values
3HCP
4NPI nurse
audienceBlocks
array of objects		Array of audience block objects.
audienceBlocks object properties
audienceSelectionMethodId
integer		Audience selection method ID.
Supported values
1Filter based
2Upload NPI list
3Existing audience
4Account based
speciality
object		Specialties to target. Required for filter based, upload NPI list, and account based blocks.
speciality object properties
specialityIds
array of integers		Specialty IDs to target. Must be empty when allSpecialitiesSelected is true.
allSpecialitiesSelected
boolean		Set to true to target all specialties, with an empty specialityIds list.
account
object		Accounts to target. Required for account based blocks.
account object properties
accountIds
array of integers		Account IDs to target. Must be empty when allAccountsSelected is true.
allAccountsSelected
boolean		Set to true to target all accounts, with an empty accountIds list.
accountType
object		Account types to target. Required for account based blocks.
accountType object properties
accountTypeIds
array of integers		Account type IDs to target. Must be empty when allAccountTypesSelected is true.
allAccountTypesSelected
boolean		Set to true to target all account types, with an empty accountTypeIds list.
healthSystem
object		Health systems to target. Required for account based blocks.
healthSystem object properties
healthSystemIds
array of integers		Health system IDs to target. Must be empty when allHealthSystemsSelected is true.
allHealthSystemsSelected
boolean		Set to true to target all health systems, with an empty healthSystemIds list.
title
object		Titles to target. Required for account based blocks.
title object properties
titleIds
array of integers		Title IDs to target. Must be empty when allTitlesSelected is true.
allTitlesSelected
boolean		Set to true to target all titles, with an empty titleIds list.
locations
object		Locations to target. Required for filter based, upload NPI list, and account based blocks.
locations object properties
countryId
integer		Country ID; must be 30100001 (United States).
whiteListedStateIds
array of integers		State IDs to target.
blackListedStateIds
array of integers		State IDs to exclude.
whiteListedCityIds
array of integers		City IDs to target.
blackListedCityIds
array of integers		City IDs to exclude.
whiteListedZipcodes
array of strings		ZIP codes to target.
blackListedZipcodes
array of strings		ZIP codes to exclude. Targeted and excluded locations can't overlap.
dataPartners
array of objects		Data partners to match the audience with. At least one must be selected. Required for filter based, upload NPI list, and account based blocks.
dataPartners object properties
id
integer		Data partner ID. Account based blocks support only 7 and 12.
Supported values
7Healthlink ID
8Data360 ID
11Purple Lab ID
12RevOptimal ID
selected
boolean		Set to true to use this data partner.
priority
integer		Order of preference, starting at 1; can't be higher than the number of data partners in the block.
reach
integer		Data partner reach.
incrementalReach
integer		Reach this data partner adds on top of higher-priority data partners; 0 to reach.
storagePathId
integer		Upload NPI list blocks only: file ID of the uploaded NPI list.
storagePath
string		Upload NPI list blocks only: storage path of the uploaded NPI list file.
storageFileName
string		Upload NPI list blocks only: name of the uploaded NPI list file.
storageFileSize
integer		Upload NPI list blocks only: size of the uploaded NPI list file.
storageFileRows
integer		Upload NPI list blocks only: number of rows in the uploaded NPI list file.
includeAudienceIds
array of integers		Existing audience blocks only: audience IDs to include. Up to 14 included and excluded audiences in total.
excludeAudienceIds
array of integers		Existing audience blocks only: audience IDs to exclude. Can't overlap with includeAudienceIds.
planLevelTargeting
object		Plan-level targeting object.
planLevelTargeting object properties
devices
object		Devices to target.
devices object properties
deviceTypeIds
array of integers		Device type IDs to target. Must be empty when allDeviceTypesSelected is true.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
allDeviceTypesSelected
boolean		Set to true to target all device types, with an empty deviceTypeIds list.
channels
object		Channels to target.
channels object properties
channelTypeIds
array of integers		Channel type IDs to target. Must be empty when allChannelTypesSelected is true.
Supported values
11App
14CTV
13OTT
12Web
allChannelTypesSelected
boolean		Set to true to target all channels, with an empty channelTypeIds list.
creativeTypes
object		Creative types to target.
creativeTypes object properties
creativeTypeIds
array of integers		Creative type IDs to target. Must be empty when allCreativeTypesSelected is true.
Supported values
11Image
13HTML
14Video
15Native
17Audio
allCreativeTypesSelected
boolean		Set to true to target all creative types, with an empty creativeTypeIds list.
isTvAutoBuying
boolean		Whether TV auto buying is enabled; requires video creatives (14).
inventory
object		Inventory to target.
inventory object properties
openExchanges
object		Open Exchange inventory to target.
openExchanges object properties
exchangeIds
array of integers		Exchange IDs to target. Must be empty when allExchangesSelected is true.
allExchangesSelected
boolean		Set to true to target all exchanges, with an empty exchangeIds list.
iabCategoryIds
array of integers		IAB category IDs to target. Must be empty when allIabCategoriesSelected is true.
allIabCategoriesSelected
boolean		Set to true to target all IAB categories, with an empty iabCategoryIds list.
inventoryGroup
object		Inventory groups to target. Send null unless you target inventory groups. Returned as an empty object in plan details when none are targeted.
inventoryGroup object properties
inventoryGroupIds
array of integers		Inventory group IDs to target.
allInventoryGroupsSelected
boolean		Set to true to target all inventory groups, with an empty inventoryGroupIds list.

Response properties
audienceSummary
array of objects		Audience summary array.
audienceSummary object properties
audienceSelectionMethodId
integer		Audience selection method ID.
reach
integer		Audience reach count.
audienceCount
integer		Number of audiences.
Request sample
{
  "npiTypeIds": [3, 4],
  "audienceBlocks": [
    {
      "audienceSelectionMethodId": 1,
      "speciality": {
        "specialityIds": [],
        "allSpecialitiesSelected": true
      },
      "account": null,
      "accountType": null,
      "healthSystem": null,
      "title": null,
      "locations": {
        "countryId": 30100001,
        "whiteListedStateIds": [],
        "blackListedStateIds": [],
        "whiteListedCityIds": [],
        "blackListedCityIds": [],
        "whiteListedZipcodes": [],
        "blackListedZipcodes": []
      },
      "dataPartners": [
        {
          "id": 12,
          "reach": 0,
          "incrementalReach": 0,
          "priority": 4,
          "selected": true
        },
        {
          "id": 7,
          "reach": 0,
          "incrementalReach": 0,
          "priority": 1,
          "selected": true
        }
      ],
      "storagePathId": null,
      "storagePath": null,
      "storageFileName": null,
      "storageFileSize": null,
      "storageFileRows": null,
      "includeAudienceIds": [],
      "excludeAudienceIds": []
    }
  ],
  "planLevelTargeting": {
    "devices": {
      "deviceTypeIds": [20300002, 20300001],
      "allDeviceTypesSelected": false
    },
    "creativeTypes": {
      "creativeTypeIds": [11],
      "allCreativeTypesSelected": false,
      "isTvAutoBuying": false
    },
    "channels": {
      "channelTypeIds": [21100001, 21100003],
      "allChannelTypesSelected": false
    },
    "inventory": {
      "inventoryGroup": {
        "inventoryGroupIds": [190634, 190827],
        "allInventoryGroupsSelected": false
      }
    }
  }
}
Response 200
{
  "success": true,
  "data": {
    "audienceSummary": [
      {
        "audienceSelectionMethodId": 1,
        "reach": 485207,
        "audienceCount": 2
      },
      {
        "audienceSelectionMethodId": 4,
        "reach": 6539272,
        "audienceCount": 1
      }
    ]
  }
}

Generate campaigns plan​

POST

Generate proposed campaigns from a plan configuration. This is the first step in creating an HCP plan. IQM builds the campaigns from the split strategy, forecasts their reach, and calculates each campaign's CPM, impressions, and budget range, along with the plan's totals. Nothing is saved.

Send the plan without totals or campaigns. The response data is the request body for Create HCP Planner.

Each campaign's dataCpm is the average data cost of its selected data partners, and its mediaCpm depends on its creative type. The selectedValueIds in splitStrategy are ignored: campaigns are created for every plan-level value of each listed dimension.

Request sample
{
  "name": "Q4 Cardiology Awareness",
  "startTime": 1793505600000,
  "endTime": 1796101199000,
  "timezoneId": 29,
  "budgetTypeId": 1,
  "frequencyCap": 3,
  "frequencyCapTypeId": 1,
  "npiTypeIds": [3, 4],
  "audienceBlocks": [
    {
      "audienceSelectionMethodId": 1,
      "speciality": {
        "specialityIds": [],
        "allSpecialitiesSelected": true
      },
      "locations": {
        "countryId": 30100001,
        "whiteListedStateIds": [],
        "blackListedStateIds": [],
        "whiteListedCityIds": [],
        "blackListedCityIds": [],
        "whiteListedZipcodes": [],
        "blackListedZipcodes": []
      },
      "dataPartners": [
        { "id": 7, "selected": true, "priority": 1 },
        { "id": 8, "selected": true, "priority": 2 }
      ]
    }
  ],
  "planLevelTargeting": {
    "devices": {
      "deviceTypeIds": [20300001, 20300004],
      "allDeviceTypesSelected": false
    },
    "creativeTypes": {
      "creativeTypeIds": [11, 14],
      "allCreativeTypesSelected": false,
      "isTvAutoBuying": false
    },
    "channels": {
      "channelTypeIds": [],
      "allChannelTypesSelected": true
    },
    "inventory": {
      "openExchanges": {
        "exchangeIds": [],
        "allExchangesSelected": true,
        "iabCategoryIds": [],
        "allIabCategoriesSelected": true
      },
      "inventoryGroup": null
    }
  },
  "splitStrategy": [
    { "splitDimensionTypeId": 1, "selectedValueIds": [11, 14] },
    { "splitDimensionTypeId": 2, "selectedValueIds": [3, 4] }
  ]
}
Response 200 (abbreviated)
{
  "success": true,
  "data": {
    "name": "Q4 Cardiology Awareness",
    "startTime": 1793505600000,
    "endTime": 1796101199000,
    "timezoneId": 29,
    "budgetTypeId": 1,
    "minBudget": 98.00,
    "budget": 8820.00,
    "maxBudget": 8820.00,
    "reach": 60000,
    "maxReach": 60000,
    "minImpressions": 4000,
    "impressions": 360000,
    "maxImpressions": 360000,
    "frequencyCap": 3,
    "frequencyCapTypeId": 1,
    "npiTypeIds": [3, 4],
    "audienceBlocks": [ ... ],
    "planLevelTargeting": { ... },
    "splitStrategy": [ ... ],
    "campaigns": [
      {
        "id": null,
        "name": "Video - Physicians",
        "startTime": 1793505600000,
        "endTime": 1796101199000,
        "frequencyCap": 3,
        "frequencyCapTypeId": 1,
        "minMediaCpm": 18.00,
        "mediaCpm": 18.00,
        "maxMediaCpm": 18.00,
        "dataCpm": 12.50,
        "minBudget": 30.50,
        "budget": 3843.00,
        "maxBudget": 3843.00,
        "minReach": 10,
        "reach": 42000,
        "maxReach": 42000,
        "minImpressions": 1000,
        "impressions": 126000,
        "maxImpressions": 126000,
        "isAbm": false,
        "targeting": {
          "dataPartnerIds": [7, 8],
          "creativeTypeId": 14,
          "deviceTypeIds": [20300001, 20300004],
          "npiTypeId": 3,
          "audienceTypeIds": [1]
        }
      },
      ...
    ]
  }
}

Publish campaigns plan​

POST

Publish an HCP plan to create an IO and campaigns. Send the full plan with its id and current statusId. Publishing first saves the request body with the same checks as Update HCP Planner, so the same request rules apply. Only Advertiser Organizations can publish plans.

Publishing is asynchronous. The plan moves to Processing (5) while the IO and campaigns are created, then to IO Created (7), with ioId and each campaign's campaignId set. If publishing fails, the plan moves to Failed (4). The response only confirms that publishing has started: use HCP Planner details by ID to check the result.

The campaigns are created as drafts. They don't run until creatives are attached and the campaigns are approved.

Request schema
id
integer		Plan ID of the plan to publish. Without an id, a new plan is created and published.
statusId
integer		The plan's current status ID. Send it back unchanged.
Supported values
2Draft
3Expired
4Failed
5Processing
6Ready
7IO Created
minBudget
number		Minimum plan budget, from the generate campaigns response. Required for Ready plans.
minImpressions
integer		Minimum plan impressions, from the generate campaigns response. Required for Ready plans.
planLevelTargeting
object required		Creative type, device, channel, and inventory targeting for the whole plan.
planLevelTargeting object properties
inventory
object required		Inventory to target.
inventory object properties
inventoryGroup
object		Inventory groups to target. Send null unless you target inventory groups.
campaigns
array of objects required		Proposed campaigns. Publishing re-creates the campaigns with new id values.
Request sample (abbreviated)
{
  "id": 4512,
  "statusId": 6,
  "name": "Q4 Cardiology Awareness",
  "startTime": 1793505600000,
  "endTime": 1796101199000,
  "timezoneId": 29,
  "budgetTypeId": 1,
  "minBudget": 98.00,
  "budget": 8820.00,
  "maxBudget": 8820.00,
  "minImpressions": 4000,
  "impressions": 360000,
  "maxImpressions": 360000,
  "frequencyCap": 3,
  "frequencyCapTypeId": 1,
  "npiTypeIds": [3, 4],
  "audienceBlocks": [ ... ],
  "planLevelTargeting": {
    "devices": { ... },
    "creativeTypes": { ... },
    "channels": { ... },
    "inventory": {
      "openExchanges": { ... },
      "inventoryGroup": null
    }
  },
  "splitStrategy": [ ... ],
  "campaigns": [ ... ]
}
Response 200
{
  "success": true,
  "data": {
    "message": "Campaign generation is in progress"
  }
}
More responses
Response 422
{
  "success": false,
  "errorObjects": [
    {
      "error": "Proposal cannot be edited in its current status."
    }
  ]
}

More HCP details​

Get split strategy list​

GET

Get the list of available split strategies for HCP plans.

Response properties
id
integer		Split strategy ID.
name
string		Split strategy name.
order
integer		Order.
displayName
string		Display name.
Response 200
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "creative_type",
      "order": 1,
      "displayName": "Creative Type"
    },
    {
      "id": 2,
      "name": "npi_type",
      "order": 2,
      "displayName": "NPI Type"
    },
    {
      "id": 3,
      "name": "partner",
      "order": 3,
      "displayName": "Partner"
    },
    {
      "id": 4,
      "name": "device_type",
      "order": 4,
      "displayName": "Device Type"
    },
    {
      "id": 5,
      "name": "audience_type",
      "order": 5,
      "displayName": "Audience Type"
    }
  ]
}

NPI type list​

GET

Get the list of available NPI types for HCP plans.

Response properties
id
integer		NPI type ID.
name
string		NPI type name.
order
integer		Order.
displayName
string		NPI type display name.
Response 200
{
  "success": true,
  "data": [
    {
      "id": 3,
      "name": "hcp",
      "order": 3,
      "displayName": "HCP"
    },
    {
      "id": 4,
      "name": "npi_nurse",
      "order": 4,
      "displayName": "NPI Nurse"
    }
  ]
}

Get geography segments​

GET

Get the list of available geography segments for HCP plans.

Response properties
id
integer		Geography segment ID.
name
string		Geography segment name.
order
integer		Order.
displayName
string		Display name.
Response 200
{
  "success": true,
  "data": [
    {
      "id": 302,
      "name": null,
      "order": 1,
      "displayName": "State"
    },
    {
      "id": 304,
      "name": null,
      "order": 4,
      "displayName": "City"
    }
  ]
}

Get data partners list​

GET

Get the list of available data partners for HCP Planners. Account based audience blocks support only Healthlink (7) and RevOptimal (12).

Response properties
id
integer		Data partner ID.
name
string		Data partner name.
order
integer		Order.
displayName
string		Data partner display name.
dataCost
integer		Data cost.
logoUrl
string		Logo URL.
Response 200
{
  "success": true,
  "data": [
    {
      "id": 7,
      "name": "hl_npi_id",
      "order": 6,
      "displayName": "Healthlink ID",
      "dataCost": 10,
      "logoUrl": "https://advp0had0vuj7rad3niaw1eus2-stage.s3.us-east-1.amazonaws.com/data_partner/hld.png"
    },
    {
      "id": 8,
      "name": "data360_npi_id",
      "order": 7,
      "displayName": "Data360 ID",
      "dataCost": 15,
      "logoUrl": "https://advp0had0vuj7rad3niaw1eus2-stage.s3.us-east-1.amazonaws.com/data_partner/D360.png"
    },
    {
      "id": 11,
      "name": "pl_npi_id",
      "order": 10,
      "displayName": "Purple Lab ID",
      "dataCost": 15,
      "logoUrl": "https://advp0had0vuj7rad3niaw1eus2-stage.s3.us-east-1.amazonaws.com/data_partner/pl.png"
    },
    {
      "id": 12,
      "name": "ro_npi_id",
      "order": 11,
      "displayName": "RevOptimal ID",
      "dataCost": 8,
      "logoUrl": "https://advp0had0vuj7rad3niaw1eus2-stage.s3.us-east-1.amazonaws.com/data_partner/ro.png"
    }
  ]
}

Get audience selection methods list​

GET

Get the list of available audience selection methods for HCP plans.

Response properties
id
integer		Audience selection method ID.
name
string		Audience selection method name.
order
integer		Order.
displayName
string		Audience selection method display name.
Response 200
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "filter_based",
      "order": 1,
      "displayName": "Filter Based"
    },
    {
      "id": 2,
      "name": "npi_upload",
      "order": 2,
      "displayName": "Upload NPI List"
    },
    {
      "id": 3,
      "name": "existing_audience",
      "order": 3,
      "displayName": "Existing Audience"
    },
    {
      "id": 4,
      "name": "abm_block",
      "order": 4,
      "displayName": "Account Based"
    }
  ]
}

Get specialties list​

GET

Get the list of available specialties for HCP plans.

Query parameters
pageNo
integer		Page number of retrieved data, default: 1.
noOfEntries
integer		Number of entries returned per page, default: 50.
searchField
string		Filter results by search field.
sortBy
string		Sorts by ascending (+) or descending (-), default: +displayName.
Supported values: name, id, createdOn.
specialityIds
array of integers		Filter by specialty IDs.
Response 200
{
  "success": true,
  "data": {
    "specialitiesList": [
      {
        "id": 40500003,
        "name": "Addiction Medicine",
        "displayName": "Addiction Medicine",
        "displayOrder": 3
      },
      {
        "id": 40500004,
        "name": "Addiction Medicine",
        "displayName": "Addiction Medicine",
        "displayOrder": 3
      }
    ],
    "totalRecords": 2,
    "filteredRecords": 2
  }
}

Get account types​

GET

Get the list of available account types for HCP plans.

Query parameters
pageNo
integer		Page number of retrieved data, default: 1.
noOfEntries
integer		Number of entries returned per page, default: 50.
searchField
string		Filter results by search field.
sortBy
string		Sorts by ascending (+) or descending (-), default: -reach.
Supported values: name, id, createdOn.
Response properties
id
integer		Account type ID.
name
string		Account type name.
displayName
string		Account type display name.
displayOrder
integer		Display order.
accountCount
integer		Account count.
Response 200
{
  "success": true,
  "data": {
    "accountTypesList": [
      {
        "id": 1,
        "name": "Individual",
        "displayName": "Individual",
        "displayOrder": 1,
        "accountCount": 1
      },
      {
        "id": 2,
        "name": "Organization",
        "displayName": "Organization",
        "displayOrder": 2,
        "accountCount": 1
      }
    ],
    "totalRecords": 2,
    "filteredRecords": 2
  }
}
Have a question?
Ask the community
Was this page helpful?