Skip to end of metadata
Go to start of metadata

Placement Service

The Placement Service enables you to create placement ad tags as well as modify and view them. You will use placements for managed publishers or for direct media buys.

  • Placement IDs and their associated information are stored server-side with Xandr and are easy to modify.
  • When you create a placement, you specify the types of creatives that are allowed to serve on it (see supported_media_types and supported_media_subtypes below).

Targeting of advertisers, line items, or campaigns via this service will override any targeting defined by the Payment Rule Service.

On This Page

Tag Format

Once you have the placement ID, you format the placement tag as follows and hand it to the publisher you represent or with whom you have a guaranteed buy. Note that "id" is the placement ID.

You can include placeholders to pass in additional query string parameters to our platform during the ad call. For more details, see Placement Tag Parameters (Customer login required).

When serving your placement tags on secure inventory (SSL), you should alter the below tags to use the host: "https://secure.adnxs.com/..."

IFRAME
JavaScript

REST API

Note that code, placement_code, site_code, and publisher_code can be used in place of the corresponding IDs in the calls below.

Add a placement (NETWORK)

Modify an existing placement (NETWORK)

Delete an existing placement

View all of the placements for one of your publishers:

View a specific placement for one of your publishers:

View all placements for a site:

 

JSON Fields

Field

Type (Length)

Description

Default

Required On

id

int

The ID of the placement.

Auto-incremented number (i.e. 123)

PUT, in query string

name

string (100)

The name of the placement.

 

POST

code

string (100)

The custom code for the placement

  

code2

string (100)

The second custom code for the placement.

  

code3

string (100)

The third custom code for the placement.

  

state

enum

The state of the placement. Possible values: "active" or "inactive".

"active"

 

width

int

The width of the placement.

  

height

int

The height of the placement.

  

is_resizable

Boolean

If the placement uses a friendly iFrame and you want the placement to resize to fit smaller or larger creatives, set this field to true.

false

 

default_position

enum

The default position of the placement on the page. Possible values: "above" (above the fold), "below" (below the fold), or "unknown".

"unknown"

 

publisher_id

int

The ID of the publisher associated with the placement.

 

POST

publisher_name

string (100)

The name of the publisher associated with the placement.

  

site_id

int

The ID of this placement's parent site. Each placement must belong to a site.

Site of publisher

 

site_name

string (100)

The name of the site on which the placement is used.

  

inventory_source_id

int

Deprecated.

  

ad_profile_id

int

The ID of the ad profile associated with the placement. (Note: The preferred way to "assign" an ad profile to a placement is as follows: Create an Ad Quality Rule with a targeting profile (the profile "targets" the placement). Link the Ad Profile to the Ad Quality Rule. Assign the Ad Quality Rule to the publisher. That way you can enjoy a greater flexibility using the targeting profile.)

  

supported_media_types

array of objects

The media types that are allowed to serve on the placement. See Supported Media Types below for more details.

If you do not specify either supported_media_types or supported_media_subtypes, the "Banner" media type and all of its subtypes will be allowed by default.

  

supported_media_subtypes

array of objects

The media subtypes that are allowed to serve on the placement. See Supported Media Subtypes below for more details.

  

pop_values

array

Deprecated.

  

default_creative_id

int

Deprecated. Please use default_creatives instead.

  

default_creatives

array

The default creatives that will be displayed instead of a PSA when there is no auction winner. For each default creative, the reserve price is set with the "price" field in the array. See Default Creatives below for more details. Note for pops placements: The placement will not pop if the reserve price is not met, except in the case of a prepop.

  

reserve_price

double

The reserve price for each of the placement's default creatives is set in the default_creatives array (see Default Creatives below). If the placement does not have default creatives, a reserve price can be set here for the placement; this is not best practice, however, as the reserve price may cause the display of a PSA.

A Yield Management Profile will supersede any reserve price settings at the Placement level. If you have such a profile, you must set your desired reserve price via a hard floor.

  

hide_referer

Boolean

If true, the referrer will not be reported.

  

default_referrer_url

string

