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