Skip to main content

Planner API

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

Read more about HCP Planners in our Help Center article.

Healthcare proposal Planner details​

HCP Planner resource properties​

Resource properties
id
integer		Plan ID.
name
string		Plan name.
startDate / startTime
integer		Unix epoch start date, in milliseconds.
startTime is the request parameter, startDate is the response property.
endDate / endTime
integer		Unix epoch end date, in milliseconds.
endTime is the request parameter, endDate is the response property.
timezoneId
integer		Timezone ID specifies the data collection start time.
budgetTypeId
integer		Budget type ID: budget(1) or impression(2).
budget
integer		Planned budget.
maxBudget
integer		Maximum budget.
workspaceMarginPercentage
integer		Margin percentage applied on top of each campaign's media CPM when calculating mediaCpm. Automatically populated server-side from the Organization's configured margin, not a value the caller sets directly.
reach
integer		Reach.
maxReach
integer		Maximum reach.
impressions / impression
integer		Impressions.
impression is the request parameter, impressions is the response property.
maxImpressions
integer		Maximum impressions.
frequencyCap
integer		Frequency cap.
frequencyCapTypeId
integer		Frequency cap type ID.
Supported values
1Day(s)
2Week(s)
3Month(s)
4Campaign duration
statusId
integer		Status ID.
On edit requests and on Publish campaigns plan, this value must exactly match the plan's current status in the database, or the request is rejected with "Proposal cannot be edited in its current status."
Supported values
1Converted
2Draft
3Expired
4Failed
5Processing
6Ready
npiTypeIds
array of integers		NPI type IDs.
Must match the NPI dimension's splitStrategy[].selectedValueIds and every campaigns[].targeting.npiTypeId used, see Targeting consistency rule.
Supported values
3HCP
4NPI nurse
audienceBlocks
array of objects		Audience blocks object.
audienceBlocks object properties
audienceSelectionMethodId
integer		Audience selection method ID.
Supported values
1Filter audience
2Upload NPI list
3Existing audience
speciality
object		Specialty object.
speciality object properties
specialityIds
array of integers		Specialty IDs.
allSpecialitiesSelected
boolean		All specialties selected.
accounts
array of objects		Accounts object.
accounts object properties
accountTypeId
integer		Account type ID.
Supported values
1Individual
2Organization
accountIds
array of integers		Account IDs.
allAccountsSelected
boolean		All accounts selected.
locations
object		Locations object.
locations object properties
countryId
integer		Country ID.
whiteListedStateIds
array of integers		Whitelisted State IDs.
blackListedStateIds
array of integers		Blacklisted State IDs.
whiteListedCityIds
array of integers		Whitelisted City IDs.
blackListedCityIds
array of integers		Blacklisted City IDs.
whiteListedZipcodes
array of strings		Whitelisted Zipcode IDs.
blackListedZipcodes
array of strings		Blacklisted Zipcode IDs.
dataPartners
array of objects		One entry per selected data partner, matching the partner dimension's splitStrategy[].selectedValueIds and every campaigns[].targeting.dataPartnerIds used, see Targeting consistency rule.
dataPartners object properties
id
integer		Data Partner ID.
Supported values
7Healthlink ID
8Data360 ID
10IQVIA ID
selected
boolean		Data partner is selected.
storagePathId
integer		Storage path ID.
storagePath
string		Storage path.
storageFileName
string		Storage file name.
storageFileSize
integer		Storage file size.
storageFileRows
integer		Storage file rows.
includeAudienceIds
array of integers		Included Audience IDs.
excludeAudienceIds
array of integers		Excluded Audience IDs.
selectedAudienceTypeIds
array of integers		Selected audience type IDs for this block.
The union of this field across all audienceBlocks must match the audience type dimension's splitStrategy[].selectedValueIds and every campaigns[].targeting.audienceTypeIds used, see Targeting consistency rule.
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
planLevelTargeting
object		Plan level targeting object.
planLevelTargeting object properties
devices
object		Devices object.
devices object properties
deviceTypeIds
array of integers		Device type IDs.
When allDeviceTypesSelected is false, must match the device dimension's splitStrategy[].selectedValueIds and every campaigns[].targeting.deviceTypeIds used, see Targeting consistency rule.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
allDeviceTypesSelected
boolean		All device types selected.
channels
object		Channels object.
channels object properties
channelTypeIds
array of integers		Channel type IDs.
Supported values
21100001App
21100002OTT App
21100003Web
allChannelTypesSelected
boolean		All channel types selected.
creativeTypes
object		Creative types object.
creativeTypes object properties
creativeTypeIds
array of integers		Creative type IDs.
When allCreativeTypesSelected is false, must match the creative dimension's splitStrategy[].selectedValueIds and every campaigns[].targeting.creativeTypeId used, see Targeting consistency rule.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
allCreativeTypesSelected
boolean		All creative types selected.
inventory
object		Inventory object.
inventory object properties
openExchangeVO
object		Open exchange VO object.
openExchangeVO object properties
exchangeIds
array of integers		Exchange IDs.
allExchangesSelected
boolean		All exchanges selected.
iabCategoryIds
array of integers		IAB category IDs.
allIabCategoriesSelected
boolean		All IAB categories selected.
inventoryGroup
object		Inventory group object.
inventoryGroup object properties
inventoryGroupIds
array of integers		Inventory group IDs.
allInventoryGroupsSelected
boolean		All inventory groups selected.
splitStrategy
array of objects		Split strategy object.
splitStrategy object properties
splitDimensionType
object		Split dimension type object.
splitDimensionType object properties
id
integer		Split dimension ID.
Supported values
1Creative type
2NPI type
3Partner
4Device type
5Audience type
name
string		Name.
displayName
string		Display name.
order
integer		Order.
selectedValueIds
array of integers		Selected Value IDs for this split dimension must exactly match both the plan-level selection and every value actually used in campaigns[] for the corresponding dimension, or the request is rejected. See the Targeting consistency rule for the exact mapping per splitDimensionType.id.
campaigns
array of objects		Campaigns object.
campaigns object properties
id
integer		Campaign ID.
name
string		Campaign name.
startDate
integer		Unix epoch start date, in milliseconds.
endDate
integer		Unix epoch end date, in milliseconds.
budget
integer		Campaign budget.
maxBudget
integer		Campaign maximum budget.
mediaCpm
number		Media CPM.
dataCpm
number		Data CPM.
budgetPercentage
number		Budget percentage.
reach
integer		Reach.
maxReach
integer		Maximum reach.
frequencyCap
integer		Frequency cap.
frequencyCapTypeId
integer		Frequency cap type ID.
Supported values
1Day(s)
2Week(s)
3Month(s)
4Campaign duration
impressions
integer		Impressions.
maxImpressions
integer		Maximum impressions.
isAbm
boolean		Indicates the audience associated with the campaign is Account-Based Marketing (ABM) type: true.
targeting
object		Targeting object.
targeting object properties
dataPartnerIds
array of integers		Data partner IDs.
Must match the partner dimension's plan-level/split-strategy selection, see Targeting consistency rule.
Supported values
7Healthlink ID
8Data360 ID
10IQVIA ID
creativeTypeId
integer		Creative type ID.
Singular: one creative type per campaign. Must match the creative dimension's plan-level/split-strategy selection, see Targeting consistency rule.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
deviceTypeIds
array of integers		Device type IDs.
Must match the device dimension's plan-level/split-strategy selection, see Targeting consistency rule.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
npiTypeId
integer		NPI type ID.
Singular: one NPI type per campaign. Must match the NPI dimension's plan-level/split-strategy selection, see Targeting consistency rule.
Supported values
3HCP
4NPI nurse
audienceTypeIds
array of integers		Audience type IDs.
Must match the audience type dimension's plan-level/split-strategy selection, see Targeting consistency rule.
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

