/

Browse the help center

Create or update video placement

Creates a new video placement or updates an existing one.

Reference

POST https://YOUR-NETWORK-DOMAIN/rest-api/placements/update/video.do

Creates a new video placement or updates an existing one. Video placements support VAST/VMAP ad serving with configurable video ad formats (PRE_ROLL, MID_ROLL, POST_ROLL, OVERLAY), waterfall settings for request/response optimization, playback controls (skip button, mute, volume), and player dimensions. If an ID is provided, the existing placement is updated; otherwise a new VIDEO_PLACEMENT is created. On an update, a zoneId other than the placement's own moves it to that zone, on the same or another site, and needs UPDATE on both sites; its banner links and its key stay, so its published ad tags keep working. Video preferences (skip button, VMAP pre-roll limits, default ad title, server-side ad insertion, competitive separation in a pod) are saved alongside the placement. The RTB configuration sent to programmatic demand — playback method (videoPlaybackMethod), API framework (videoApiFramework), min/max ad duration and skip min — needs the Video RTB Configuration permission, as in the console. Parameters that were sent but not applied are listed in 'ignoredFields', each with its reason in 'ignoredFieldReasons'.

Form Params

videoFormats array<string>

Video ad formats. Accepts enum names or integer IDs for backward compatibility

PRE_ROLL,MID_ROLL

id integer

ID of the placement to update — omit to create a new placement (then zoneId and type are required, and the caller needs INVENTORY CREATE)

4001

zoneId integer

ID of the zone to create the placement in — required when id is omitted; on update, a zoneId other than the placement's own moves it to that zone and keeps its key (published ad tags keep working)

3001

type string

Placement type — required when creating and must match the endpoint: SITE_PLACEMENT for update/standard, NON_STANDARD_SITE_PLACEMENT for update/non-standard, MOBILE_SITE_PLACEMENT for update/mobile, VIDEO_PLACEMENT for update/video, APPLICATION_PLACEMENT for update/app, NATIVE_PLACEMENT for update/native, CLICK_THROUGH_PLACEMENT for update/click_through, EMAIL_PLACEMENT for update/email. On update it may be omitted; a value that differs from the stored type is rejected

SITE_PLACEMENT

adUnitId integer

ID of the ad unit that sets the placement size — the preferred way to size a placement (size.adUnit is deprecated). It must be one of the ad units of the placement's type (GET /rest-api/ad-units.do); any other id is refused with 400 and nothing is changed

5

adCategory string

Ad category of an APPLICATION_PLACEMENT (a new placement starts with BANNER; omitted on update keeps the current one). applicationAdCategory sets the same value and wins when both are sent

BANNER

operatingSystem string

Operating system of an APPLICATION_PLACEMENT (a new placement starts with IOS; omitted on update keeps the current one). applicationOperatingSystem sets the same value and wins when both are sent

ANDROID

actionLimitsEnabled boolean

Enable per-action conversion limits

false

active boolean

Whether the placement is active

true

adPosition string

Ad position on page per OpenRTB spec (ABOVE_THE_FOLD, BELOW_THE_FOLD, HEADER, FOOTER, SIDEBAR, FULL_SCREEN)

ABOVE_THE_FOLD

ajaxCodeAdWrapper string

Ad wrapper type for invocation code (WITHOUT_WRAPPER, FRIENDLY_FRAME, SANDBOXED_FRAME, NO_REDIRECT_FRAME)

FRIENDLY_FRAME

ajaxCodeProtocol string

Protocol for invocation code (RELATIVE, HTTPS, HTTP)

HTTPS

allowVariableBannerSizes boolean

Allow banners of different sizes to serve in this placement

false

alwaysRedirect boolean

Always use redirect-based ad serving instead of iframe/JavaScript

false

applicationAdCategory string

Application ad category (BANNER, INTERSTITIAL, NATIVE_AD, REWARDED_VIDEO)

BANNER

applicationOperatingSystem string

Target operating system for application placements (IOS, ANDROID)

ANDROID

contentReplacementEnabled boolean

Enable content replacement mode (ad replaces page content)

false

customOpenRtbTagId string

Custom OpenRTB tag ID sent in bid requests instead of the default placement key

custom-tag-001

defaultCode string

Default HTML code to display when no ad is available (passback)

<div>No ads available</div>

description string

Placement description

Top-of-page leaderboard ad slot

disableAutoLinking boolean

Disable automatic banner-to-placement linking

false

displayType string

Display type for application placements (VIEW, ACTIVITY)

VIEW

domainAsDefaultChannel boolean

Use the site domain as the default channel parameter

false

enableLinking boolean

Enable banner-to-placement linking

true

enablePricingOverride boolean

Allow placement-level pricing to override campaign pricing

false

enableRules boolean

Enable advanced rules engine for this placement

false

enableTargeting boolean

Enable targeting rules for this placement

false

fitContainer boolean

Resize the ad creative to fit the placement container

false

name string

Placement name

