Create or modify an Ad Order - DEPRECATED

post

https://sandbox-api.viantinc.com/{basePath}/adorder/save

Creates or modifies an Ad Order.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Note

io_number and externalAdOrderId 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.

Submitting a record with both fields is an error condition, and will result in a 400 response.

Request

POST /adorder/save

Request Body

Name	Type	Description	Required
id	Number	Ad order ID.	Required for update.
name	String	Ad order name.	Yes
campaignId	Number	Campaign ID associated with the ad order.	Yes
optimizationGoal	String	Optimization goal for the ad order: CPM CPC CPA	Yes
startDate	Number	Start date of the ad order, passed as Unix time in milliseconds.	Yes for creation. After creation the flight endpoint must be used to update and modify.
endDate	Number	End date of the ad order, passed as Unix time in milliseconds.	Yes for creation. After creation the flight endpoint must be used to update and modify.
lifetimeBudget	Number	The total lifetime budget for the ad order in USD.	Yes for creation. After creation the flight endpoint must be used to update and modify.
frequencyCap	Object	Holds all frequency cap settings. If not present, defaults to null.	No
frequencyCap.limit	Number	The maximum number of impressions a user is exposed to per frequency cap time period duration. See frequencyCap.duration and frequencyCap.timePeriod.	Yes (if parent object present)
frequencyCap.duration	Number	The number of given frequencyCap.timePeriod	Yes (if parent object present)
frequencyCap.timePeriod	String	MINUTE HOUR DAY	Yes (if parent object present)
channelsV2	String Array / Null	Channels the Ad Order will be capable of serving on: Display Video Native Audio DOOH CTV LTV LTV Wide Orbit	No
max_bid	Number	The maximum bid. Default values apply when no values are present.	No
audienceWeightsEnabled	Boolean	Controls whether audience weights are enabled. If null or the field is absent, will be set to default false on create, and left untouched on update.	No
goalMode	String	Sets goal prioritization. Can be set to: PERFORMANCE SPEND Defaults to "PERFORMANCE" if not provided.	No
hourlyPacingMode	String	ASAP SPEND_EVENLY	No
hourlyFrontload	Number	Percentage frontload between 0.00 and 100.00. Null if hourlyPacingMode is ASAP	Required if hourlyPacingMode is "SPEND_EVENLY"
ioNumber	String	Client ID for Ad Order ioNumber and externalAdOrderId serve the same purpose. A request to create an Ad Order may include one or the other of these fields, but not both.	No
externalAdOrderId	String	Client ID for Ad Order ioNumber and externalAdOrderId serve the same purpose. A request to create an Ad Order may include one or the other of these fields, but not both.	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	An ad order object.
entity.id	Number	Ad order ID.
entity.name	String	Ad order name.
entity.campaignId	Number	Campaign ID associated with the ad order.
entity.startDate	Number	Start date of the ad order, passed as Unix time in milliseconds.
entity.endDate	Number	End date of the ad order, passed as Unix time in milliseconds.
entity.optimizationGoal	String	Optimization goal for the ad order -- CPM CPC CPA
entity.lifetimeBudget	Number	The total lifetime budget for the ad order in USD.
entity.frequencyCap	Object	A frequency cap settings object.
entity.frequencyCap.limit	Number	The maximum number of impressions a user is exposed to per frequency cap time period duration. See frequencyCap.duration and frequencyCap.timePeriod.
entity.frequencyCap.duration	Number	The number of given frequencyCap.timePeriod.
entity.frequencyCap.timePeriod	String	MINUTE HOUR DAY
entity[].channelsV2	String Array / Null	Channels the Ad Order will be capable of serving on: Display Video Native Audio DOOH CTV LTV LTV Wide Orbit
entity.audienceWeightsEnabled	Boolean	Controls whether audience weights are enabled.
entity.audiences	Object Array	An array of audience objects targeted by the ad order.
entity.audiences[].id	Number	Audience ID.
entity.audiences[].name	String	Audience name.
entity.audiences[].weight	Integer	Audience weight.
entity.audiences[].pmpDeals	Number Array	An array of any targeted PMP deals IDs, where the IDs are the internal Viant IDs.
entity.audiences[].exchanges	Object	If this object is not present, the audience will not modify exchange targeting criteria.
entity.audiences[].exchanges.include	Number Array	An array of any targeted exchange IDs.
entity.audiences[].exchanges.exclude	Number Array	An array of any excluded exchange IDs.
entity.audiences[].siteLists	Object	If this object is not present, the audience will not modify site list targeting criteria.
entity.audiences[].siteLists.include	Number Array	An array of any targeted site list IDs.
entity.audiences[].siteLists.exclude	Number Array	An array of any excluded site list IDs.
entity.goalMode	String	Sets goal prioritization. Can be set to: PERFORMANCE SPEND
entity.hourlyPacingMode	String	ASAP SPEND_EVENLY
entity.hourlyFrontload	Number	Percentage frontload between 0.00 and 100.00. Null if hourlyPacingMode is ASAP