If a Visibility Profile is set to hide inventory URLs in your bid requests, you can set this field to pass a vanity URL instead. This is particularly useful in cases where publishers do not want to share actual domains but nonetheless want buyers to be able to identify them by domain.

  

visibility_profile_id

int

The ID of the visibility profile assigned directly to the placement. For more details about visibility profiles, see the Visibility Profile Service.

  

exclusive

Boolean

Read-only.

To designate whether a placement's inventory is to be made available for resale, use the rtb field in the marketplace_map object of the placement's site. See Site Service for a description of this field. All inventory made available for resale is part of the RTB Marketplace.

false

 

pixel_url

string

Piggyback call upon user loading placement.

null

 

pixel_type

enum

Identifies the type of pixel. Possible values are "javascript" or "image".

image

 

content_categories

array

A list of Content Categories associated with this placement (Customer login required). At most 20 categories can be specified for a placement.

  

filtered_advertisers

array

A list of advertisers that are allowed to target the placement.

  

filtered_line_items

array

A list of line items that are allowed to target the placement.

  

filtered_campaigns

array

A list of campaigns that are allowed to target the placement.

  

segments

array

A list of segments that users will be added to upon viewing this placement.

  

estimated_clear_prices

array of objects

The bid amount that has historically won the majority (95%) of the 3rd party auctions in which it participates. See Estimated Clear Prices below for more details.

  

media_subtypes

array

Deprecated. Please use supported_media_types and supported_media_subtypes instead.

  

intended_audience

enum

Values for self-auditing only. Possible values: "general", "children", "young_adult", or "mature".

  

inventory_attributes

array

The sensitive attributes contained by the placement. Note that inventory_attributes can also be applied at the site level, and in this case will influence objects at the placement level, as well. This is an array of objects with IDs. Please see the Inventory Attribute Service for a list of IDs.

  

audited

Boolean

If true, the placement has been self-audited by the owner.

false

 

audit_level

enum

Values for self-auditing only. Note that self-audits at the site level can be overridden at the placement level. Possible values:

  • "site" - Use this value if the audited field is set to false in the placement but true in the site.
  • "placement" - Use this value if the audited field is set to true in the placement.

"site"

 

default_calculation_type

enum

This determines the bid price threshold below which a default creative will be served. You can choose whether this threshold is the network's gross revenue or the publisher's net revenue. If there are no additional eligible campaigns, nor any default creatives available, a PSA is served. Possible values: "gross" or "net".

"gross"

 

apply_floor_to_direct

Boolean

Removed. Please use floor_application_target instead.

  

demand_filter_action

string

Indicates demand sources which can be included or excluded.

default

 

floor_application_target

enum

The type of bids to which the reserve price is applied. Possible values:

  • "external_only" - The reserve price is applied only to external bids (buying member and selling member are different). Use this option if you would rather serve an available managed learn impression than serve a default, even if this means exceeding the maximum % of daily volume for learn (max_learn_pct field in Publisher Service).
  • "external_non_preferred" - The reserve price is applied to external bids (buying member and selling member are different) or when the impression is an available managed learn impression that exceeds the maximum % of daily volume for learn. Use this option if you would rather serve a default than serve an available managed learn impression that would exceed the maximum % of daily volume for learn.
  • "all" - The reserve price is applied to all bids except managed learn impressions within the maximum % of daily volume for learn.

"all"

 

pixel_url_secure

string

Secure piggyback call upon user loading placement.

null

 

site_audit_status

enum

Indicates how the site has decided to perform creative audits. Possible values are "self" or "unaudited".

unaudited

 

toolbar

object

Sellers must declare all toolbar and browser-plugin inventory. If a seller assigns the "toolbar" inventory attribute, this additional meta data must also be included. See Toolbar & Browser Plug-in Declaration and Policies for Selling for more information (Customer login required).

  

acb_code

string (32)

Deprecated.

  

tag_data

string

Deprecated.

  

cost_cpm

double

If a value exists, it will be used as the payment information for the placement. This will override any payment rules associated with the publisher. See Payment Rules for more information.