Homepage Leaderboard 728x90

nativePreferences.contextSubType string

GENERAL

nativePreferences.contextType string

CONTENT_CENTRIC

nativePreferences.iconSize.height integer

Height in pixels

90

nativePreferences.iconSize.width integer

Width in pixels

728

nativePreferences.imageSize.height integer

Height in pixels

90

nativePreferences.imageSize.width integer

Width in pixels

728

nativePreferences.placementType string

IN_THE_FEED_OF_CONTENT

nativePreferences.requiredFields array<string>

ICON

nativePreferences.videoSize.height integer

Height in pixels

90

nativePreferences.videoSize.width integer

Width in pixels

728

operationBetweenRuleTypes string

Logical operator between different targeting rule types (AND, OR)

AND

piggybackStatus string

Piggyback tracking status (ENABLED, DISABLED)

DISABLED

refreshInterval integer

Ad refresh interval in seconds (0 = no refresh)

60

rotateInterval integer

Banner rotation interval in seconds (0 = no rotation)

30

serverSideTrackersEnabled boolean

Whether server-side trackers fire for this placement

false

servingDomain string

Ad-serving domain this placement's tags and URLs are generated on — one of the domains GET /rest-api/placements/{placementId}/serving-domains.do lists; any other value is refused with 400. Needs the INVOCATION_CODE_DOMAIN permission (Set Ad-Serving Domain (Placement)), without which it is not applied

ads.example.com

showBrandedOverlay boolean

Show branded overlay on ads served in this placement

false

size.adUnit string

Deprecated — prefer adUnitId. Name of a predefined site ad unit; the placement gets the ad unit of that width and height

MEDIUM_RECTANGLE

size.height integer

Height in pixels

90

size.width integer

Width in pixels

728

thirdPartyNetworkLookupLimit integer

Maximum number of third-party network lookups for daisy chaining (0-10)

5

videoAdMaxDuration integer

Maximum video ad duration in seconds

30

videoAdMinDuration integer

Minimum video ad duration in seconds

5

videoAdSkipMin integer

Minimum duration in seconds before skip button appears

5

height integer

Video player height in pixels

480

maxPodDuration integer

Maximum ad pod duration in seconds (0-1800)

60

playbackControlsEnabled boolean

Whether video player controls are visible

true

playbackMute boolean

Whether video playback starts muted

false

playbackSkipAdButtonText string

Text displayed on the skip-ad button

Skip Ad

playbackSkipAdCountdown integer

Number of seconds before skip button appears (0-100)

10

playbackSkipAdCountdownText string

Text displayed during skip-ad countdown (%d is replaced with seconds)

Skip in %d

playbackSkipAdEnabled boolean

Whether the skip-ad button is enabled

true

playbackSkipAdExtraStyle string

Extra CSS style for the skip-ad button

color: #ffffff; font-size: 14px;

playbackVolume integer

Default playback volume percentage (0-100)

40

waterfallExecuteRequestsToPlacementAmount integer

Number of waterfall ad requests to execute per placement (0-10)

1

waterfallIterateTimesThroughCreativesList integer

Number of times to iterate through the creatives list (0-10)

1

waterfallLinearAdBreakMaxShowAmount integer

Maximum number of linear ads to show in one ad break (0-20)

1

waterfallMaximalTimeout integer

Maximum timeout in seconds for waterfall ad loading (0-300)

0

waterfallMinimalTimeout integer

Minimum timeout in seconds for waterfall ad loading (0-300)

0

waterfallReturnCreativesInTheResponseAmount integer

Number of creatives to return in the VAST response (0-20)

1

width integer

Video player width in pixels

640

labels array<string>

Label names to assign to this placement, comma-separated or repeated

premium

labelUpdateType string

How to handle labels: ADD (default), OVERWRITE, REMOVE, or CLEAR

ADD

nativeAdapterTemplateId string

Native adapter template to render this placement through; an empty value detaches the one it carries. The template must be active, of the placement content adapter type, and built for this placement's type. Its properties are set in the same request, one parameter per property named by its key; a FILE property takes a multipart upload under its key or, without multipart, fileUrl[<property key>] (bare fileUrl when the template has one FILE property): the file is downloaded once (http/https to a public host only) and stored exactly as the upload would be. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter.

100

skipButtonEnabled boolean

Whether to show the skip ad button on the video player. Omitted keeps the current value; a new placement starts with false

false

skipButtonShowAfterSeconds integer

Seconds before the skip button appears. Omitted keeps the current value; a new placement starts with 5

5

vmapMaxNumberOfPreRolls integer

Maximum number of pre-roll ads in VMAP response. Omitted keeps the current value; a new placement starts with 2

2

vastDefaultAdTitle string

Default VAST AdTitle value used when the banner has no title

My Video Ad

ssaiStitcher string

Server-side ad insertion service that calls the VAST tag; its macros for the viewer's IP, user-agent, device id and app are added to the tag. An empty value turns it off; omitted keeps the current one.

