Creates or modifies a campaign. If the request includes a valid Campaign ID, the existing Campaign will be modified; if the ID field is omitted or the value is null, a new Campaign will be created.
Note
io_number and externalCampaignId both serve the same purpose and refer to the same value: an external ID for use by clients. These fields point to the same value; on input, a caller should use one field or the other, not both; on output, both fields are provided (currently), and will have the same value.
Request
POST /campaign/save
Request Body
Name | Type | Description | Required |
|---|---|---|---|
id | Number | Campaign ID. | Required for update. |
advertiserId | Number | Advertiser ID associated with the campaign. | Yes |
name | String | Campaign name. | Yes |
domain | String | The advertiser domain for the campaign (e.g. viant.com). | Yes |
maxBudget | Number | Total lifetime budget for the campaign in USD. | Yes |
dailyBudget | Number | Maximum daily spend in USD. | No |
dailyFrequencyCap | Number | The maximum number of impressions a user is exposed to per frequency cap time period duration. Note: The name of this field is misleading since it is not necessarily "daily". The name of this field remains unchanged for backwards compatibility and will be updated on the next major version. See frequencyCapDuration and frequencyCapTimePeriod. | Yes (if frequencyCapDuration or frequencyCapTimePeriod present) |
frequencyCapDuration | Number | The number of given frequencyCapTimePeriod. | Yes (if dailyFrequencyCap or frequencyCapTimePeriod present) |
frequencyCapTimePeriod | String | "MINUTE", "HOUR", "DAY" | Yes (if dailyFrequencyCap or frequencyCapDuration present) |
startDate | Number | Start date (Unix time in milliseconds). | Yes |
endDate | Number | End date (Unix time in milliseconds). | Yes |
iabCategory | String Array | An array of IAB category codes (e.g. "IAB8-6"). See reference table here | Yes |
markupRate | Number | Markup as a decimal (e.g. 0.10 for 10%). | No |
lifetimeImpressionCap | Number | Lifetime impression cap. | No |
dailyImpressionCap | Number | Daily impression cap. | No |
lifetimeClickCap | Number | Lifetime click cap. | No |
dailyClickCap | Number | Daily click cap. | No |
ioNumber | String | IO Number. Used as client ID; mutually exclusive with externalCampaignId. | No |
externalCampaignId | String | Client campaign ID; mutually exclusive with ioNumber. | No |
minBidMultiplier | Number | Minimum bid multiplier. | No |
maxBidMultiplier | Number | Maximum bid multiplier. | No |
flights | Object Array | Array of campaign flights. | Yes for campaign flights, No for order flights |
autoAdvertising | Boolean | Whether Viant AI is enabled for this campaign. | No |
pacingMode | String | One of: ASAP, SPEND_EVENLY | No |
intradayFrontloadPct | Number | Increase hourly budget to frontload spend. | No |
objective | String | One of: AWARENESS, ENGAGEMENT, CONVERSION | No |
Response
| JSON Fields | Type | Description |
|---|---|---|
| messages | Object Array | An array of any error messages. |
| messages[].level | String | Error level. |
| messages[].code | String | Error code. |
| messages[].message | String | Error message. |
| entity | Object Array | An array of campaign objects. |
| entity[].id | Number | Campaign ID. |
| entity[].advertiserId | Number | Advertiser ID associated with the campaign. |
| entity[].name | String | Campaign name. |
| entity[].domain | String | The advertiser domain for the campaign (e.g. viant.com). |
| entity[].maxBudget | Number | Total lifetime budget for the campaign in USD. |
| entity[].dailyBudget | Number | Maximum daily spend in USD. |
| entity[].dailyFrequencyCap Note: The name of this field is misleading since it is not necessarily "daily". The name of this field remains unchanged for backwards compatibility and will be updated on the next major version. |
Number | The maximum number of impressions a user is exposed to per frequency cap time period duration. See frequencyCapDuration and frequencyCapTimePeriod. |
| entity[].frequencyCapDuration | Number | The number of given frequencyCapTimePeriod. |
| entity[].frequencyCapTimePeriod | String | "MINUTE", "HOUR", or "DAY" |
| entity[].startDate | Number | Start date as Unix time in milliseconds. |
| entity[].endDate | Number | End date as Unix time in milliseconds. |
| entity[].iabCategory | String Array | IAB category codes associated with the campaign (e.g., "IAB8-6"). |
| entity[].markupRate | Number | Percentage markup (e.g., 0.10 for 10%). |
| entity[].lifetimeImpressionCap | Number | Lifetime impression cap. |
| entity[].dailyImpressionCap | Number | Daily impression cap. |
| entity[].lifetimeClickCap | Number | Lifetime click cap. |
| entity[].dailyClickCap | Number | Daily click cap. |
| entity[].ioNumber | String | IO Number. |
| entity[].externalCampaignId | String | External (Client) campaign ID. |
| entity[].channelGroup | String | Deprecated. Generally displays as "MOBILE_COMPUTER_CTV". |
| entity[].minBidMultiplier | Number | Minimum bid multiplier. |
| entity[].maxBidMultiplier | Number | Maximum bid multiplier. |
| entity[].hasFlights | Boolean | True if this campaign has campaign flights (read-only). |
| entity[].flights | Object Array | Array of Campaign Flights. |
| entity[].autoAdvertising | Boolean | Flag indicating if Viant AI is enabled for this campaign. |
| entity[].pacingMode | String | One of:
|
| entity[].intradayFrontloadPct | Number | Increases hourly budget to spend more at the beginning of the day. |
| entity[].objective | String | One of:
|
Examples
Request to create a new campaign
curl -u <user>:<password> -X POST -H "Content-Type: application/json" -d '{"id":null, "advertiserId":456, "name":"Retargeting Campaign", "domain":"bigbox.com", "maxBudget":100000, "dailyBudget":1000, "dailyFrequencyCap":5, "frequencyCapDuration":24, "frequencyCapTimePeriod":"HOUR", "startDate":1464739200000, "endDate":1483228800000, "agencyCommissionRate":0.10, "iabCategory":["IAB22", "IAB18"], "lifetimeImpressionCap": 100000,"dailyImpressionCap": 100,"lifetimeClickCap": 15000,"dailyClickCap": 10,"ioNumber": "12345"}' https://sandbox-api.viant.com/v1/campaign/save
Since the ID field is null, this creates a new campaign.
Response
{
"messages": [],
"entity": {
"id": 92,
"advertiserId": 456,
"name": "Retargeting Campaign",
"domain": "bigbox.com",
"maxBudget": 100000,
"dailyBudget": 1000,
"dailyFrequencyCap": 5,
"frequencyCapDuration": 24,
"frequencyCapTimePeriod": "HOUR",
"startDate": 1464739200000,
"endDate": 1483228800000,
"markupRate": 0.10,
"iabCategory": [
"IAB22",
"IAB18"
],
"lifetimeImpressionCap": 100000,
"dailyImpressionCap": 100,
"lifetimeClickCap": 15000,
"dailyClickCap": 10,
"ioNumber": "12345",
"externalCampaignId": "12345",
"channelGroup": "MOBILE_COMPUTER_CTV",
"minBidMultiplier": null,
"maxBidMultiplier": null,
"autoAdvertising": false,
"pacingMode": "SPEND_EVENLY",
"intradayFrontloadPct": 0.0,
"hasFlights": false,
"flights": []
}
}Request to edit an existing campaign
curl -u <user>:<password> -X POST -H "Content-Type: application/json" -d '{"id":null, "advertiserId":456, "name":"Retargeting Campaign", "domain":"bigbox.com", "maxBudget":100000, "dailyBudget":2000, "dailyFrequencyCap":5, "frequencyCapDuration":3, "frequencyCapTimePeriod":"DAY", "startDate":1464739200000, "endDate":1483228800000, "agencyCommissionRate":0.10, "iabCategory":["IAB22", "IAB18"],"lifetimeImpressionCap": 100000,"dailyImpressionCap": 100, "lifetimeClickCap": 15000, "dailyClickCap": 10,"ioNumber": "12345"}' https://sandbox-api.viant.com/v1/campaign/save
In this example we updated the daily max budget of the previously created campaign.
Response
{
"messages": [],
"entity": {
"id": 92,
"advertiserId": 456,
"name": "Retargeting Campaign",
"domain": "bigbox.com",
"maxBudget": 100000,
"dailyBudget": 2000,
"dailyFrequencyCap": 5,
"frequencyCapDuration": 3,
"frequencyCapTimePeriod": "DAY",
"startDate": 1464739200000,
"endDate": 1483228800000,
"markupRate": 0.10,
"iabCategory": [
"IAB22",
"IAB18"
],
"lifetimeImpressionCap": 100000,
"dailyImpressionCap": 100,
"lifetimeClickCap": 15000,
"dailyClickCap": 10,
"ioNumber": "12345",
"externalCampaignId": "12345",
"channelGroup": "MOBILE_COMPUTER_CTV",
"minBidMultiplier": null,
"maxBidMultiplier": null,
"autoAdvertising": false,
"pacingMode": "SPEND_EVENLY",
"intradayFrontloadPct": 0.0,
"hasFlights": false,
"flights": []
}
}Request to create a new campaign with campaign flights
curl -u <user>:<password> -X POST -H "Content-Type: application/json" -d '{"id": null,"advertiserId": 55812,"name": "New Campaign with Campaign Flights","domain": "viant.com","iabCategory": ["IAB1-1"],"channelGroup": "MOBILE_COMPUTER_CTV","flights": [{"id": null,"status": null,"budgetType": "AUTO_BUDGET","dailyBudget": null,"dailyFrontload": 0.0,"maxBudget": 90.0,"remainingBudget": null,"dailyImpCap": null,"lifetimeImpCap": null,"startDate": 1631836800000,"endDate": 1633046340000}]}' https://sandbox-api.viant.com/v1/campaign/save
Response
{
"messages": [],
"entity": {
"id": 303435,
"advertiserId": 55812,
"name": "New Campaign with Campaign Flights",
"domain": "viant.com",
"maxBudget": 90.0,
"dailyBudget": null,
"dailyFrequencyCap": null,
"frequencyCapDuration": null,
"frequencyCapTimePeriod": null,
"startDate": 1631836800000,
"endDate": 1633046340000,
"iabCategory": [
"IAB1-1"
],
"markupRate": null,
"lifetimeImpressionCap": null,
"dailyImpressionCap": null,
"lifetimeClickCap": null,
"dailyClickCap": null,
"ioNumber": null,
"externalCampaignId": null,
"channelGroup": "MOBILE_COMPUTER_CTV",
"minBidMultiplier": null,
"maxBidMultiplier": null,
"autoAdvertising": false,
"pacingMode": "SPEND_EVENLY",
"intradayFrontloadPct": 0.0,
"hasFlights": true,
"flights": [
{
"id": 1,
"status": "ACTIVE",
"budgetType": "AUTO_BUDGET",
"dailyBudget": null,
"dailyFrontload": 0.0,
"maxBudget": 90.0,
"remainingBudget": null,
"dailyImpCap": null,
"lifetimeImpCap": null,
"startDate": 1631836800000,
"endDate": 1633046340000
}
]
}
}