---
title: "Create banner"
type: reference
method: POST
path: /rest-api/banner/create.do
tag: "Banners"
---

# Create banner

`POST https://YOUR-NETWORK-DOMAIN/rest-api/banner/create.do`

Creates a new banner (creative) under the specified campaign. Requires campaignId and placementType at minimum (unless creating from a Self-Serve prototype), and the role permission of the bannerType (e.g. CODE, EXTERNAL_FILE). Supports all banner types including display, video, native, code, VAST/VPAID tag, DSP, and mobile/application advertising networks. Without a file upload: an image by URL is bannerType=EXTERNAL_FILE with imageBannerLink (the image), url (the click) and adUnitId or adUnitWidth + adUnitHeight; a VAST tag is bannerType=VAST_2_0_TAG_URL with placementType=VIDEO_PLACEMENT and vastTagUrl; HTML is bannerType=CODE with code; a template creative is bannerType=TEMPLATE with templateId and one parameter per template property named by its key (GET /rest-api/template/{id}/properties.do), an HTML5 ZIP property filled by html5ZipUrl and a FILE property by fileUrl. A stored (not hot-linked) creative takes its file by URL too, downloaded once and kept exactly as an upload: LOCAL_FILE with imageFileUrl, LOCAL_VIDEO with videoFileUrl, LOCAL_NATIVE with nativeIconFileUrl / nativeImageFileUrl / nativeVideoFileUrl. The response returns the full created banner object with its assigned ID. Parameters that were sent but not applied are listed in 'ignoredFields', each with its reason in 'ignoredFieldReasons'.

## Query params

| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| `campaignId` | integer | yes | `2001` | ID of the campaign to create the banner under |
| `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 |
| `placementType` | string | no | `SITE_PLACEMENT` | Conditionally required — unless the banner is built from a self-serve prototype (selfServeCampaignType). Placement type of the ad: SITE_PLACEMENT, NON_STANDARD_SITE_PLACEMENT, MOBILE_SITE_PLACEMENT, VIDEO_PLACEMENT, APPLICATION_PLACEMENT, EMAIL_PLACEMENT or NATIVE_PLACEMENT. There is no click-through banner: a CLICK_THROUGH_PLACEMENT accepts a banner of any type, so create one of these and link it. |
| `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 |
| `selfServeCampaignType` | string | no | `BANNER_DESKTOP` | Self-Serve campaign type; if set, banner is created from a prototype. Accepts enum name or integer ID for backward compatibility |
| `linkToPlacements` | boolean | no | `false` | If true, after creation 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. |
| `status` | string | no | `NEW` | Initial approval status (NEW, PENDING, APPROVED, REJECTED). A status other than the one the banner is created with needs the BANNERS_APPROVAL permission; without it the field is listed in ignoredFields and the banner is created with its default status. |
| `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. |

## Body

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

## Responses

- `200` — Banner created successfully
- `400` — Invalid request or campaign not found
- `401` — Authentication error
- `403` — Not enough permissions

## Example request

```bash
curl --request POST \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/banner/create.do?campaignId=2001&adUnitId=5&url=https%3A%2F%2Fwww.example.com%2Flanding&name=Summer%20Sale%20300x250&bannerType=LOCAL_FILE&placementType=SITE_PLACEMENT' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --form 'imageFile=@creative.png'
```

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