AWS_MEDIATAILOR

podSeparation string

How competing advertisers are kept apart within one ad pod: ADVERTISER_DOMAIN allows one spot per advertiser domain, ADVERTISER_DOMAIN_AND_CATEGORY also one per advertiser category. The same spot (ISCI / Ad-ID code) never repeats in a pod regardless. An empty value turns separation off; omitted keeps the current one.

ADVERTISER_DOMAIN

videoPlaybackMethod array<string>

Playback methods the video player supports, sent to programmatic demand as OpenRTB video.playbackmethod: AUTO_PLAY_SOUND_ON (1), AUTO_PLAY_SOUND_OFF (2), CLICK_TO_PLAY (3), MOUSE_OVER (4), by name or id, comma-separated or repeated. An empty value clears them; omitted keeps the current ones. Needs the Video RTB Configuration permission.

AUTO_PLAY_SOUND_OFF,CLICK_TO_PLAY

videoApiFramework array<string>

API frameworks the video player supports, sent to programmatic demand as OpenRTB video.api: VPAID_1_0 (1), VPAID_2_0 (2), MRAID_1 (3), ORMMA (4), MRAID_2 (5), MRAID_3 (6), by name or id, comma-separated or repeated. An empty value clears them; omitted keeps the current ones. Needs the Video RTB Configuration permission.

VPAID_2_0

Responses

200

Placement created or updated successfully

400

servingDomain is not one of the ad-serving domains GET placements/{placementId}/serving-domains lists, or adUnitId is no ad unit of the placement's type, or a videoPlaybackMethod or videoApiFramework value that is no such playback method or API framework

401

Authentication error

403

Forbidden — insufficient permissions

Language

cURL Request

curl --request POST \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/placements/update/video.do' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'id=4001' \
  --data-urlencode 'zoneId=3001' \
  --data-urlencode 'name=Homepage Leaderboard 728x90' \
  --data-urlencode 'active=true' \
  --data-urlencode 'videoFormats=PRE_ROLL,MID_ROLL'

Python Request

import requests

response = requests.request("POST", "https://YOUR-NETWORK-DOMAIN/rest-api/placements/update/video.do", headers={"X-Api-Key": "YOUR_API_KEY"}, data={"id": "4001", "zoneId": "3001", "name": "Homepage Leaderboard 728x90", "active": "true", "videoFormats": "PRE_ROLL,MID_ROLL"})
print(response.json())

Node Request

const response = await fetch('https://YOUR-NETWORK-DOMAIN/rest-api/placements/update/video.do', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({"id":"4001","zoneId":"3001","name":"Homepage Leaderboard 728x90","active":"true","videoFormats":"PRE_ROLL,MID_ROLL"}),
});

console.log(await response.json());

Java Request

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://YOUR-NETWORK-DOMAIN/rest-api/placements/update/video.do"))
    .header("X-Api-Key", "YOUR_API_KEY")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .method("POST", HttpRequest.BodyPublishers.ofString("id=4001&zoneId=3001&name=Homepage%20Leaderboard%20728x90&active=true&videoFormats=PRE_ROLL%2CMID_ROLL"))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

C# Request

using var client = new HttpClient();

var request = new HttpRequestMessage(new HttpMethod("POST"), "https://YOUR-NETWORK-DOMAIN/rest-api/placements/update/video.do");
request.Headers.Add("X-Api-Key", "YOUR_API_KEY");
request.Content = new FormUrlEncodedContent(new Dictionary<string, string> { ["id"] = "4001", ["zoneId"] = "3001", ["name"] = "Homepage Leaderboard 728x90", ["active"] = "true", ["videoFormats"] = "PRE_ROLL,MID_ROLL" });

var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Go Request

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, _ := http.NewRequest("POST", "https://YOUR-NETWORK-DOMAIN/rest-api/placements/update/video.do", strings.NewReader(`id=4001&zoneId=3001&name=Homepage%20Leaderboard%20728x90&active=true&videoFormats=PRE_ROLL%2CMID_ROLL`))
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

PHP Request

<?php
$ch = curl_init("https://YOUR-NETWORK-DOMAIN/rest-api/placements/update/video.do");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Api-Key: YOUR_API_KEY", "Content-Type: application/x-www-form-urlencoded"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, 'id=4001&zoneId=3001&name=Homepage%20Leaderboard%20728x90&active=true&videoFormats=PRE_ROLL%2CMID_ROLL');

echo curl_exec($ch);
curl_close($ch);

Ruby Request

require 'net/http'
require 'json'

uri = URI("https://YOUR-NETWORK-DOMAIN/rest-api/placements/update/video.do")
request = Net::HTTP::Post.new(uri)
request['X-Api-Key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/x-www-form-urlencoded'
request.set_form_data('id' => "4001", 'zoneId' => "3001", 'name' => "Homepage Leaderboard 728x90", 'active' => "true", 'videoFormats' => "PRE_ROLL,MID_ROLL")

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.body