Create banner

autolinkCategories array<integer>

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>

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

Whether the banner is active

adUnitHeight integer

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

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

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

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

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

Allow auto-linking to new placements

allowUseForTemplate boolean

Allow use of this banner as a template

always2ndPrice boolean

Always use second-price auction for this banner

applicationAdCategory string

Application ad category. Allowed values: BANNER, INTERSTITIAL, NATIVE_AD, REWARDED_VIDEO

applicationOperatingSystem string

Target operating system for application banners. Allowed values: ANDROID, IOS

applicationPreCheckPackages string

App banner: packages to check on the device before showing the banner, comma-separated. Needs the Application Pre-Check permission

bannerType string

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

Mobile / app banner: id of the conversion action tracking the app install

callToAction string

Call-to-action text for native banners

clickUrl string

Click URL for native banners

code string

HTML/JavaScript markup of a CODE banner

customParameters array<string>

Custom native banner parameters

description string

Description text for native banners

directFileDownload boolean

Whether to enable direct file download for the banner

displayType string

Android interstitial app banner: show it as a VIEW or as an ACTIVITY

dspPartnerId integer

DSP partner ID for OpenRTB banners

enablePassbackFunctionality boolean

Enable passback functionality for this banner

enableViewTracking boolean

Whether to enable view tracking for this banner. Needs the Banner View Tracking permission

hardLinkage boolean

Hard linkage: when true the banner serves only on the placements it is linked to. Needs the Link Placements to Banners permission

hostExternalFiles boolean

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

Native icon height in pixels

iconUrl string

External URL to native icon image; an empty value removes it, omitted keeps it

iconWidth integer

Native icon width in pixels

imageBannerLink string

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

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

Native image height in pixels

imageUrl string

External URL to native image; an empty value removes it, omitted keeps it

imageWidth integer

Native image width in pixels

inStreamVideoType string

In-stream video ad type. Allowed values: LINEAR_VIDEO_AD (linear video), NON_LINEAR_VIDEO_AD (overlay)

labelUpdateType string

How to update labels. Allowed values: add (append), overwrite (replace all existing), remove (delete specified), clear (remove all)

labels array<string>

Labels to apply to the banner

mimeTypes string

OPENRTB_DSP banner on a video placement: video MIME types sent in the bid request, comma-separated. Needs the Open RTB permission

name string

Banner name, up to 512 characters and never blank

nativeIconFileUrl string

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

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

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

Rating value for native banners (e.g., app store rating)

returnAsIframe boolean

Video-placement banner: return the creative inside an iframe in the VAST response

skipButtonShowAfterSeconds integer

Video banner: seconds before the player shows the skip button. Needs the Video Skip Button permission

subtitle string

Subtitle text for native banners

target string

HTML link target for the banner's click-through URL (not applicable to CODE type)

targetTemplateName string

Target template name for template-based banners, up to 50 characters

thirdTrackingCode object

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

Title text for native banners

universalAdIdRegistry string

Registry of the video creative's Universal Ad ID (VAST UniversalAdId idRegistry); empty with a code set means ad-id.org

universalAdIdValue string

ISCI / Ad-ID code of the video creative, sent as the VAST UniversalAdId; an empty string clears it

url string

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

Use placement size instead of banner size

vast40WrapperAllowMultipleAds boolean

VAST 4.0: allow multiple ads in response

vast40WrapperFallbackOnNoAds boolean

VAST 4.0: fallback when no ads available

vast40WrapperFollowAdditionalWrappers boolean

VAST 4.0: follow additional wrapper redirects

vastTagUrl string

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

Video file URL of an EXTERNAL_VIDEO banner

videoFileName string

Video file name

videoFileUrl string

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

Native video height in pixels

videoUrl string

External URL to native video; an empty value removes it, omitted keeps it

videoWidth integer

Native video width in pixels

weight integer

Banner weight for rotation (higher weight = more impressions), 1 to 32767

placementType string

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

Conditionally required — when bannerType is TEMPLATE. Template ID

vpaidFrameworkId integer

Conditionally required — when bannerType is VPAID_FRAMEWORK. VPAID framework ID

selfServeCampaignType string

Self-Serve campaign type; if set, banner is created from a prototype. Accepts enum name or integer ID for backward compatibility

linkToPlacements boolean

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

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

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

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

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.