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

# Create or update native placement

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

Creates a new native placement or updates an existing one. Native placements serve native ad creatives with configurable icon, image, and video size preferences. If an ID is provided, the existing placement is updated; otherwise a new NATIVE_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. Default creative sizes are: icon 128x128, image 1200x627, video 640x480; on an update, a size that is not sent keeps its current value. Parameters that were sent but not applied are listed in 'ignoredFields', each with its reason in 'ignoredFieldReasons'.

## Form params

| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| `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 |
| `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. |

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

## Example request

```bash
curl --request POST \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/placements/update/native.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'
```

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