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: ASAP SPEND_EVENLY
entity[].intradayFrontloadPct	Number	Increases hourly budget to spend more at the beginning of the day.
entity[].objective	String	One of: AWARENESS ENGAGEMENT CONVERSION

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
      }
    ]
  }
}