Targeting consistency rule​

The values selected in planLevelTargeting and each audienceBlocks entry must agree with the corresponding splitStrategy[].selectedValueIds entry and with every campaigns[].targeting value actually used. This applies across 5 dimensions. A mismatch on any dimension is rejected with a generic error that does not say which field disagreed, so it's worth getting these right before submitting.

For each dimension you split on, the matching splitStrategy[] entry's selectedValueIds must exactly match both sides of the table above: the plan-level selection and every value actually used in campaigns[].

Dimension: splitDimensionType.idMust equal planLevelTargeting / audienceBlocks.Must equal campaigns[].targeting
Creative: 1planLevelTargeting.creativeTypes.creativeTypeIds (all real creative type IDs when allCreativeTypesSelected is true, otherwise the explicit list).creativeTypeId (singular)
NPI: 2Top-level npiTypeIds.npiTypeId (singular)
Partner: 3The set of dataPartners[].id across all audienceBlocks.dataPartnerIds
Device: 4planLevelTargeting.devices.deviceTypeIds (all real device type IDs when allDeviceTypesSelected is true, otherwise the explicit list).deviceTypeIds
Audience type: 5The union of selectedAudienceTypeIds across all audienceBlocks.audienceTypeIds
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": "Q1 Diabetes Awareness",
  "startTime": 1735124399000,
  "endTime": 1757534400000,
  "timezoneId": 4,
  "budgetTypeId": 1,
  "budget": 75000,
  "maxBudget": 80000,
  "frequencyCap": 5,
  "frequencyCapTypeId": 1,
  "npiTypeIds": [3, 4],
  "audienceBlocks": [
    {
      "audienceSelectionMethodId": 1,
      "speciality": {
        "specialityIds": [101, 102],
        "allSpecialitiesSelected": false
      },
      "dataPartners": [
        { "id": 7, "selected": true },
        { "id": 8, "selected": true }
      ],
      "selectedAudienceTypeIds": [1, 2]
    }
  ],
  "planLevelTargeting": {
    "devices": {
      "deviceTypeIds": [20300001, 20300004],
      "allDeviceTypesSelected": false
    },
    "creativeTypes": {
      "creativeTypeIds": [11, 14],
      "allCreativeTypesSelected": false,
      "isTvAutoBuying": true
    }
  },
  "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, 2]
    }
  ],
  "campaigns": [
    {
      "name": "Campaign A",
      "startTime": 1735124399000,
      "endTime": 1757534400000,
      "budget": 37500,
      "maxBudget": 40000,
      "frequencyCap": 5,
      "frequencyCapTypeId": 1,
      "isAbm": false,
      "targeting": {
        "dataPartnerIds": [7],
        "creativeTypeId": 11,
        "deviceTypeIds": [20300001],
        "npiTypeId": 3,
        "audienceTypeIds": [1]
      }
    }
  ]
}

HCP Planner details by ID​

GET

Get Healthcare proposal Planner details by ID.