null

 

is_prohibited

Boolean

Read-only. If true, the placement has been prohibited due to violation of Xandr content policies (Customer login required). Direct and third-party auctions will not be run for a prohibited placement.

false

 

last_modified

timestamp

Read-only. The date and time when the placement was last modified.

  

stats

object

The stats object has been deprecated (as of October 17, 2016). Use the Report Service to obtain statistical information instead.

  

content_retrieval_timeout_ms

int

The timeout this placement will set on content retrieved from "mediated" creatives, i.e., creatives whose content_source is set to "mediation". For more information, see the Creative Service.

  • If set to 0, the ad server will use the value from the Member Service
  • Defaults to 0 if not provided to the API on PUT or POST calls
  • If ad server reads a 0 in this field, it will perform a member lookup and use the default timeout defined by the Member Service (assuming it's also non-zero).
  • When creating a placement, no values will be copied into this field from the member's default settings. You must explicitly specify them in your calls to POST. For more information, see the default_content_retrieval_timeout_ms field of the Member Service.

0

 

enable_for_mediation

Boolean

This will be the source of truth for whether a placement should accept mediated content. Unless set on PUT or POST, this field will inherit its default value from the member. If the default value is changed on the Member Service, that action will not retroactively impact placements created previously; they will continue to be set to the old default value. In other words, the value of this field cannot be updated retroactively by setting the member default. For more information, see the default_enable_for_mediation field of the Member Service.

Inherited from default_enable_for_mediation field of the Member Service.

 
private_sizes

array of objects

The list of placement sizes that may be allowed to serve in deals and packages. See Private Sizes below for more details.

  
videoobject

The media subtype allowed to serve on the placement. See Video Settings below for more details.

 

null 
ad_typesarray of objectsContains information relating to placement types, including the ad type ID and information about the renderer. For more information, see Ad Types below.nullPUT

use_detected_domain

bool

Read-only. Whether to use the detected domain versus the reported domain. Defaults to true for all clients.

true

 
mime_typesarray of stringsThe list of mime types to include or exclude on the placement. supported_mime_types_action_include below is used to specify whether to include or exclude those mime types.empty 
supported_mime_types_action_includebooleanIf true, the mime types listed in the mime_types array will be included.false 
handles_mixed_mediabooleanThis tells our platform whether the video player can support a VAST file with different mime types.true 
 

Supported Media Types

Creatives are categorized by media type and media subtype. Media type defines the general display style of the creative, for example, "Banner", and media subtype defines the specific display style of creatives, for example, "Standard Banner" or "In-Banner Video". You can use this array to limit the media type, the general display style of creatives, that can serve on a placement. To limit the media subtype, the specific display style of creatives, use the supported_media_subtypes array (see Supported Media Subtypes below).

Field

Type

Description

Default

id

int

The ID of the allowed media type. You can use the Media Type Service to view all media types.

1

name

string

The name of the allowed media type.

"Banner"
media_type_group_idintThe group ID for the media type. 
uses_sizesenumWhether the media type has size specifications. Possible values: "always", "sometimes", "never". 
last_modifieddateWhen the allowed_media_type object was last updated. 

Supported Media Subtypes

Creatives are categorized by media type and media subtype. Media type defines the general display style of the creative, for example, "Banner", and media subtype defines the specific display style of creatives, for example, "Standard Banner" or "In-Banner Video". You can use this array to limit the media subtype, the specific display style of creatives, that can serve on a placement. To limit the media type, the general display style of creatives, use the supported_media_types array (see Supported Media Types above).

Field

Type

Description

Default

id

int

The ID of the allowed media subtype. You can use the Media Subtype Service to view all media subtypes.

null

name

string

The name of the allowed media subtype.

 
is_privatebooleanWhether the media subtype is set to private. If true then yes. 
media_type_group_idintThe group ID for the media type. 

Notes on Supported Media Types and Media Subtypes

  • If you do not specify either supported media types or supported media subtypes, the "Banner" media type and all of its subtypes will be allowed by default.
  • You can combine the "Banner" and "Text" media types, and any combination of their media subtypes, on a single placement, but you cannot combine any of the other media types and media subtypes. This limitation ensures that only appropriate creatives are served on a placement. For example, a placement that allows creatives of the media type "Video" is intended to be fed to a video player; it would not make sense to allow creatives of any other media type, such as "Interstitial", to serve on the placement.
  • You can set a placement to allow the "Expandable" media type or any of its subtypes for direct inventory. If you want to support expandable creatives for placements that are available for reselling to other platform members, please provide the placement's ID to support for verification.

Video Settings

If the supported_media_type is "video" or the supported_media_subtypes is "Standard VAST", these fields should be included in the video object. Please see below for an example

The following settings affect auction outcomes: for Outstream player settings, which determine the ultimate behavior of the Outstream video player, see "Outstream Video Player Settings" in our UI documentation.

Field

 

Type

Description

id

 

int

The ID of the video creative.

width

 

int

The width of the video creative.

max_duration_secs

 

int

The maximum duration of a video ad that is allowed to be played on the placement.

If maximum_number_ads is > 1, then the max duration applies to the entire length of an ad pod (a linear grouping of more than one ad designed to fill a single placement).

This field must be set in order to enable ad pods.

maximum_ad_duration_secs intThe maximum video ad duration in seconds of any single ad that can be played on the placement. This only applies to ad pods.
maximum_number_ads
 intThe maximum number of ads that are allowed to be played on the placement. If maximum_number_ads is > 1, then the placement can be an ad pod (a linear grouping of more than one ad designed to fill a single placement).
start_delay_secs int

The start delay in seconds for the placement. If the start delay value is > 0, then the position of the placement is "mid-roll".

This field must be set if the context is "mid-roll".

skipoffset_seconds  int

 The number of seconds that is allowed for the video to play, before it can be skipped.

The default value is null.

If you set this value to anything but null, the supports_skippable field must be set to true. (See below).

supports_skippable

 

boolean

The ad slot is skippable.

Possible values: "true" or "false"

context

 

string

Roll position of the video creative.

Possible Values: "pre-roll", "mid-roll", "post-roll".

This field must be set in order to enable ad pods.

playback_method string

The different playback methods are:

  • Auto-play, sound-on
  • Auto-play, sound-off
  • Click-to-play
  • Mouse-over
  • Auto-play, sound unknown

Possible values: "auto_play_sound_on", "auto_play_sound_off", "click_to_play", "mouse_over", "auto_play_sound_unknown", null

frameworks array of strings

The framework of the placement. Options include:

  • VPAID 1.0
  • VPAID 2.0
  • MRAID-1
  • ORMMA
  • MRAID-2

Possible values: "vpaid_1_0", "vpaid_2_0", "mraid_1", "ormma" and "mraid_2"

video_bumpers
 array of objectsThe bumpers that can be associated with the ad pod. Bumper duration is not included in the overall duration of the ad pod. See video bumpers object.
player_vast_version
 string

This field specifies the highest vast version the placement supports, and should be set to highest value that your player supports. Creatives that require a vast version higher than your player version will not be eligible to serve in your placement.

Possible values:

  • 2.0
  • 3.0
  • 4.0

Specifying a value higher than your player supports may cause errors when unsupported creatives are rendered.

Video Bumpers

This array of objects contains information relating to the bumpers on an ad pod.

FieldType (Length)DescriptionDefault
video_bumper_typestring

The type of bumper. Options include:

  • intro
  • outro
null
max_duration_secsint

The max duration of the bumper.

null

Ad Types

This array of objects contains information relating to placement types, including the ad type ID and information about the renderer.

FieldType (Length)DescriptionDefaultRequired On
idint

The ID of the ad_type.

Possible values:

  • 1 = Banner
  • 2 = Video
  • 3 = Native
nullPOST/PUT
renderer_idint

The ID of the renderer.

Possible values:

  • 1 = outstream banner
  • 2 = outstream video
nullPOST/PUT
namestringThe name of the ad_type in all lowercase letters for example video or banner  
display_namestringThe display name of the ad_type, shown as the ad type with initial caps, for example Video or Banner.  
renderermulti objectAn object consisting of the id and display_name of the renderer.nullPOST/PUT

Default Creatives

You use this array to assign default creatives to the placement. Please note the following requirements:

  • A default creative must not be expired. See the is_expired field in the Creative Service for more information.

  • A default creative must be assigned to a creative template that matches the supported_media_types and supported_media_subtypes of the placement. For example, if the placement allows creatives of the "Banner" media type, you would not be able to associate default creatives that use a creative template for the "Interstitial" media type. See the template field in the Creative Service for more information.

  • If the placement is sized (the "width" and "height" fields are defined for the placement), this array should contain only one creative with the matching dimensions.

Field

Type

Description

id

int

The ID of the default creative.

width

int

The width of the default creative.

height

int

The height of the default creative.

price

double

The reserve price for the default creative. A winning bid must be above this price.

name

string

Read-only. The name of the default creative.

Pop Values

If the supported_media_type is "Pop", or the supported_media_subtypes is "Popup" or "Popunder", these fields should be included in the pop_values array. Please see below for an example.

Field

Type

Description

Default

Required On

pop_freq_times

int

Number of times that the tag can be popped to a unique user ID in pop_frequency_duration seconds. Has no effect when pop_is_prepop is set to true.

No frequency cap

 

pop_freq_duration

int

See pop_freq_times.

No frequency cap

 

pop_is_prepop

Boolean

If true, the tag is a prepop tag and will serve into a window that the publisher page has already popped.

false

 

pop_max_width

int

If pop_max_width is specified, any creative shown by the tag must have a width equal to or smaller than pop_max_width

no max width

 

pop_max_height

int

The max height of the creative. If pop_max_height is specified, any creative shown by the tag must have a height equal to or smaller than pop_max_height

no max height

 
Estimated Clear Prices

Field

Type

Description

Default

Required On

clear_price

int

The bid amount that has historically won the majority (95%) of the 3rd party auctions in which it participates for this placement.

  

average_price

double

This is the average of all bids submitted for this placement.

  

width

int

When exporting sizeless placement tags to be served, this determines the width of the placement.

  

height

int

When exporting sizeless placement tags to be served, this determines the height of the placement.

  

verified

Boolean

Indicates whether the creative has been verified.

  
geo_countrystringThe country code for the geographical location associated with the impression.  
Private Sizes

This array determines the specific placement sizes that are allowed to serve for a custom deal or in a package. The override_size_preference in the Deal Service or Package Service must be set to append for these private sizes to serve along with the standard placement sizes. If set to override, the private sizes are used instead of the standard sizes.

Field

Type

Description

Default

Required On

width

int

The width of the placement.

  

height

int

The height of the placement.

  
Stats

The stats object has been deprecated (as of October 17, 2016). Use the Report Service to obtain statistical information instead.

Toolbar & Browser Plug-in Declaration

According to platform policy (customer login required), sellers must identify all toolbar/browser plug-in inventory and segregate it from other inventory on its own placements. To identify toolbar inventory, sellers must:

  • Set the inventory_attribute appropriately

  • Send the required information in the toolbar array, described here:

Parameter

Type

Description

name

string

The common trade name of the toolbar.

company

string

The developer of the toolbar. Please identify the legal business entity, not a trade name.

tos_url

string

A link to a web page where our auditors can find complete terms of service.

install_url

string

A link to a web page where our auditors can install the toolbar.

The license could not be verified: License Certificate has expired!

The license could not be verified: License Certificate has expired!

Examples

Viewing all placements for one of your publishers
Viewing a specific placement
Adding a placement that allows only creatives with the "Interstitial" media type
Adding a placement that allows only creatives with the "In-Banner Video" media subtype
Adding a placement that allows only creatives with the "Popup" media subtype
Adding a placement that allows only creatives with the "Video Standard VAST" media subtype
   Adding an ad pod placement that allows an intro bumper
   Adding a placement with the skipoffset feature enabled