Example

Request to create an ad order

curl -u <user>:<password> -X POST -H "Content-Type: application/json" -d '{"name" : "Android","campaignId":91,"optimizationGoal":"CPM","startDate" : 1462060800000,"endDate" : 1464652800000,"lifetimeBudget":1000, "audiences":null, "externalAdOrderId": "abc12345"}' https://sandbox-api.viant.com/v1/adorder/save

Since the ID field is null, this creates a new ad order.

Response

{
  "messages": [],
  "entity": {
    "id": 9993,
    "name": "Android",
    "campaignId": 91,
    "startDate": 1462060800000,
    "endDate": 1464652800000,
    "optimizationGoal": "CPC",
    "lifetimeBudget": 1000,
    "frequencyCap": {
      "limit": null,
      "duration": null,
      "timePeriod": null
    },
    "channelsV2": null,
    "audiences": [
      {
        "id": 9802,
        "name": "Default Audience",
        "weight": 1,
        "pmpDeals": null
        "siteLists": {
          "include": [
            100,
            101
          ],
          "exclude": null
        },
        "exchanges": {
          "include": null,
          "exclude": [96]
        }
      }
    ],
    "audienceWeightsEnabled": false,
    "goalMode": "PERFORMANCE",
    "hourlyPacingMode": "ASAP",
    "hourlyFrontload": null,
    "io_number": "abc12345",
    "externalAdOrderId": "abc12345"
  }
}

Note that a default audience for targeting is created.

Request to edit an existing ad order

curl -u <user>:<password> -X POST -H "Content-Type: application/json" -d '{"id":9993, "name": "Android", "campaignId":91, "optimizationGoal":"CPM", "startDate" : 1462060800000, "endDate" : 1464652800000, "lifetimeBudget":1000, "frequencyCap":{"limit":5, "duration":3, "timePeriod":"DAY"}, "audiences":[{"id":9802, "name":"Default Audience", "weight" : 1, "pmpDeals":[6565]}], "audienceWeightsEnabled": false}' https://sandbox-api.viant.com/v1/adorder/save

Response

{
  "messages": [],
  "entity": {
    "id": 9993,
    "name": "Android",
    "campaignId": 91,
    "startDate": 1462060800000,
    "endDate": 1464652800000,
    "optimizationGoal": "CPC",
    "lifetimeBudget": 1000,
    "frequencyCap": {
      "limit": 5,
      "duration": 3,
      "timePeriod": "DAY"
    },
    "channelsV2": null,
    "audiences": [
      {
        "id": 9802,
        "name": "Default Audience",
        "weight": 1,
        "pmpDeals": [
          6565
        ],
        "siteLists": {
          "include": [
            100,
            101
          ],
          "exclude": null
        },
        "exchanges": {
          "include": null,
          "exclude": [96]
        }
      }
    ],
    "audienceWeightsEnabled": false,
    "hourlyPacingMode": "ASAP",
    "hourlyFrontload": null,
    "io_number": null,
    "externalAdOrderId": null
  }
}