Path parameters
planId
integer		Plan ID.
Response 200
{
  "success": true,
  "data": {
    "id": 1,
    "name": "Q4 Diabetes Awareness Campaign",
    "statusId": 2,
    "startTime": 1732707706666,
    "endTime": 1733312506666,
    "timezoneId": 3,
    "budgetTypeId": 1,
    "budget": 100000,
    "maxBudget": 120000,
    "reach": 50000,
    "maxReach": 70000,
    "impressions": 200000,
    "maxImpressions": 250000,
    "frequencyCap": 3,
    "frequencyCapTypeId": 1,
    "npiTypeIds": [3, 4],
    "audienceBlocks": [
      {
        "audienceSelectionMethodId": 1,
        "speciality": {
          "specialityIds": [406000001, 406000002],
          "allSpecialitiesSelected": false
        },
        "accounts": [
          {
            "accountTypeId": 403000007,
            "accountIds": [440016, 440023],
            "allAccountsSelected": false
          }
        ],
        "locations": {
          "countryId": 30100001,
          "whiteListedStateIds": [],
          "blackListedStateIds": [],
          "whiteListedCityIds": [],
          "blackListedCityIds": [],
          "whiteListedZipcodes": [],
          "blackListedZipcodes": []
        },
        "dataPartners": {
          "dataPartnerIds": [7, 8],
          "allDataPartnersSelected": null
        },
        "storagePathId": null,
        "storagePath": null,
        "storageFileName": null,
        "storageFileSize": null,
        "storageFileRows": null,
        "includeAudienceIds": [],
        "excludeAudienceIds": []
      },
      {
        "audienceSelectionMethodId": 2,
        "speciality": null,
        "accounts": [],
        "locations": null,
        "dataPartners": {
          "dataPartnerIds": [8, 10],
          "allDataPartnersSelected": null
        },
        "storagePath": "tmp/aud_uploads/upload_block2.csv",
        "storagePathId": 1234,
        "storageFileName": "upload_block2.csv",
        "storageFileSize": 200,
        "storageFileRows": 500,
        "includeAudienceIds": [],
        "excludeAudienceIds": []
      },
      {
        "audienceSelectionMethodId": 3,
        "speciality": null,
        "accounts": [],
        "locations": null,
        "dataPartners": null,
        "storagePath": null,
        "includeAudienceIds": [1137702, 1101834, 1101831],
        "excludeAudienceIds": [1102476]
      }
    ],
    "planLevelTargeting": {
      "devices": {
        "deviceTypeIds": [20300001, 20300002],
        "allDeviceTypesSelected": null
      },
      "channels": {
        "channelTypeIds": [11, 12],
        "allChannelTypesSelected": null
      },
      "creativeTypes": {
        "creativeTypeIds": [11, 14, 15],
        "allCreativeTypesSelected": null
      },
      "inventory": {
        "openExchangeVO": {
          "exchangeIds": [16, 19],
          "allExchangesSelected": null,
          "iabCategoryIds": [11, 21],
          "allIabCategoriesSelected": null
        },
        "inventoryGroup": null
      }
    },
    "splitStrategy": [
      {
        "splitDimensionType": {
          "id": 1,
          "name": "creative_type",
          "displayName": "Creative Type",
          "order": 1
        },
        "selectedValueIds": [1, 2]
      },
      {
        "splitDimensionType": {
          "id": 2,
          "name": "npi_type",
          "displayName": "NPI Type",
          "order": 2
        },
        "selectedValueIds": [3, 4]
      }
    ],
    "campaigns": [
      {
        "id": 1,
        "name": "Filter-Block1•Device1•Creative1",
        "startDate": 1732707706666,
        "endDate": 1733312506666,
        "budget": 16000,
        "maxBudget": 18000,
        "mediaCpm": 22.5,
        "dataCpm": 5.0,
        "budgetPercentage": 16.0,
        "reach": 11000,
        "frequencyCap": 3,
        "frequencyCapTypeId": 1,
        "maxReach": 70000,
        "impressions": 35000,
        "maxImpressions": 250000,
        "isAbm": false,
        "targeting": {
          "dataPartnerIds": [5, 7],
          "creativeTypeId": 1,
          "deviceTypeIds": [1],
          "npiTypeId": 1,
          "audienceTypeIds": []
        }
      }
    ]
  }
}

Get list of HCP Planners​

GET

Get a list of HCP Planners.

A plan id can be used in the HCP Planner details by ID endpoint and to perform various actions in Healthcare 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		Filter results by search field: account name.
sortBy
string		Sorts by ascending (+) or descending (-).
Supported values: id, name, createdBy, createdOn, startDate, reach, impression, budget.
statusIds
string		Comma separated status IDs.
budgetTypeIds
string		Comma separated budget type IDs: budget(1) or impression(2).
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.
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.
reach
integer		Reach.
impression
integer		Impression.
budget
integer		Budget.
ioId
integer		IO ID.
budgetTypeId
integer		Budget type ID.
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,
        "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 Healthcare proposal Planner file.

Request schema
planId
integer		Plan ID.
fileTypeId
integer		ID of the file type to download the plan as. Only 1 (XLSX) and 3 (PDF) are supported for this endpoint - 2 (CSV) and any other value is rejected with "Invalid file type to download HCP Plan".
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"
  }
}

Healthcare proposal Planner management​

Create HCP Planner​

POST
POST

Create a new ready or draft Healthcare proposal Planner. See resource properties for request schema.

