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).

Note

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

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

"id" is the placement ID.

Tip

You can include placeholders to pass in additional query string parameters to our platform during the ad call.

Important

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

IFRAME

<!-- BEGIN IFRAME TAG < - DO NOT MODIFY -->
<IFRAME SRC="https://ib.adnxs.com/tt?id=2704"
    FRAMEBORDER="0"
    SCROLLING="no"
    MARGINHEIGHT="0"
    MARGINWIDTH="0"
    TOPMARGIN="0"
    LEFTMARGIN="0"
    ALLOWTRANSPARENCY="true"
    WIDTH="120"
    HEIGHT="600"></IFRAME>
<!-- END TAG -->

JavaScript

<!-- BEGIN JS TAG < - DO NOT MODIFY -->
<SCRIPT SRC="https://ib.adnxs.com/ttj?id=2704" TYPE="text/javascript"></SCRIPT>
<!-- END TAG -->

REST API

Note

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

HTTP Method	Endpoint	Description
`POST`	`https://api.appnexus.com/placement?publisher_id=PUBLISHER_ID` `https://api.appnexus.com/placement?site_id=SITE_ID` (placement JSON)	Add a placement (NETWORK).
`PUT`	`https://api.appnexus.com/placement?id=PLACEMENT_ID&publisher_id=PUBLISHER_ID` `https://api.appnexus.com/placement?code=PLACEMENT_ID&site_id=SITE_ID` (placement JSON)	Modify an existing placement (NETWORK).
`DELETE`	`https://api.appnexus.com/placement?id=PLACEMENT_ID&publisher_id=PUBLISHER_ID` `https://api.appnexus.com/placement?code=PLACEMENT_CODE&publisher_code=PUBLISHER_CODE`	Delete an existing placement.
`GET`	`https://api.appnexus.com/placement?publisher_id=PUBLISHER_ID`	View all of the placements for one of your publishers.
`GET`	`https://api.appnexus.com/placement?id=PLACEMENT_ID`	View a specific placement for one of your publishers.
`GET`	`https://api.appnexus.com/placement?id=1,2,3`	View all placements for a site.

JSON fields

Field	Type	Description
`id`	int	The ID of the placement. Default: Auto-incremented number (i.e. 123) Required On: `PUT`, in query string
`name`	string (100)	The name of the placement. Required On: `POST`
`code`	string (100)	The custom code for the placement. Note: Codes must be alphanumeric and cannot contain spaces. The following characters are also permitted: - period (".") - underscore ("_") - hyphen ("-") - percent ("%")
`code2`	string (100)	The second custom code for the placement. Note: Codes must be alphanumeric and cannot contain spaces. The following characters are also permitted: - period (".") - underscore ("_") - hyphen ("-") - percent ("%")
`code3`	string (100)	The third custom code for the placement. Note: Codes must be alphanumeric and cannot contain spaces. The following characters are also permitted: - period (".") - underscore ("_") - hyphen ("-") - percent ("%")
`state`	enum	The state of the placement. Possible values: `"active"` or `"inactive"`. Default: `"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`. Default: `false`
`default_position`	enum	The default position of the placement on the page. Possible values: - `"above"` (above the fold) `"below"` (below the fold) `"unknown"` Default: `"unknown"`
`publisher_id`	int	The ID of the publisher associated with the placement. Required On: `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. Default: 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. Attention: 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: 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. Important: 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.
`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. Default: `False`
`pixel_url`	string	Piggyback call upon user loading placement. Default: `null`
`pixel_type`	enum	Identifies the type of pixel. Possible values are `"javascript"` or `"image"`. Default: `image`
`content_categories`	array	A list of Content Categories associated with this placement. 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"` - `"mature"`
`inventory_attributes`	array	The sensitive attributes contained by the placement. Tip: The `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. Default: `false`
`audit_level`	enum	Values for self-auditing only. Note: The 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. Default: `"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"`. Default: `"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: `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. Default: `"all"`
`pixel_url_secure`	string	Secure piggyback call upon user loading placement. Default: `null`
`site_audit_status`	enum	Indicates how the site has decided to perform creative audits. Possible values are `"self"` or `"unaudited"`. Default: `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.
`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. Default: `null`
`is_prohibited`	Boolean	Read-only. If `true`, the placement has been prohibited due to violation of Xandr content policies. Direct and third-party auctions will not be run for a prohibited placement. Default: `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. Default: `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. Default: 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.
`video`	object	The media subtype allowed to serve on the placement. See Video Settings below for more details. Default: `null`
`ad_types`	array of objects	Contains information relating to placement types, including the ad type ID and information about the renderer. For more information, see Ad Types below. Default: `null` Required On: `PUT`
`use_detected_domain`	boolean	Read-only. Whether to use the detected domain versus the reported domain. Defaults to `true` for all clients. Default: `true`
`mime_types`	array of strings	The 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. For a list of the strings used to identify each mime types, see Supported Mime Types. Default: `empty`
`supported_mime_types_action_include`	boolean	If `true`, the mime types listed in the `mime_types` array will be included. Default: `false`
`handles_mixed_media`	boolean	This tells our platform whether the video player can support a VAST file with different mime types. Default: `true`
`tinytag_renderer_asset_floor_prices`	array of objects	Associates floor prices to native creatives that have been assigned to the placement. For additional information, see Tinytag Renderer Asset Floor Prices. Required On: `PUT`
`is_ss_native_assembly_enabled`	boolean	When enabled, although the original request will be a banner request, the requests that are sent to bidders will have native info set in order to receive native assets back in the responses. The final response will be set back to a banner ad type with a native assembled ad markup attached. If `true` then yes.
`GPID`	string (255)	Global Placement ID (GPID). Global placement-level identifier provided by the publisher to indicate a specific ad placement on page.

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
`id`	int	The ID of the allowed media type. You can use the Media Type Service to view all media types.