Structured Data - v4.1 - Insertion Order

See the overview for an explanation of format.

Field

Required

Type

Writable

Description

Io Id

Required only when editing existing insertion orders

integer

Numeric ID value of the insertion order. If left blank, a new Insertion Order ID will be created and a unique ID will be assigned. Optionally, when creating a new Insertion Order, you can use a custom identifier for the purpose of assigning Line Items to the new Insertion Order. The format for a custom identifier is "ext[custom identifier]", for example, ext123. When the file is uploaded and processed, all custom identifiers will be replaced with DBM-assigned IDs and the objects will be associated (for example, Line Item to Insertion Order) based on the custom identifiers.

Campaign Id

integer

Numeric ID value of the campaign. You can specify a custom identifier (for example, "ext[custom campaign identifier]") for a campaign that you are creating at the same time as this insertion order.

Name

Yes

string

Yes

The name of the entry.

Timestamp

Required when editing existing entries

integer

The timestamp for the entry, this is used by the system to verify that the entry has not changed between downloading and uploading.

Status

Yes

string

Yes

The status setting for the entry.

Active
Paused
Draft
Archived
Deleted

Io Type

Yes

string

Yes

The type of the insertion order. Only settable on creation.

standard

Fees

string, list of lists

Yes

All fees for this entry. List format = (Fee category; Fee amount; Fee type; Invoiced;).

Fee category
- CPM
- Media
Fee amount
- Float
- Pct as float
Fee type
- (string, see table in fees)
Invoiced
- True
- False
- blank

Example '(CPM; 2; Bid Manager Fee; False) ; (Media; 13; Default; True);'
Acceptable values are provided in the following table:

Note: Premium Fees CPM Fee is reserved by the system and is immutable. The cardinality of the Premium Fee is preserved across mutations by inserting Default CPM fees if needed.

Fee category	Fee Type	Invoiced option
CPM/Media	Default	Not permitted (leave blank)
CPM/Media	Third-Party Ad Server	Not permitted (leave blank)
CPM/Media	DoubleVerify	Permitted (True/False)
CPM/Media	Adsafe	Not permitted (leave blank)
CPM/Media	Adxpose	Not permitted (leave blank)
CPM/Media	Vizu	Not permitted (leave blank)
CPM/Media	Aggregate Knowledge	Not permitted (leave blank)
CPM/Media	Teracent	Not permitted (leave blank)
CPM/Media	Evidon	Not permitted (leave blank)
CPM/Media	Agency Trading Desk Fee	Not permitted (leave blank)
CPM/Media	Adloox	Permitted (True/False)
CPM	ShopLocal	Required (True)
CPM	TrustMetrics	Not permitted (leave blank)
CPM	Integral Ad Science Video	Permitted (True/False)
CPM	MOAT Video	Not permitted (leave blank)
Media	Bid Manager Fee	Required (True)
Media	Media Cost Data	Not permitted (leave blank)
CPM	Premium Fees	Not permitted (leave blank)

Integration Code

string

Yes

An optional code for tracking purposes.

Details

string

Yes

Entry details in string format.

Pacing

Yes

string

Yes

The time period used to spend to the pacing amount.

Daily
Monthly
Flight

Pacing Rate

Yes

string

Yes

The rate of pacing for this entry.

ASAP
Even
Ahead

Pacing Amount

Yes

float

Yes

The amount to spend per the time period set by the pacing type.

Frequency Enabled

Yes

string

Yes

Enables/disables impression-based frequency capping on the insertion order.

TRUE
FALSE

Frequency Exposures

Required when "Frequency Enabled" is "TRUE"

integer

Yes

A positive integer amount for the number of impressions in a given Frequency Amount, that is, the x in 'Show x impressions over y period'.

Frequency Period

Required when "Frequency Enabled" is "TRUE"

string

Yes

Specifies the time period unit for the frequency cap.

Minutes
Hours
Days
Weeks
Months
Lifetime

Frequency Amount

Required when "Frequency Enabled" is "TRUE"

integer

Yes

A positive integer amount for length of time of the Frequency Period type, that is, the y in 'Show x impressions over y period'.

Performance Goal Type

Yes

string

Yes

The goal unit for the insertion order

CPM
CPA
CPC
CPV
CPIAVC
CTR
% Viewability
None
Other