Request sample
{
  "id": 123,
  "name": "Sample HCP Planner Request",
  "startTime": 1735124399000,
  "endTime": 1757534400000,
  "timezoneId": 4,
  "budgetTypeId": 1,
  "budget": 75000,
  "maxBudget": 80000,
  "reach": 250000,
  "maxReach": 300000,
  "impressions": 1000000,
  "maxImpressions": 1200000,
  "frequencyCap": 5,
  "frequencyCapTypeId": 1,
  "npiTypeIds": [3, 4],
  "audienceBlocks": [
    {
      "audienceSelectionMethodId": 1,
      "speciality": {
        "specialityIds": [
          101,
          102
        ],
        "allSpecialitiesSelected": false
      },
      "accounts": [
        {
          "accountTypeId": 1,
          "accountIds": [
            201,
            202
          ],
          "allAccountsSelected": false
        },
        {
          "accountTypeId": 2,
          "accountIds": [],
          "allAccountsSelected": true
        }
      ],
      "locations": {
        "countryId": 1,
        "whiteListedStateIds": [
          501,
          502
        ],
        "blackListedStateIds": [],
        "whiteListedCityIds": [],
        "blackListedCityIds": [],
        "whiteListedZipcodes": [
          90210,
          10001
        ],
        "blackListedZipcodes": []
      },
      "dataPartners": {
        "dataPartnerIds": [
          1,
          2
        ],
        "allDataPartnersSelected": false
      },
      "storagePathId": null,
      "includeAudienceIds": null,
      "excludeAudienceIds": null
    },
    {
      "audienceSelectionMethodId": 2,
      "speciality": {
        "specialityIds": [
          101,
          102
        ],
        "allSpecialitiesSelected": false
      },
      "accounts": null,
      "locations": {
        "countryId": 1,
        "whiteListedStateIds": [
          501,
          502
        ],
        "blackListedStateIds": [],
        "whiteListedCityIds": [],
        "blackListedCityIds": [],
        "whiteListedZipcodes": [
          90210,
          10001
        ],
        "blackListedZipcodes": []
      },
      "dataPartners": {
        "dataPartnerIds": [
          1,
          2
        ],
        "allDataPartnersSelected": false
      },
      "storagePathId": 1,
      "includeAudienceIds": null,
      "excludeAudienceIds": null
    },
    {
      "audienceSelectionMethodId": 3,
      "speciality": null,
      "accounts": null,
      "locations": null,
      "dataPartners": null,
      "storagePathId": null,
      "includeAudienceIds": [
        301,
        302
      ],
      "excludeAudienceIds": [
        401
      ]
    }
  ],
  "planLevelTargeting": {
    "devices": {
      "deviceTypeIds": [
        1,
        2
      ],
      "allDeviceTypesSelected": false
    },
    "channels": {
      "channelTypeIds": [
        1,
        2
      ],
      "allChannelTypesSelected": false
    },
    "creativeTypes": {
      "creativeTypeIds": [
        10,
        11
      ],
      "allCreativeTypesSelected": false,
      "isTvAutoBuying": true
    },
    "inventory": {
      "openExchanges": {
        "exchangeIds": [
          1,
          2
        ],
        "allExchangesSelected": false,
        "iabCategoryIds": [
          1,
          2
        ],
        "allIabCategoriesSelected": false
      },
      "inventoryGroup": {
        "inventoryGroupIds": [
          1,
          2
        ],
        "allInventoryGroupsSelected": false
      }
    }
  },
  "splitStrategy": [
    {
      "splitDimensionTypeId": 1,
      "selectedValueIds": [
        10,
        11
      ]
    }
  ],
  "campaigns": [
    {
      "id": null,
      "name": "Campaign A",
      "startTime": 1754942400000,
      "endTime": 1757534400000,
      "budget": 37500,
      "maxBudget": 40000,
      "mediaCpm": 50,
      "dataCpm": 15,
      "reach": 125000,
      "maxReach": 150000,
      "impressions": 500000,
      "maxImpressions": 600000,
      "isAbm": false,
      "targeting": {
        "dataPartnerIds": [
          1
        ],
        "creativeTypeId": 10,
        "deviceTypeIds": [
          1
        ],
        "npiTypeId": 1,
        "audienceTypeIds": [
          1
        ]
      }
    }
  ]
}

Update HCP Planner​

PUT

Update an existing Healthcare proposal Planner by ID. See resource properties for request schema.

Path parameters
planId
integer		Plan ID.
Response 200
{
  "success": true,
  "data": {
    "message": "Sample proposal updated successfully",
    "id": 123
  }
}

Delete HCP Planner​

DELETE

Delete one or more Healthcare proposal Planners by IDs.

Query parameters
proposalIds
string		Comma separated proposal IDs to delete.
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 a Healthcare proposal Planner name is available for use within the Organization. This endpoint also validates the name's character limit and vertical type.

Request schema
name
string		Planner name to validate.

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

Get targeting graphs​

POST

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

