---
title: "Update banner"
type: reference
method: POST
path: /rest-api/banner/{bannerId}/update.do
tag: "Banners"
---

# Update banner

`POST https://YOUR-NETWORK-DOMAIN/rest-api/banner/{bannerId}/update.do`

Updates an existing banner's properties including name, active status, weight, creative files, template properties, labels, auto-linking settings, tracking codes, and native ad preferences. Supports all banner types (LOCAL_FILE, EXTERNAL_FILE, CODE, TEMPLATE, VPAID_FRAMEWORK, native, video, DSP, etc.). Only provided fields are updated; omitted fields remain unchanged. The response returns the full updated banner object. Parameters that were sent but not applied are listed in 'ignoredFields', each with its reason in 'ignoredFieldReasons'.

## Path params

| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| `bannerId` | integer | yes | `3001` | ID of the banner to update |

## Query params

| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| `autolinkCategories` | array<integer> | no | `5` | IDs of the publisher categories whose new placements the banner auto-links to, comma-separated or repeated — optional: with none set, autoLinkLabels alone decide; with both set, a placement must match both |
| `autoLinkLabels` | array<string> | no | `premium` | Label names whose new placements the banner auto-links to (the placement needs at least one of them), comma-separated or repeated — a name that does not exist yet is created. Works with or without autolinkCategories |
| `active` | boolean | no | `true` | Whether the banner is active |
| `adUnitHeight` | integer | no | `250` | Ad unit height in pixels: the size of a custom ad unit, or without adUnitId the size to pick the ad unit by |
| `adUnitId` | integer | no | `5` | Ad unit ID for the banner dimensions; list them with GET /rest-api/ad-units.do. When omitted, adUnitWidth and adUnitHeight pick the ad unit of that size for the placement type, or its custom ad unit. On update, omitting all three keeps the stored size |
| `adUnitWidth` | integer | no | `300` | Ad unit width in pixels: the size of a custom ad unit, or without adUnitId the size to pick the ad unit by |
| `additionalParameters` | object | no | `value` | Additional banner parameters as key-value pairs, e.g. additionalParameters['flashVars']. On update the keys sent are set and the others kept; a key sent with an empty value is removed. The click target is the separate target field |
| `advertisingNetworkParameters` | object | no | `{"NATIVE_ADAPTER_TEMPLATE_ID":"value"}` | Advertising network parameters for DSP banners. Valid keys: NATIVE_ADAPTER_TEMPLATE_ID, TEMPLATE_ID, BROKER_URL, WIN_NOTIFICATION_URL, DSP_TRAFFIC_TIER, BANNER_MASK_INVENTORY, SECOND_PRICE_ONLY, ALLOW_EMPTY_DSP_UID, DSP_CUSTOM_CURRENCY, USD_TO_DSP_CUSTOM_CURRENCY_RATE, CONTENT_ADAPTER_TEMPLATE_ID, FORCE_FIRST_PRICE, LURL_NOTIFICATION, LURL_NOTIFICATION_AUCTION_PRICE_AVAILABLE, HASH_PUBLISHER_SITE_FIELDS_VALUES, ADD_SOURCE_SCHAIN, CUSTOM_SOURCE_SCHAIN_ASI, INTERSTITIAL |
| `allowNewPlacementsAutoLinking` | boolean | no | `true` | Allow auto-linking to new placements |
| `allowUseForTemplate` | boolean | no | `false` | Allow use of this banner as a template |
| `always2ndPrice` | boolean | no | `true` | Always use second-price auction for this banner |
| `applicationAdCategory` | string | no | `BANNER` | Application ad category. Allowed values: BANNER, INTERSTITIAL, NATIVE_AD, REWARDED_VIDEO |
| `applicationOperatingSystem` | string | no | `ANDROID` | Target operating system for application banners. Allowed values: ANDROID, IOS |
| `applicationPreCheckPackages` | string | no | `com.northwind.app` | App banner: packages to check on the device before showing the banner, comma-separated. Needs the Application Pre-Check permission |
| `bannerType` | string | no | `EXTERNAL_FILE` | Conditionally required — when creating a banner that is not built from a self-serve prototype (selfServeCampaignType). Creative type, which decides the fields that carry the creative: EXTERNAL_FILE - image hot-linked from imageBannerLink, click URL in url, size from adUnitId (or adUnitWidth + adUnitHeight); CODE - HTML/JS in code; VAST_2_0_TAG_URL - third-party VAST/VPAID tag in vastTagUrl (placementType VIDEO_PLACEMENT, size optional); EXTERNAL_VIDEO - video file URL in videoFileLink, click URL in url; TEMPLATE - templateId plus one request parameter per template property, named by the property key (see GET /rest-api/template/{id}/properties.do), an HTML5 ZIP property filled by html5ZipUrl and a FILE property by fileUrl; EXTERNAL_NATIVE - iconUrl / imageUrl / videoUrl (hot-linked) with title, description, callToAction and clickUrl; OPENRTB_DSP - dspPartnerId; LOCAL_FILE - the image stored on the ad server, uploaded as imageFile or fetched from imageFileUrl, click URL in url, size from adUnitId; LOCAL_VIDEO - the video stored on the ad server, uploaded as videoFile or fetched from videoFileUrl; LOCAL_NATIVE - icon / image / video stored on the ad server, uploaded as nativeIconFile / nativeImageFile / nativeVideoFile or fetched from nativeIconFileUrl / nativeImageFileUrl / nativeVideoFileUrl, with title, description, callToAction and clickUrl. |
| `boundedInstallActionId` | integer | no | `12` | Mobile / app banner: id of the conversion action tracking the app install |
| `callToAction` | string | no | `Install Now` | Call-to-action text for native banners |
| `clickUrl` | string | no | `https://www.example.com/app` | Click URL for native banners |
| `code` | string | no | `<a href="https://www.example.com"><img src="https://cdn.example.com/300x250.png"></a>` | HTML/JavaScript markup of a CODE banner |
| `customParameters` | array<string> | no | `1` | Custom native banner parameters |
| `description` | string | no | `Download our app and get 50% off` | Description text for native banners |
| `directFileDownload` | boolean | no | `false` | Whether to enable direct file download for the banner |
| `displayType` | string | no | `VIEW` | Android interstitial app banner: show it as a VIEW or as an ACTIVITY |
| `dspPartnerId` | integer | no | `42` | DSP partner ID for OpenRTB banners |
| `enablePassbackFunctionality` | boolean | no | `false` | Enable passback functionality for this banner |
| `enableViewTracking` | boolean | no | `true` | Whether to enable view tracking for this banner. Needs the Banner View Tracking permission |
| `hardLinkage` | boolean | no | `true` | Hard linkage: when true the banner serves only on the placements it is linked to. Needs the Link Placements to Banners permission |
| `hostExternalFiles` | boolean | no | `true` | EXTERNAL_FILE, EXTERNAL_VIDEO and EXTERNAL_NATIVE only: download the files from imageBannerLink / videoFileLink / iconUrl, imageUrl, videoUrl and serve our stored copy instead of the links. The links are kept; a changed link is downloaded again; false serves the links again and drops the copy. Omitted keeps the current setting. |
| `iconHeight` | integer | no | `100` | Native icon height in pixels |
| `iconUrl` | string | no | `https://cdn.example.com/icon.png` | External URL to native icon image; an empty value removes it, omitted keeps it |
| `iconWidth` | integer | no | `100` | Native icon width in pixels |
| `imageBannerLink` | string | no | `https://cdn.example.com/banner-300x250.png` | Image URL of an EXTERNAL_FILE banner. The image is hot-linked from this address at serve time unless hostExternalFiles is on; it should match the ad unit's size. |
| `imageFileUrl` | string | no | `https://cdn.example.com/creatives/summer-sale-300x250.png` | URL of the image of a LOCAL_FILE banner - the multipart-free way to upload imageFile: the image is downloaded and stored as the banner's own file (served from the ad server/CDN, not hot-linked; for a hot-linked image use EXTERNAL_FILE with imageBannerLink). GIF, JPEG, PNG or SVG (sanitised); the console's size limit for the ad unit applies. On update it replaces the stored image. The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter. |
| `imageHeight` | integer | no | `627` | Native image height in pixels |
| `imageUrl` | string | no | `https://cdn.example.com/image.jpg` | External URL to native image; an empty value removes it, omitted keeps it |
| `imageWidth` | integer | no | `1200` | Native image width in pixels |
| `inStreamVideoType` | string | no | `LINEAR_VIDEO_AD` | In-stream video ad type. Allowed values: LINEAR_VIDEO_AD (linear video), NON_LINEAR_VIDEO_AD (overlay) |
| `labelUpdateType` | string | no | `ADD` | How to update labels. Allowed values: add (append), overwrite (replace all existing), remove (delete specified), clear (remove all) |
| `labels` | array<string> | no | `Summer Sale` | Labels to apply to the banner |
| `mimeTypes` | string | no | `video/mp4,video/webm` | OPENRTB_DSP banner on a video placement: video MIME types sent in the bid request, comma-separated. Needs the Open RTB permission |
| `name` | string | no | `Summer Sale 300x250` | Banner name, up to 512 characters and never blank |
| `nativeIconFileUrl` | string | no | `https://cdn.example.com/creatives/app-icon-100.png` | URL of the icon of a LOCAL_NATIVE banner - the multipart-free way to upload nativeIconFile. GIF, JPEG, PNG or SVG; fitted to iconWidth x iconHeight as an upload is. On update it replaces the stored icon. The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter. |
| `nativeImageFileUrl` | string | no | `https://cdn.example.com/creatives/hero-1200x627.jpg` | URL of the main image of a LOCAL_NATIVE banner - the multipart-free way to upload nativeImageFile. GIF, JPEG, PNG or SVG; fitted to imageWidth x imageHeight as an upload is. On update it replaces the stored image. If its file name is already taken by the icon it is stored as image-<name>. The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter. |
| `nativeVideoFileUrl` | string | no | `https://cdn.example.com/creatives/app-preview.mp4` | URL of the video of a LOCAL_NATIVE banner - the multipart-free way to upload nativeVideoFile. MP4, at least videoWidth x videoHeight in the same orientation, up to the video size limit. On update it replaces the stored video. The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter. |
| `rating` | number | no | `4.5` | Rating value for native banners (e.g., app store rating) |
| `returnAsIframe` | boolean | no | `true` | Video-placement banner: return the creative inside an iframe in the VAST response |
| `skipButtonShowAfterSeconds` | integer | no | `5` | Video banner: seconds before the player shows the skip button. Needs the Video Skip Button permission |
| `subtitle` | string | no | `Free Download` | Subtitle text for native banners |
| `target` | string | no | `_BLANK` | HTML link target for the banner's click-through URL (not applicable to CODE type) |
| `targetTemplateName` | string | no | `Mobile US targeting` | Target template name for template-based banners, up to 50 characters |
| `thirdTrackingCode` | object | no | `value` | Third-party tracking code (HTML/JavaScript fired with the impression) per country: thirdTrackingCode[*] for every country, thirdTrackingCode[US] for one - the key is * or a two-letter country code (any case; stored upper-case, GB as UK); any other key is not applied and is listed in ignoredFields. An empty value removes that code. Not applied to EXTERNAL_VIDEO banners. Needs the BANNER_THIRD_PARTY_TRACKING permission. |
| `title` | string | no | `Best App Ever` | Title text for native banners |
| `universalAdIdRegistry` | string | no | `ad-id.org` | Registry of the video creative's Universal Ad ID (VAST UniversalAdId idRegistry); empty with a code set means ad-id.org |
| `universalAdIdValue` | string | no | `ABCD1234000H` | ISCI / Ad-ID code of the video creative, sent as the VAST UniversalAdId; an empty string clears it |
| `url` | string | no | `https://www.example.com/landing` | Click-through (landing page) URL of EXTERNAL_FILE, LOCAL_FILE, EXTERNAL_VIDEO, LOCAL_VIDEO and TEMPLATE banners. For a VAST_2_0_TAG_URL banner this field stores the VAST tag URL; send it as vastTagUrl instead. |
| `usePlacementSize` | boolean | no | `false` | Use placement size instead of banner size |
| `vast40WrapperAllowMultipleAds` | boolean | no | `false` | VAST 4.0: allow multiple ads in response |
| `vast40WrapperFallbackOnNoAds` | boolean | no | `true` | VAST 4.0: fallback when no ads available |
| `vast40WrapperFollowAdditionalWrappers` | boolean | no | `true` | VAST 4.0: follow additional wrapper redirects |
| `vastTagUrl` | string | no | `https://ads.example.com/vast?id=123` | Third-party VAST/VPAID tag URL of a VAST_2_0_TAG_URL banner (placementType VIDEO_PLACEMENT). Takes precedence over url, which older clients send for the same value. The player follows the tag, so the banner needs no ad unit; adUnitWidth + adUnitHeight are kept when given. |
| `videoFileLink` | string | no | `https://cdn.example.com/video.mp4` | Video file URL of an EXTERNAL_VIDEO banner |
| `videoFileName` | string | no | `promo_video.mp4` | Video file name |
| `videoFileUrl` | string | no | `https://cdn.example.com/creatives/summer-sale-15s.mp4` | URL of the video of a LOCAL_VIDEO banner - the multipart-free way to upload videoFile: the video (MP4 or FLV) is downloaded and stored as the banner's own file, up to the configured video size limit (20 MB by default, never more than 100 MB). On update it replaces the stored video. The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter. |
| `videoHeight` | integer | no | `1080` | Native video height in pixels |
| `videoUrl` | string | no | `https://cdn.example.com/video.mp4` | External URL to native video; an empty value removes it, omitted keeps it |
| `videoWidth` | integer | no | `1920` | Native video width in pixels |
| `weight` | integer | no | `10` | Banner weight for rotation (higher weight = more impressions), 1 to 32767 |
| `templateId` | integer | no | `100` | Conditionally required — when bannerType is TEMPLATE. Template ID |
| `vpaidFrameworkId` | integer | no | `50` | Conditionally required — when bannerType is VPAID_FRAMEWORK. VPAID framework ID |
| `linkToPlacements` | boolean | no | `false` | If true, after the update link the banner to every placement its auto-linking rules match: the banner's own when allowNewPlacementsAutoLinking is on (narrowed by autolinkCategories / autoLinkLabels), otherwise its campaign's. With auto-linking off on both, or without the Link Placements to Banners or Auto-Linking Settings permission, nothing is linked and the field is listed in ignoredFields with the reason. |
| `selfServRequest` | boolean | no | `false` | If true, applies Self-Serve template property handling |
| `status` | string | no | `APPROVED` | New approval status to set (NEW, PENDING, APPROVED, REJECTED). Changing it needs the BANNERS_APPROVAL permission; without it the status is left as it is and listed in ignoredFields, while the rest of the update is saved. Sending the current status changes nothing. |
| `deleteImage` | boolean | no | `false` | If true, removes the banner's current image file; a LOCAL_FILE banner must then upload its replacement in imageFile. imageFileUrl replaces the image without it. |
| `mediaAssetId` | integer | no | `42` | Media library file the creative uses instead of an upload (GET /rest-api/media-library/assets.do): a video for LOCAL_VIDEO, an image for LOCAL_FILE, a video ADVANCED_LOCAL_VIDEOS adds to its media files. The file is referenced, not copied. A TEMPLATE banner whose template has one HTML5 ZIP property takes a library ZIP here; with several, send mediaAsset.<property key> per property, e.g. mediaAsset.$$HTML5_HEAD$$=42. Requires the MEDIA_LIBRARY permission. |
| `html5ZipUrl` | string | no | `https://cdn.example.com/creatives/summer-sale-300x250.zip` | URL of the HTML5 creative's ZIP archive, for a TEMPLATE banner whose template has one HTML5 ZIP property - the way to supply it without a multipart upload. At most 10 MB; the archive must unpack within the HTML5 limits (by default 1000 files, 20 MB a file, 50 MB in all, no path outside its folder). The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter. For a template with several HTML5 ZIP properties send html5ZipUrl[<property key>] per property instead, e.g. html5ZipUrl[$$HTML5_HEAD$$]. On update it replaces the stored archive. |
| `fileUrl` | string | no | `https://cdn.example.com/creatives/hero-1200x627.png` | URL of the file for a TEMPLATE banner's FILE property (an image or video the template renders) - the way to supply it without a multipart upload; the file must be of a content type the property allows. At most the video size limit (10 MB when that is lower). The server downloads the file once (http/https to a public host only, 10 s to connect or stall, 30 s in all, 3 redirects), types it from its own bytes and stores it exactly as the same file uploaded through the console: the same type, size and dimension checks, the same sanitising (SVG) and the same storage/CDN. A URL that is unreachable, not public, too large or of the wrong type is a 400 naming the parameter. For a template with several FILE properties send fileUrl[<property key>] per property instead, e.g. fileUrl[$$IMAGE$$]. On update it replaces the stored file. |
| `refreshHostedFiles` | boolean | no | `false` | With hostExternalFiles on: download every link of the EXTERNAL_FILE, EXTERNAL_VIDEO or EXTERNAL_NATIVE banner again, for a file that changed behind an unchanged link. A link that changed is downloaded again without it. |

## Body

A multipart form: `imageFile` (file), `nativeIconFile` (file), `nativeImageFile` (file), `nativeVideoFile` (file), `videoFile` (file).

## Responses

- `200` — Banner updated successfully
- `400` — Invalid request or banner not found
- `401` — Authentication error
- `403` — Not enough permissions
- `404` — Not found — resource does not exist

## Example request

```bash
curl --request POST \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/banner/3001/update.do?adUnitId=5&name=Summer%20Sale%20300x250&bannerType=LOCAL_FILE&active=true' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --form 'imageFile=@creative.png'
```

Source: https://epom.com/ad-server/docs/api/banners/post-banner-update