Performance Goal Value

Yes

string

Yes

The goal value in currency (CPM, CPA, CPC, CPV, CPIAVC), percentage (% Viewability, CTR) or as a string (Other).

Measure DAR

Yes

string

Yes

Enables/disables audience measurement using Nielsen Digital Ad Ratings

TRUE
FALSE

Measure DAR Channel

Required when "Measure DAR" is "TRUE"

integer

Yes

The channel to measure with Nielsen Digital Ad Ratings. Format = UniversalChannel.id

Budget Type

Yes

string

Yes

Specifies the type of budget in terms of an amount of "revenue" to spend (amount) or a number of impressions (impressions) to purchase.

Amount
Impressions

Budget Segments

Yes

string, list of lists

Yes

Specifies the specific budget segments. List format = (Budget, Start Date, End Date). Budget is in currency floating format. Dates are in MM/DD/YYYY format. Example: "(100.50;01/01/2016;03/31/2016;);(200.00;04/01/2016;06/30/2016;);"

Auto Budget Allocation

Yes

string

Yes

Enables/disables auto-budget allocation

TRUE
FALSE

Geography Targeting - Include

string, list

Yes

List of geographies to include in targeting. List format = (GeoLocation.id; GeoLocation.id;etc.).

Geography Targeting - Exclude

string, list

Yes

List of geographies to exclude in targeting. List format = (GeoLocation.id;GeoLocation.id; etc.).

Language Targeting - Include

string, list

Yes

List of languages to include in targeting. List format = (Language.id;Language.id;etc.).

Language Targeting - Exclude

string, list

Yes

List of languages to exclude in targeting. List format = (Language.id;Language.id;etc.).

Device Targeting - Include

string, list

Yes

List of devices to include in targeting. List format = (DeviceCriteria.id;DeviceCriteria.id;etc.).

Device Targeting - Exclude

string, list

Yes

List of devices to exclude in targeting. List format = (DeviceCriteria.id;DeviceCriteria.id;etc.).

Browser Targeting - Include

string, list

Yes

List of browser to include in targeting. List format = (Browser.id;Browser.id;etc.).

Browser Targeting - Exclude

string, list

Yes

List of browser to exclude in targeting. List format = (Browser.id;Browser.id;etc.).

Brand Safety Labels

string, list

Yes

List of the digital content labels to target. List format = (G;PG; etc.).

Brand Safety Sensitivity Setting

string

Yes

Choose the sensitivity setting to block inventory based on the subject matter of its surrounding content.

Do not block
Use DoubleClick Verification
Use custom

Brand Safety Custom Settings

Required when "Brand Safety Custom Setting" is "Use Custom"

string, list

Yes

If the Brand Safety Sensitivity Setting is 'Use custom', specify the list of standard content classifiers. For example, (Adult;Alcohol;Tobacco;etc.).

Adult
Derogatory
Downloads & Sharing
Weapons
Gambling
Violence
Suggestive
Profanity
Alcohol
Drugs
Tobacco
Politics
Religion
Tragedy
Transportation Accidents
Sensitive social issues
Shocking

Third Party Verification Services

string

Yes

Third party verification services provider.

None
Integral Ad Science
DoubleVerify
Adloox

Third Party Verification Labels

string, list

Yes

If Third Party Verification Services is not "None", specify a list of labels supported by the selected provider.

Channel Targeting - Include

string, list

Yes

List of channels to include in targeting. List format = (UniversalChannel.id;UniversalChannel.id; etc.).

Channel Targeting - Exclude

string, list

Yes

List of channels to include in targeting. List format = (UniversalChannel.id;UniversalChannel.id; etc.).

Site Targeting - Include

string, list

Yes

List of sites to include in targeting. The list can include a set of site IDs or strings of URLs, if not found in the Universal Site table. List format = (UniversalSite.Id;'http://someurl.com';etc.).

Site Targeting - Exclude

string, list

Yes

List of sites to exclude in targeting. The list can include a set of site IDs or strings of URLs, if not found in the Universal Site table. List format = (UniversalSite.Id;'http://someurl.com';etc.).

App Targeting - Include

string, list

Yes