Use this API to visualize how different targeting dimensions are distributed across audience blocks and plan-level targeting in a Healthcare proposal Planner.

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 audience
2Upload NPI list
3Existing audience
speciality
object		Specialty object.
speciality object properties
specialityIds
array of integers		Specialty IDs.
allSpecialitiesSelected
boolean		All specialties selected.
accounts
array of objects		Accounts.
accounts object properties
accountTypeId
integer		Account type ID.
Supported values
1Individual
2Organization
accountIds
array of integers		Account IDs.
allAccountsSelected
boolean		All accounts selected.
locations
object		Locations object.
locations object properties
countryId
integer		Country ID.
whiteListedStateIds
array of integers		Whitelisted State IDs.
blackListedStateIds
array of integers		Blacklisted State IDs.
whiteListedCityIds
array of integers		Whitelisted City IDs.
blackListedCityIds
array of integers		Blacklisted City IDs.
whiteListedZipcodes
array of strings		Whitelisted Zipcode IDs.
blackListedZipcodes
array of strings		Blacklisted Zipcode IDs.
dataPartners
object		Data partners object.
dataPartners object properties
dataPartnerIds
array of integers		Data partner IDs.
allDataPartnersSelected
boolean		All data partners selected.
storagePathId
integer		Storage path ID.
storagePath
string		Storage path.
storageFileName
string		Storage file name.
storageFileSize
integer		Storage file size.
storageFileRows
integer		Storage file rows.
includeAudienceIds
array of integers		Included Audience IDs.
excludeAudienceIds
array of integers		Excluded Audience IDs.
planLevelTargeting
object		Plan level targeting object.
planLevelTargeting object properties
devices
object		Devices object.
devices object properties
deviceTypeIds
array of integers		Device type IDs.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
allDeviceTypesSelected
boolean		All device types selected.
channels
object		Channels object.
channels object properties
channelTypeIds
array of integers		Channel type IDs.
Supported values
21100001App
21100002OTT App
21100003Web
allChannelTypesSelected
boolean		All channel types selected.
creativeTypes
object		Creative types object.
creativeTypes object properties
creativeTypeIds
array of integers		Creative type IDs.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
allCreativeTypesSelected
boolean		All creative types selected.
inventory
object		Inventory.
inventory object properties
openExchangeVO
object		Open exchange VO object.
openExchangeVO object properties
exchangeIds
array of integers		Exchange IDs.
allExchangesSelected
boolean		All exchanges selected.
iabCategoryIds
array of integers		IAB category IDs.
allIabCategoriesSelected
boolean		All IAB categories selected.
inventoryGroup
object		Inventory group.
inventoryGroup object properties
inventoryGroupIds
array of integers		Inventory group IDs.
allInventoryGroupsSelected
boolean		All inventory groups selected.
owId
integer		Organization wrapper 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.
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
21100001App
21100002OTT App
21100003Web
percentage
number		Percentage.
Request sample
{
  "npiTypeIds": [3, 4],
  "audienceBlocks": [
    {
      "audienceSelectionMethodId": 1,
      "speciality": {
        "specialityIds": [406000001, 406000002],
        "allSpecialitiesSelected": false
      },
      "accounts": [
        {
          "accountTypeId": 403000007,
          "accountIds": [440016, 440023],
          "allAccountsSelected": false
        }
      ],
      "locations": {
        "countryId": 30100001,
        "whiteListedStateIds": [],
        "blackListedStateIds": [],
        "whiteListedCityIds": [],
        "blackListedCityIds": [],
        "whiteListedZipcodes": [],
        "blackListedZipcodes": []
      },
      "dataPartners": {
        "dataPartnerIds": [7, 8],
        "allDataPartnersSelected": null
      },
      "storagePathId": 0,
      "storagePath": "string",
      "storageFileName": "string",
      "storageFileSize": 0,
      "storageFileRows": 0,
      "includeAudienceIds": [
        0
      ],
      "excludeAudienceIds": [
        0
      ]
    }
  ],
  "planLevelTargeting": {
    "devices": {
      "deviceTypeIds": [20300001, 20300002],
      "allDeviceTypesSelected": null
    },
    "channels": {
      "channelTypeIds": [11, 12],
      "allChannelTypesSelected": null
    },
    "creativeTypes": {
      "creativeTypeIds": [11, 14, 15],
      "allCreativeTypesSelected": null
    },
    "inventory": {
      "openExchanges": {
        "exchangeIds": [16, 19],
        "allExchangesSelected": null,
        "iabCategoryIds": [11, 21],
        "allIabCategoriesSelected": null
      }
    }
  },
  "owId": 0
}
Response 200
{
  "success": true,
  "data": {
    "deviceTypeDistribution": {
      "totalNPIs": 2025510,
      "breakdown": [
        { "deviceTypeId": 1, "percentage": 20 },
        { "deviceTypeId": 2, "percentage": 35 },
        { "deviceTypeId": 3, "percentage": 15 },
        { "deviceTypeId": 4, "percentage": 30 }
      ]
    },
    "creativeTypeDistribution": [
      {
        "creativeTypeId": 1,
        "impressions": 1600000,
        "cpm": 72.0
      },
      {
        "creativeTypeId": 2,
        "impressions": 1200000,
        "cpm": 65.0
      }
    ],
    "channelTypeDistribution": {
      "totalNPIs": 2025510,
      "breakdown": [
        { "channelTypeId": 1, "percentage": 60 },
        { "channelTypeId": 2, "percentage": 40 }
      ]
    }
  }
}

Get audience graph​

POST

This API accepts audience block criteria and plan level targeting to return an audience graph for Healthcare proposal Planners. The audience graph contains granular reach data broken down by NPI types, specialties, and data partner overlap.

Use this API 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 audience
2Upload NPI list
3Existing audience
speciality
object		Specialty object.
speciality object properties
specialityIds
array of integers		Specialty IDs.
allSpecialitiesSelected
boolean		All specialties selected.
accounts
array of objects		Accounts.
accounts object properties
accountTypeId
integer		Account type ID.
Supported values
1Individual
2Organization
accountIds
array of integers		Account IDs.
allAccountsSelected
boolean		All accounts selected.
locations
object		Locations object.
locations object properties
countryId
integer		Country ID.
whiteListedStateIds
array of integers		Whitelisted State IDs.
blackListedStateIds
array of integers		Blacklisted State IDs.
whiteListedCityIds
array of integers		Whitelisted City IDs.
blackListedCityIds
array of integers		Blacklisted City IDs.
whiteListedZipcodes
array of strings		Whitelisted Zipcode IDs.
blackListedZipcodes
array of strings		Blacklisted Zipcode IDs.
dataPartners
object		Data partners object.
dataPartners object properties
dataPartnerIds
array of integers		Data partner IDs.
Supported values
7Healthlink ID
8Data360 ID
10IQVIA ID
allDataPartnersSelected
boolean		All data partners selected.
storagePathId
integer		Storage path ID.
storagePath
string		Storage path.
storageFileName
string		Storage file name.
storageFileSize
integer		Storage file size.
storageFileRows
integer		Storage file rows.
includeAudienceIds
array of integers		Included Audience IDs.
excludeAudienceIds
array of integers		Excluded Audience IDs.

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,
    4
  ],
  "audienceBlock": {
    "audienceSelectionMethodId": 1,
    "speciality": {
      "specialityIds": [
        1,
        2
      ],
      "allSpecialitiesSelected": false
    },
    "account": {
      "accountIds": [
        1,
        2
      ],
      "allAccountsSelected": false
    },
    "healthSystem": {
      "healthSystemIds": [],
      "allHealthSystemsSelected": true
    },
    "title": {
      "titleIds": [],
      "allTitlesSelected": true
    },
    "accountType": {
      "accountTypeIds": [],
      "allAccountTypesSelected": true
    },
    "locations": {
      "countryId": 1,
      "whiteListedStateIds": [],
      "blackListedStateIds": [],
      "whiteListedCityIds": [],
      "blackListedCityIds": [],
      "whiteListedZipcodes": [],
      "blackListedZipcodes": []
    },
    "dataPartners": {
      "dataPartnerIds": [
        1,
        2
      ],
      "allDataPartnersSelected": null
    },
    "storagePathId": null,
    "storagePath": null,
    "storageFileName": null,
    "storageFileSize": null,
    "storageFileRows": null,
    "includeAudienceIds": [],
    "excludeAudienceIds": []
  }
}
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 API retrieves aggregated audience reach and audience count per audience block based on the provided Planner configuration. It validates user access and the Healthcare vertical before processing.