Request to create an ad order with channelsV2 account

curl -u <user>:<password> -X POST -H "Content-Type: application/json" -d '{"name" : "Android","campaignId":91,"optimizationGoal":"CPM","startDate" : 1462060800000,"endDate" : 1464652800000,"lifetimeBudget":1000,"channelsV2":["Display", "DOOH"], "audiences":null}' https://sandbox-api.viant.com/v1/adorder/save

Since the ID field is null, this creates a new ad order.

Response

{
  "messages": [],
  "entity": {
    "id": 9993,
    "name": "Android",
    "campaignId": 91,
    "startDate": 1462060800000,
    "endDate": 1464652800000,
    "optimizationGoal": "CPC",
    "lifetimeBudget": 1000,
    "frequencyCap": {
      "limit": null,
      "duration": null,
      "timePeriod": null
    },
    "channelsV2": [
      "Display",
      "DOOH"
    ],
    "audiences": [
      {
        "id": 9802,
        "name": "Default Audience",
        "weight": 1,
        "pmpDeals": null
        "siteLists": {
          "include": [
            100,
            101
          ],
          "exclude": null
        },
        "exchanges": {
          "include": null,
          "exclude": [96]
        }
      }
    ],
    "audienceWeightsEnabled": false,
    "goalMode": "PERFORMANCE",
    "hourlyPacingMode": "ASAP",
    "hourlyFrontload": null,
    "io_number": null,
    "externalAdOrderId": null
  }
}

Body Params

name

string

required

campaignId

int32

required

Campaign ID associated with the ad order. The campaign's budget type determines which budget fields are required.

optimizationGoal

string

enum

required

Optimization goal for the ad order.
VCR is accepted as a case-insensitive alias for VIDEO_COMPLETION_RATE on input
and is normalized to VIDEO_COMPLETION_RATE in the response.

Allowed:

startDate

number

required

endDate

number

required

lifetimeBudget

number

The total lifetime budget for the ad order in USD.
Required if the campaign's budget type is MONETARY.
Optional (will be ignored) if the campaign's budget type is IMPRESSIONS.

dailyBudget

number

The daily budget limit in USD.
Optional. Only applicable when the campaign's budget type is MONETARY.

lifetimeImpressions

number

The total lifetime impressions budget for the ad order.
Required if the campaign's budget type is IMPRESSIONS.
Not applicable if the campaign's budget type is MONETARY.

dailyImpressions

number

The daily impressions budget limit.
Optional. Only applicable when the campaign's budget type is IMPRESSIONS.

frequencyCap

object

max_bid

number

audienceWeightsEnabled

boolean

costOptimizationEnabled

boolean

goalMode

string

enum

Allowed:

cpa_goal

number

CPA goal value. Required when optimizationGoal=CPA.

ctr_goal

double

CTR goal (e.g. 0.002). Required when optimizationGoal=CPC.

completion_rate_goal

double

Video completion rate goal (0.0–1.0).
Required when optimizationGoal=VIDEO_COMPLETION_RATE on create.
On update, if omitted, the existing stored value is preserved.

minBidMultiplier

number | null

Minimum bid multiplier for bid matrix entries.
On update, if omitted, the existing stored value is preserved.

maxBidMultiplier

number | null

Maximum bid multiplier for bid matrix entries.
On update, if omitted, the existing stored value is preserved.

channels

array of strings

channels

dayPartType

string

dayParts

array of objects

dayParts

audiences

array of objects

audiences

externalAdOrderId

string

hourlyPacingMode

string

enum

Allowed:

hourlyFrontload

number

Responses

401

Unauthorized

403

Forbidden

404

Not Found

Note

Request

Request Body

Response

Example

Request to create an ad order

Response

Request to edit an existing ad order

Response

Request to create an ad order with channelsV2 account

Response

200OK

400Bad Request