List of apps to include in targeting. The list can include a set of UniversalSite IDs or strings of app packages, if not found in the Universal Site table. List format = (UniversalSite.Id; 'some.app.package';etc.).

App Targeting - Exclude

string, list

Yes

List of apps to exclude in targeting. The list can include a set of UniversalSite IDs or strings of app packages, if not found in the Universal Site table. List format = (UniversalSite.Id; 'some.app.package';etc.).

App Collection Targeting - Include

string, list

Yes

List of app collections to include in targeting. List format= App Collection ID; App Collection ID;

App Collection Targeting - Exclude

string, list

Yes

List of app collections to exclude in targeting. List format= App Collection ID; App Collection ID;

Category Targeting - Include

string, list

Yes

List of categories to include in targeting, from AdX vertical IDs. List format = (Verticals.Id;Verticals.Id;etc.).

Category Targeting - Exclude

string, list

Yes

List of categories to exclude in targeting, from AdX vertical IDs. List format = (Verticals.Id;Verticals.Id;etc.).

Keyword Targeting - Include

string, list

Yes

List of keyword strings to include in targeting.

Keyword Targeting - Exclude

string, list

Yes

List of keyword strings to exclude in targeting.

Keyword List Targeting - Exclude

string, list

Yes

List of negative keyword lists to exclude in targeting. List format= Negative Keyword List ID; Negative Keyword List ID;

Audience Targeting - Similar Audiences

Required when "Type" is "Display" or "Video" or "Audio"

string

Yes

Enable similar audiences for positively targeted first-party lists.

TRUE
FALSE

Audience Targeting - Include

string, list of list of pairs

Yes

List of audience lists to include in targeting. For first-party audience lists, each audience is listed as a pair of UserList ID and recency setting. A pair is (1;1d;), where 1d is a sample recency representing 1 day recency. Recency is not available for third-party audiences, so the list format is (3;);(4;);. To "AND" and "OR" groups of audiences, follow this example: To combine pairs with and without recency: ' ((1;1d;);(2;365d;));((3;);(4;5m;);(5;all;));'. This means (list 1 with 1 day recency OR list 2 with 365day recency ) AND (list 3 without a specified recency OR list 4 with 5 minute recency OR list 5 with all users).
Valid recency values are:
all, 1m, 5m, 10m, 15m, 30m, 1h, 2h, 3h, 6h, 12h, 1d, 2d, 3d, 5d, 7d, 10d, 14d, 15d, 21d, 28d, 30d, 45d, 60d, 90d, 120d, 180d, 270d, 365d

Audience Targeting - Exclude

string, list of list of pairs

Yes

List of audience lists to exclude in targeting. Each audience is listed as a pair of UserList ID and recency setting, if the audience list is a 1P audience list. A pair is (1;1d;), where 1d is a sample recency representing 1 day recency. However, for 3P audiences, recency is not available, so the list format is (3;);(4;);. List format= (UserList.id; recency optional;); (UserList.id; recency optional;);
Example: "(1;1d;);(2;);".
Valid recency values are:
all, 1m, 5m, 10m, 15m, 30m, 1h, 2h, 3h, 6h, 12h, 1d, 2d, 3d, 5d, 7d, 10d, 14d, 15d, 21d, 28d, 30d, 45d, 60d, 90d, 120d, 180d, 270d, 365d

Affinity & In Market Targeting - Include

string, list

Yes

List of affinity and/or in-market audience lists to include. List format= UserList ID; UserList ID;

Affinity & In Market Targeting - Exclude

string, list

Yes

List of affinity and/or in-market audience lists to exclude. List format= UserList ID; UserList ID;

Custom List Targeting

string, list

Yes

List of custom lists to target. List format= UserList ID; UserList ID;

Inventory Source Targeting - Authorized Seller Only

Required when "Type" is "Display" or "Video" or "Audio"

string

Yes

Setting to target authorized seller only, authorized seller and resellers, or authorized seller + unknown. "Authorized Direct" means only authorized sellers will be targeted. TRUE means targeting the authorized sellers and resellers. FALSE means it will target authorized sellers, resellers, and unknown sellers.

TRUE
FALSE
Authorized Direct

Inventory Source Targeting - Include

string, list

Yes

List of inventory to include in targeting. List format = (InventorySource.id; InventorySource.id;).