Use this API 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 audience
2Upload NPI list
3Existing audience
speciality
object		Specialty object.
speciality object properties
specialityIds
array of integers		Specialty IDs.
allSpecialitiesSelected
boolean		All specialties selected.
locations
object		Locations object.
locations object properties
countryId
integer		Country ID.
whiteListedStateIds
array of integers		Whitelisted State IDs.
blackListedStateIds
array of integers		Blacklisted State IDs.
whiteListedCityIds
array of integers		Whitelisted City IDs.
blackListedCityIds
array of integers		Blacklisted City IDs.
whiteListedZipcodes
array of strings		Whitelisted Zipcode IDs.
blackListedZipcodes
array of strings		Blacklisted Zipcode IDs.
dataPartners
array of objects		Data partners array.
dataPartners object properties
dataPartnerIds
array of integers		Data partner IDs.
Supported values
7Healthlink ID
8Data360 ID
10IQVIA ID
allDataPartnersSelected
boolean		All data partners selected.
storagePathId
integer		Storage path ID.
includeAudienceIds
array of integers		Included Audience IDs.
excludeAudienceIds
array of integers		Excluded Audience IDs.
planLevelTargeting
object		Plan-level targeting object.
planLevelTargeting object properties
devices
object		Devices object.
devices object properties
deviceTypeIds
array of integers		Device type IDs.
Supported values
20300001Mobile
20300002Desktop
20300003Connected TV
20300004Tablet
20399999Unknown
allDeviceTypesSelected
boolean		All device types selected.
channels
object		Channels object.
channels object properties
channelTypeIds
array of integers		Channel type IDs.
Supported values
21100001App
21100002OTT App
21100003Web
allChannelTypesSelected
boolean		All channel types selected.
creativeTypes
object		Creative types object.
creativeTypes object properties
creativeTypeIds
array of integers		Creative type IDs.
Supported values
0All
11Image
13HTML
14Video
15Native
17Audio
allCreativeTypesSelected
boolean		All creative types selected.
inventory
object		Inventory.
inventory object properties
openExchangeVO
object		Open exchange VO object.
openExchangeVO object properties
exchangeIds
array of integers		Exchange IDs.
allExchangesSelected
boolean		All exchanges selected.
iabCategoryIds
array of integers		IAB category IDs.
allIabCategoriesSelected
boolean		All IAB categories selected.
inventoryGroup
object		Inventory group.
inventoryGroup object properties
inventoryGroupIds
array of integers		Inventory group IDs.
allInventoryGroupsSelected
boolean		All inventory groups selected.

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": [11, 12],
      "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

This API accepts a Planner configuration (audience blocks, plan-level targeting, and split strategy) and computes proposed campaigns from it — resolving real audience data via the audience API and real reach estimates via a separate data API for each generated campaign. It is a read-only computation: nothing is created or persisted by this call, so it's safe to call repeatedly while iterating on a plan's targeting.

It returns the same input data with the computed campaigns array added (sorted by reach, descending). That response can be submitted directly to Publish campaigns plan to create draft campaigns in IQM.

If you call this endpoint without id, the response has none either, and publish will create a new proposal.

If you call this endpoint with an existing proposal's id (to recompute campaigns for a proposal you already have), that ID is preserved, and the publish endpoint will instead edit that proposal.

See the full resource properties for request schema and response properties.

