/

Browse the help center

Create or update application placement

Creates a new application placement or updates an existing one.

Reference

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

Creates a new application placement or updates an existing one. Application placements are designed for in-app ad serving on iOS and Android platforms with configurable ad categories (BANNER or INTERSTITIAL) and operating system targeting. If an ID is provided, the existing placement is updated; otherwise a new APPLICATION_PLACEMENT is created under the specified zone. 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. Parameters that were sent but not applied are listed in 'ignoredFields', each with its reason in 'ignoredFieldReasons'.

Form Params

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

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

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

401

Authentication error

403

Forbidden — insufficient permissions

Language

cURL Request

curl --request POST \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/placements/update/app.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 'adCategory=BANNER'

Python Request

import requests

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

Node Request

const response = await fetch('https://YOUR-NETWORK-DOMAIN/rest-api/placements/update/app.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","adCategory":"BANNER"}),
});

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/app.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&adCategory=BANNER"))
    .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/app.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", ["adCategory"] = "BANNER" });

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/app.do", strings.NewReader(`id=4001&zoneId=3001&name=Homepage%20Leaderboard%20728x90&active=true&adCategory=BANNER`))
	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/app.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&adCategory=BANNER');

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

Ruby Request

require 'net/http'
require 'json'

uri = URI("https://YOUR-NETWORK-DOMAIN/rest-api/placements/update/app.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", 'adCategory' => "BANNER")

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