Inventory Source Targeting - Exclude

string, list

Yes

List of inventory to exclude in targeting. List format = (InventorySource.id; InventorySource.id;).

Inventory Source Targeting - Target New Exchanges

string

Yes

Setting to target new exchanges.

True
False

Daypart Targeting

string, list

Yes

List of IDs, where each daypart ID is constructed in the following format:
daypart_id = base_dayparting_id
+ days_since_monday * 10000
+ start * 100
+ end

base_dayparting_id = 300000
days_since_monday: 0=Monday, 1=Tuesday, ..., 6=Sunday
start: 0..95 (00:00--23:45) an integer from 0-95, representing 15min slots
end: 1..96 (00:15--24:00); an integer from 0-95, representing 15min slots
start < end
For new entities, times will be set in the timezone of your users (i.e., "Local"). For existing entities, the timezone will not be changed.

Daypart Targeting Time Zone

Required when "Daypart Targeting" is included.

string

Yes

Timezone to use for daypart targeting.

Local
Advertiser

Environment Targeting

Required when "Type" is "Display" or "Video" or "Audio"

string, list

Yes

List of environments to target. List format = (Desktop Web; Mobile App; etc.).
For Display Environment:

Desktop Web
Mobile Web
Mobile App
Mobile App Interstitial
Desktop Web on Mobile

For Video:

Desktop Web Video
Desktop Web Game
Desktop Web In-Read
Desktop Web In-Feed
Mobile Web Video
Mobile App Video
Mobile App Video Interstitial

For Audio:

Desktop Web Audio
Mobile Web Audio
Mobile App Audio

Viewability Targeting Active View

string

Yes

Target predicted viewability percentages. Percentages are represented as floats. One of {0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.9}

Viewability Targeting Ad Position - Include

string

Yes

Target ad positions. Select one or none of the acceptable values:

All
ATF
BTF
Unknown

Viewability Targeting Ad Position - Exclude

string

Yes

Exclude ad positions in targeting. Select one or none of the acceptable values:

ATF
BTF
Unknown

Video Ad Position Targeting

string, list

Yes

List of video ad positions to target. Select one or more of the acceptable values:

unknown
Pre-roll
Mid-roll
Post-roll

Video Player Size Targeting

string, list

Yes

List of video ad player size to target. Select one or more of the acceptable values:

unknown
small
large
HD

Demographic Targeting Gender

string, list

Yes

List of genders to target. Select one or more of the acceptable values:

Female
Male
Unknown

Demographic Targeting Age

string, list

Yes

Target to a user age range. Specify a from/to range by selecting a single From age and a single To age and whether to include unknown ages true/false. See the list of acceptable From/To ages.
Example 1: to target 18-55 and include unknown ages, specify the format {From; To ; Include unknown True/False} = 18;55;true;
Example 2: to target only users >35 years old and exclude unknown ages, specify the following = 35;+;false;.
Acceptable values for From:

Acceptable values for To:

Demographic Targeting Household Income

string, list

Yes

Target a household income range. Specify a from/to range by selecting a single Top_of_Range income range and a single Bottom_of_Range income range and whether to include households with unknown income true/false. See the list of acceptable Top_of_Range/Bottom_of_Range ranges.
Example 1: to target the top 10% to 50% of households and include households with unknown income, specify the format {Top_of_Range; Bottom_of_Range; Include unknown True/False} = Top 10%;41-50%;true;
Example 2: to target only the lower 50% of households and exclude households with unknown income, specify the format {Top_of_Range; Bottom_of_Range; Include unknown True/False} = Lower 50%;Lower 50%;true;
Acceptable values for Top_of_Range/Bottom_of_Range:

Top 10%
11-20%
21-30%
31-40%
41-50%
Lower 50%

Demographic Targeting Parental Status

Yes

string, list

Yes

List of parental status to target. Select one or more of the acceptable values.

Parent
Not a parent
Unknown

Connection Speed Targeting

string

Yes

Target to a specific connection speed. Select one of the acceptable values:

Carrier Targeting - Include

string, list

Yes

List of ISPs or Carriers to target. List format = {ISP.id; ISP.id;}

Carrier Targeting - Exclude

string, list

Yes

List of ISPs or Carriers to exclude. List format = {ISP.id; ISP.id;}