Request sample
{
  "name": "Q4 Diabetes Awareness Campaign",
  "startTime": 1732707706666,
  "endTime": 1733312506666,
  "timezoneId": 3,
  "budgetTypeId": 1,
  "budget": 100000,
  "maxBudget": 120000,
  "reach": 50000,
  "maxReach": 70000,
  "impressions": 200000,
  "maxImpressions": 250000,
  "frequencyCap": 3,
  "frequencyCapTypeId": 1,
  "npiTypeIds": [3, 4],
  "audienceBlocks": [
    {
      "audienceSelectionMethodId": 1,
      "speciality": {
        "allSpecialitiesSelected": true
      },
      "accounts": [
        {
          "allAccountsSelected": true
        }
      ],
      "locations": {
        "countryId": 30100001
      },
      "dataPartners": {
        "allDataPartnersSelected": true
      },
      "storagePath": null,
      "includeAudienceIds": [],
      "excludeAudienceIds": []
    },
    {
      "audienceSelectionMethodId": 2,
      "speciality": {
        "allSpecialitiesSelected": true
      },
      "accounts": [
        {
          "allAccountsSelected": true
        }
      ],
      "locations": {
        "countryId": 30100001
      },
      "dataPartners": {
        "allDataPartnersSelected": true
      },
      "storagePath": "tmp/aud_uploads/upload_block2.csv",
      "includeAudienceIds": [],
      "excludeAudienceIds": []
    },
    {
      "audienceSelectionMethodId": 3,
      "speciality": {
        "allSpecialitiesSelected": true
      },
      "accounts": [
        {
          "allAccountsSelected": true
        }
      ],
      "locations": {
        "countryId": 30100001
      },
      "dataPartners": {
        "allSpecialitiesSelected": true
      },
      "storagePath": null,
      "includeAudienceIds": [1, 2, 3],
      "excludeAudienceIds": [1, 2, 3]
    }
  ],
  "planLevelTargeting": {
    "devices": {
      "allDeviceTypesSelected": true
    },
    "channels": {
      "allChannelTypesSelected": true
    },
    "creativeTypes": {
      "allCreativeTypesSelected": true
    },
    "inventory": {
      "openExchangeVO": {
        "allExchangesSelected": true,
        "allIabCategoriesSelected": true
      },
      "inventoryGroup": {
        "allInventoryGroupsSelected": true
      }
    }
  },
  "splitStrategy": [
    { "splitDimensionTypeId": 1, "selectedValueIds": [11, 13, 14, 15, 17] },
    { "splitDimensionTypeId": 2, "selectedValueIds": [3, 4] },
    { "splitDimensionTypeId": 3, "selectedValueIds": [7] },
    { "splitDimensionTypeId": 4, "selectedValueIds": [11] },
    { "splitDimensionTypeId": 5, "selectedValueIds": [] }
  ]
}
Response 200
{
  "name": "Q4 Diabetes Awareness Campaign",
  "startTime": 1732707706666,
  "endTime": 1733312506666,
  "timezoneId": 3,
  "budgetTypeId": 1,
  "budget": 100000,
  "maxBudget": 120000,
  "reach": 50000,
  "maxReach": 70000,
  "impressions": 200000,
  "maxImpressions": 250000,
  "workspaceMarginPercentage": 20.0,
  "frequencyCap": 3,
  "frequencyCapTypeId": 1,
  "npiTypeIds": [3, 4],
  "audienceBlocks": [
    {
      "audienceSelectionMethodId": 1,
      "speciality": {
        "allSpecialitiesSelected": true
      },
      "accounts": [
        {
          "allAccountsSelected": true
        }
      ],
      "locations": {
        "countryId": 30100001
      },
      "dataPartners": {
        "allDataPartnersSelected": true
      },
      "storagePath": null,
      "includeAudienceIds": [],
      "excludeAudienceIds": []
    },
    {
      "audienceSelectionMethodId": 2,
      "speciality": {
        "allSpecialitiesSelected": true
      },
      "accounts": [
        {
          "allAccountsSelected": true
        }
      ],
      "locations": {
        "countryId": 30100001
      },
      "dataPartners": {
        "allDataPartnersSelected": true
      },
      "storagePath": "tmp/aud_uploads/upload_block2.csv",
      "includeAudienceIds": [],
      "excludeAudienceIds": []
    },
    {
      "audienceSelectionMethodId": 3,
      "speciality": {
        "allSpecialitiesSelected": true
      },
      "accounts": [
        {
          "allAccountsSelected": true
        }
      ],
      "locations": {
        "countryId": 30100001
      },
      "dataPartners": {
        "allSpecialitiesSelected": true
      },
      "storagePath": null,
      "includeAudienceIds": [1, 2, 3],
      "excludeAudienceIds": [1, 2, 3]
    }
  ],
  "planLevelTargeting": {
    "devices": {
      "allDeviceTypesSelected": true
    },
    "channels": {
      "allChannelTypesSelected": true
    },
    "creativeTypes": {
      "allCreativeTypesSelected": true
    },
    "inventory": {
      "openExchangeVO": {
        "allExchangesSelected": true,
        "allIabCategoriesSelected": true
      },
      "inventoryGroup": {
        "allInventoryGroupsSelected": true
      }
    }
  },
  "splitStrategy": [
    { "splitDimensionTypeId": 1, "selectedValueIds": [11, 13, 14, 15, 17] },
    { "splitDimensionTypeId": 2, "selectedValueIds": [3, 4] },
    { "splitDimensionTypeId": 3, "selectedValueIds": [7] },
    { "splitDimensionTypeId": 4, "selectedValueIds": [11] },
    { "splitDimensionTypeId": 5, "selectedValueIds": [] }
  ],
  "campaigns": [
    {
      "id": null,
      "name": "Campaign_Image_HCP_Healthlink_Mobile",
      "startTime": 1732707706666,
      "endTime": 1733312506666,
      "frequencyCap": 1,
      "frequencyCapTypeId": 1,
      "budget": null,
      "maxBudget": 0.0,
      "minMediaCpm": null,
      "mediaCpm": null,
      "maxMediaCpm": null,
      "dataCpm": null,
      "minReach": 0,
      "reach": null,
      "maxReach": 0,
      "impressions": null,
      "maxImpressions": 0,
      "strategy": "Image + HCP + Healthlink + Mobile",
      "targeting": {
        "dataPartnerIds": [7],
        "creativeTypeId": 11,
        "deviceTypeIds": [11],
        "npiTypeId": 3,
        "audienceTypeIds": [1, 2]
      },
      "isAbm": false
    }
  ]
}

Publish campaigns plan​

POST

Generate an insertion order and draft campaigns based on a provided Planner configuration. To generate the Planner configuration with campaigns data, use the Generate campaigns plan API.

This endpoint accepts an existing HCP Planner ID (id) and updates it with the provided Planner configuration and campaigns data. The statusId must match the status of the existing plan, or the request will fail.

If no existing HCP Planner ID is provided, a new plan will be created.

See the full resource properties for request schema and response properties.

