---
title: "Create or update video placement"
type: reference
method: POST
path: /rest-api/placements/update/video.do
tag: "Placements"
---

# Create or update video placement

`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

| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| `videoFormats` | array<string> | no | `PRE_ROLL,MID_ROLL` | Video ad formats. Accepts enum names or integer IDs for backward compatibility |
| `id` | integer | no | `4001` | ID of the placement to update — omit to create a new placement (then zoneId and type are required, and the caller needs INVENTORY CREATE) |
| `zoneId` | integer | no | `3001` | 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) |
| `type` | string | no | `SITE_PLACEMENT` | 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 |
| `adUnitId` | integer | no | `5` | 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 |
| `adCategory` | string | no | `BANNER` | 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 |
| `operatingSystem` | string | no | `ANDROID` | 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 |
| `actionLimitsEnabled` | boolean | no | `false` | Enable per-action conversion limits |
| `active` | boolean | no | `true` | Whether the placement is active |
| `adPosition` | string | no | `ABOVE_THE_FOLD` | Ad position on page per OpenRTB spec (ABOVE_THE_FOLD, BELOW_THE_FOLD, HEADER, FOOTER, SIDEBAR, FULL_SCREEN) |
| `ajaxCodeAdWrapper` | string | no | `FRIENDLY_FRAME` | Ad wrapper type for invocation code (WITHOUT_WRAPPER, FRIENDLY_FRAME, SANDBOXED_FRAME, NO_REDIRECT_FRAME) |
| `ajaxCodeProtocol` | string | no | `HTTPS` | Protocol for invocation code (RELATIVE, HTTPS, HTTP) |
| `allowVariableBannerSizes` | boolean | no | `false` | Allow banners of different sizes to serve in this placement |
| `alwaysRedirect` | boolean | no | `false` | Always use redirect-based ad serving instead of iframe/JavaScript |
| `applicationAdCategory` | string | no | `BANNER` | Application ad category (BANNER, INTERSTITIAL, NATIVE_AD, REWARDED_VIDEO) |
| `applicationOperatingSystem` | string | no | `ANDROID` | Target operating system for application placements (IOS, ANDROID) |
| `contentReplacementEnabled` | boolean | no | `false` | Enable content replacement mode (ad replaces page content) |
| `customOpenRtbTagId` | string | no | `custom-tag-001` | Custom OpenRTB tag ID sent in bid requests instead of the default placement key |
| `defaultCode` | string | no | `<div>No ads available</div>` | Default HTML code to display when no ad is available (passback) |
| `description` | string | no | `Top-of-page leaderboard ad slot` | Placement description |
| `disableAutoLinking` | boolean | no | `false` | Disable automatic banner-to-placement linking |
| `displayType` | string | no | `VIEW` | Display type for application placements (VIEW, ACTIVITY) |
| `domainAsDefaultChannel` | boolean | no | `false` | Use the site domain as the default channel parameter |
| `enableLinking` | boolean | no | `true` | Enable banner-to-placement linking |
| `enablePricingOverride` | boolean | no | `false` | Allow placement-level pricing to override campaign pricing |
| `enableRules` | boolean | no | `false` | Enable advanced rules engine for this placement |
| `enableTargeting` | boolean | no | `false` | Enable targeting rules for this placement |
| `fitContainer` | boolean | no | `false` | Resize the ad creative to fit the placement container |
| `name` | string | no | `Homepage Leaderboard 728x90` | Placement name |
| `nativePreferences.contextSubType` | string | no | `GENERAL` |  |
| `nativePreferences.contextType` | string | no | `CONTENT_CENTRIC` |  |
| `nativePreferences.iconSize.height` | integer | no | `90` | Height in pixels |
| `nativePreferences.iconSize.width` | integer | no | `728` | Width in pixels |
| `nativePreferences.imageSize.height` | integer | no | `90` | Height in pixels |
| `nativePreferences.imageSize.width` | integer | no | `728` | Width in pixels |
| `nativePreferences.placementType` | string | no | `IN_THE_FEED_OF_CONTENT` |  |
| `nativePreferences.requiredFields` | array<string> | no | `ICON` |  |
| `nativePreferences.videoSize.height` | integer | no | `90` | Height in pixels |
| `nativePreferences.videoSize.width` | integer | no | `728` | Width in pixels |
| `operationBetweenRuleTypes` | string | no | `AND` | Logical operator between different targeting rule types (AND, OR) |
| `piggybackStatus` | string | no | `DISABLED` | Piggyback tracking status (ENABLED, DISABLED) |
| `refreshInterval` | integer | no | `60` | Ad refresh interval in seconds (0 = no refresh) |
| `rotateInterval` | integer | no | `30` | Banner rotation interval in seconds (0 = no rotation) |
| `serverSideTrackersEnabled` | boolean | no | `false` | Whether server-side trackers fire for this placement |
| `servingDomain` | string | no | `ads.example.com` | 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 |
| `showBrandedOverlay` | boolean | no | `false` | Show branded overlay on ads served in this placement |
| `size.adUnit` | string | no | `MEDIUM_RECTANGLE` | Deprecated — prefer adUnitId. Name of a predefined site ad unit; the placement gets the ad unit of that width and height |
| `size.height` | integer | no | `90` | Height in pixels |
| `size.width` | integer | no | `728` | Width in pixels |
| `thirdPartyNetworkLookupLimit` | integer | no | `5` | Maximum number of third-party network lookups for daisy chaining (0-10) |
| `videoAdMaxDuration` | integer | no | `30` | Maximum video ad duration in seconds |
| `videoAdMinDuration` | integer | no | `5` | Minimum video ad duration in seconds |
| `videoAdSkipMin` | integer | no | `5` | Minimum duration in seconds before skip button appears |
| `height` | integer | no | `480` | Video player height in pixels |
| `maxPodDuration` | integer | no | `60` | Maximum ad pod duration in seconds (0-1800) |
| `playbackControlsEnabled` | boolean | no | `true` | Whether video player controls are visible |
| `playbackMute` | boolean | no | `false` | Whether video playback starts muted |
| `playbackSkipAdButtonText` | string | no | `Skip Ad` | Text displayed on the skip-ad button |
| `playbackSkipAdCountdown` | integer | no | `10` | Number of seconds before skip button appears (0-100) |
| `playbackSkipAdCountdownText` | string | no | `Skip in %d` | Text displayed during skip-ad countdown (%d is replaced with seconds) |
| `playbackSkipAdEnabled` | boolean | no | `true` | Whether the skip-ad button is enabled |
| `playbackSkipAdExtraStyle` | string | no | `color: #ffffff; font-size: 14px;` | Extra CSS style for the skip-ad button |
| `playbackVolume` | integer | no | `40` | Default playback volume percentage (0-100) |
| `waterfallExecuteRequestsToPlacementAmount` | integer | no | `1` | Number of waterfall ad requests to execute per placement (0-10) |
| `waterfallIterateTimesThroughCreativesList` | integer | no | `1` | Number of times to iterate through the creatives list (0-10) |
| `waterfallLinearAdBreakMaxShowAmount` | integer | no | `1` | Maximum number of linear ads to show in one ad break (0-20) |
| `waterfallMaximalTimeout` | integer | no | `0` | Maximum timeout in seconds for waterfall ad loading (0-300) |
| `waterfallMinimalTimeout` | integer | no | `0` | Minimum timeout in seconds for waterfall ad loading (0-300) |
| `waterfallReturnCreativesInTheResponseAmount` | integer | no | `1` | Number of creatives to return in the VAST response (0-20) |
| `width` | integer | no | `640` | Video player width in pixels |
| `labels` | array<string> | no | `premium` | Label names to assign to this placement, comma-separated or repeated |
| `labelUpdateType` | string | no | `ADD` | How to handle labels: ADD (default), OVERWRITE, REMOVE, or CLEAR |
| `nativeAdapterTemplateId` | string | no | `100` | 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. |
| `skipButtonEnabled` | boolean | no | `false` | Whether to show the skip ad button on the video player. Omitted keeps the current value; a new placement starts with false |
| `skipButtonShowAfterSeconds` | integer | no | `5` | Seconds before the skip button appears. Omitted keeps the current value; a new placement starts with 5 |
| `vmapMaxNumberOfPreRolls` | integer | no | `2` | Maximum number of pre-roll ads in VMAP response. Omitted keeps the current value; a new placement starts with 2 |
| `vastDefaultAdTitle` | string | no | `My Video Ad` | Default VAST AdTitle value used when the banner has no title |
| `ssaiStitcher` | string | no | `AWS_MEDIATAILOR` | 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. |
| `podSeparation` | string | no | `ADVERTISER_DOMAIN` | 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. |
| `videoPlaybackMethod` | array<string> | no | `AUTO_PLAY_SOUND_OFF,CLICK_TO_PLAY` | 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. |
| `videoApiFramework` | array<string> | no | `VPAID_2_0` | 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. |

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

## Example request

```bash
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'
```

Source: https://epom.com/ad-server/docs/api/placements/post-placements-update-video