Request sample
{
  "id": 123,
  "name": "Sample HCP Planner Request",
  "statusId": 6,
  "startTime": 1735124399000,
  "endTime": 1757534400000,
  "timezoneId": 4,
  "budgetTypeId": 1,
  "budget": 75000.00,
  "maxBudget": 80000.00,
  "reach": 250000,
  "maxReach": 300000,
  "impressions": 1000000,
  "maxImpressions": 1200000,
  "frequencyCap": 5,
  "frequencyCapTypeId": 1,
  "npiTypeIds": [1, 2],
  "audienceBlocks": [
    {
      "audienceSelectionMethodId": 1,
      "speciality": {
        "specialityIds": [101, 102],
        "allSpecialitiesSelected": false
      },
      "locations": {
        "countryId": 1,
        "whiteListedStateIds": [501, 502],
        "blackListedStateIds": [],
        "whiteListedCityIds": [],
        "blackListedCityIds": [],
        "whiteListedZipcodes": [90210, 10001],
        "blackListedZipcodes": []
      },
      "dataPartners": [
        {
          "id": 7,
          "reach": 10000,
          "priority": 1,
          "isSelected": true,
          "incrementalReach": 5000
        },
        {
          "id": 8,
          "reach": 10000,
          "priority": 2,
          "isSelected": true,
          "incrementalReach": 5000
        },
        {
          "id": 10,
          "reach": 10000,
          "priority": 3,
          "isSelected": true,
          "incrementalReach": 5000
        }
      ]
    },
    {
      "audienceSelectionMethodId": 2,
      "speciality": {
        "specialityIds": [101, 102],
        "allSpecialitiesSelected": false
      },
      "locations": {
        "countryId": 1,
        "whiteListedStateIds": [501, 502],
        "blackListedStateIds": [],
        "whiteListedCityIds": [],
        "blackListedCityIds": [],
        "whiteListedZipcodes": [90210, 10001],
        "blackListedZipcodes": []
      },
      "dataPartners": [
        {
          "id": 7,
          "reach": 10000,
          "priority": 1,
          "isSelected": true,
          "incrementalReach": 5000
        },
        {
          "id": 8,
          "reach": 10000,
          "priority": 2,
          "isSelected": true,
          "incrementalReach": 5000
        },
        {
          "id": 10,
          "reach": 10000,
          "priority": 3,
          "isSelected": true,
          "incrementalReach": 5000
        }
      ],
      "storagePathId": 1
    },
    {
      "audienceSelectionMethodId": 3,
      "includeAudienceIds": [301, 302],
      "excludeAudienceIds": [401]
    },
    {
      "audienceSelectionMethodId": 4,
      "speciality": {
        "specialityIds": [101, 102],
        "allSpecialitiesSelected": false
      },
      "accounts": [
        {
          "accountTypeId": 1,
          "accountIds": [201, 202],
          "allAccountsSelected": false
        },
        {
          "accountTypeId": 2,
          "accountIds": [],
          "allAccountsSelected": true
        }
      ],
      "locations": {
        "countryId": 1,
        "whiteListedStateIds": [501, 502],
        "blackListedStateIds": [],
        "whiteListedCityIds": [],
        "blackListedCityIds": [],
        "whiteListedZipcodes": [90210, 10001],
        "blackListedZipcodes": []
      },
      "dataPartners": [
        {
          "id": 7,
          "reach": 10000,
          "priority": 1,
          "isSelected": true,
          "incrementalReach": 5000
        },
        {
          "id": 8,
          "reach": 10000,
          "priority": 2,
          "isSelected": true,
          "incrementalReach": 5000
        },
        {
          "id": 10,
          "reach": 10000,
          "priority": 3,
          "isSelected": true,
          "incrementalReach": 5000
        }
      ]
    }
  ],
  "planLevelTargeting": {
    "devices": {
      "deviceTypeIds": [1, 2],
      "allDeviceTypesSelected": false
    },
    "channels": {
      "channelTypeIds": [1, 2],
      "allChannelTypesSelected": false
    },
    "creativeTypes": {
      "creativeTypeIds": [10, 11],
      "allCreativeTypesSelected": false,
      "isTvAutoBuying": true
    },
    "inventory": {
      "openExchanges": {
        "exchangeIds": [1, 2],
        "allExchangesSelected": false,
        "iabCategoryIds": [1, 2],
        "allIabCategoriesSelected": false
      },
      "inventoryGroup": {
        "inventoryGroupIds": [1, 2],
        "allInventoryGroupsSelected": false
      }
    }
  },
  "splitStrategy": [
    {
      "splitDimensionTypeId": 1,
      "selectedValueIds": [10, 11]
    }
  ],
  "campaigns": [
    {
      "id": null,
      "name": "Campaign A",
      "startTime": 1754942400000,
      "endTime": 1757534400000,
      "budget": 37500.00,
      "maxBudget": 40000.00,
      "mediaCpm": 50.0,
      "dataCpm": 15.0,
      "reach": 125000,
      "maxReach": 150000,
      "impressions": 500000,
      "maxImpressions": 600000,
      "isAbm": false,
      "targeting": {
        "dataPartnerIds": [1],
        "creativeTypeId": 10,
        "deviceTypeIds": [1],
        "npiTypeId": 1,
        "audienceTypeIds": [1]
      }
    }
  ]
}
Response 200
{
  "success": true,
  "data": {
    "message": "Campaign generation is in progress"
  }
}

More HCP details​

Get split strategy list​

GET

Get the list of available split strategies for Healthcare proposal Planners.

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 Healthcare proposal Planners.

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 Healthcare proposal Planners.

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 Healthcare proposal Planners.

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": 10,
      "name": "iqvia_npi_id",
      "order": 9,
      "displayName": "IQVIA ID",
      "dataCost": 25,
      "logoUrl": "https://advp0had0vuj7rad3niaw1eus2-stage.s3.us-east-1.amazonaws.com/data_partner/iqvia.png"
    }
  ]
}

Get audience selection methods list​

GET

Get the list of available audience selection methods for Healthcare proposal Planners.

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 Audience"
    },
    {
      "id": 2,
      "name": "npi_upload",
      "order": 2,
      "displayName": "Upload NPI List"
    },
    {
      "id": 3,
      "name": "existing_audience",
      "order": 3,
      "displayName": "Existing Audience"
    }
  ]
}

Get specialties list​

GET

Get the list of available specialties for Healthcare proposal Planners.

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 Healthcare proposal Planners.

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?