Skip to main content
The Ad Unit API lets you create and manage ad units from your server. Units you create with the API appear in the console right away. You use unit IDs for SDK integration and in the creative sets of the Ad Product API. The API works on the same data as ad units in the console. You can also read and update units created in the console.

Prerequisites

  • You need an API key with the ad-unit:read and ad-unit:write scopes. You can’t select these scopes in [Settings] > [Integrations] in the console. Ask Adrop, and we’ll issue you a key with the scopes. You can get the App API and Ad Product API scopes on the same key.
  • The two scopes are checked separately. A key with only ad-unit:write gets 403 on read (GET) requests. Create and update responses include the full unit, but you also need ad-unit:read to read units separately.
  • Look up the ID of the app to create units in with the App API.
Call the API from your server only. Don’t put API keys in apps or web pages.

Basics

When you get 429, wait for the number of seconds in the Retry-After header, then send the request again. When the server is busy, you can get 429 even if you send requests one at a time.

Endpoints

Paths are relative to the Base URL.

Create a Unit

Creates an ad unit.

Request

Requires the ad-unit:write scope.

Request Body

  • Omitted values are filled with the same per-format defaults as the unit creation screen in the console.
  • If you turn on a setting and don’t send the values that go with it, they get the same defaults as in the console. For example, if you turn on carouselActivated, carouselShowIndicator and carouselRollingInterval are filled with their defaults.
  • You can create only banner and native units in web apps.
  • Response-only fields (_id, connected, archived, createdAt, updatedAt) and fields not listed here return 400 VALIDATION_FAILED.

Request Example

Response Example

Returns 201 with the new unit as a unit object.
Create requests aren’t idempotent. If you resend a request because you didn’t get a response, the unit can be created twice. Before resending, check the unit list to see whether the unit was created.

Errors

  • 400 AD_UNIT_VALIDATION_FAILED: The request breaks a unit rule, such as the size, the range of a format setting, or a condition between settings.
  • 400 AD_UNIT_NATIVE_SLOTS_NOT_ACCEPTABLE: nativeSlots doesn’t follow the rules.
  • 404 PROJECT_APP_NOT_FOUND: app isn’t an app in this project.

Unit Object

The get, create, and update endpoints return units in this format. Settings that aren’t stored aren’t filled with defaults in features.

Formats and Sizes

Set format to one of these values exactly, including case.
  • Banners, native units, and popups can also use a custom size instead of a preset. Width and height are each an integer from 1 to 10,000, and popups must have a width-to-height ratio from 2:3 to 3:2.
  • If you use a video size (320x180 or 180x320), set video.dimensions to the matching ratio (16:9 or 9:16).
  • Rewarded unit creatives are always 9:16 videos.
For what each format offers, see Ad Unit Formats.

Format Settings

features can include only the settings the format uses. Settings for other formats return 400. Send numbers as JSON numbers (strings such as "1000" aren’t accepted). Time values are in milliseconds.

All Formats

Video settings (videoSupported, videoController, and videoSkipDelayMs) are always off for interstitial, rewarded, and splash units.

Native

Interstitial

Splash

Rewarded units use only the settings common to all formats.

Setting Conditions

  • Template only (useTemplate) is available only for banners that use a preset size and have no video.
  • You can turn on canSupportThemeDark only for banners with Template only turned off, native units with an image or video, popups, and splash units.
  • For native units with no image or video, you can’t turn on Show AD Mark (useWatermark), CTA Button, or Accept Video Creatives.
  • Ranges are checked only when the related setting is on. For example, carouselRollingInterval is checked when carouselActivated is on.

Native Texts and Media

  • Each nativeTexts item has id (lowercase letters, digits, and _), label, maxLength (maximum number of characters, greater than 0), and optional (whether the item is optional). You can add up to 50 items.
  • headline (ad headline) and body (ad description) can only be in the first or second position of nativeTexts.
  • Each nativeSlots item has id, label (optional), w, and h. You can use nativeSlots only for native units with an image or video. The first media item must have the id m1 and the same size as the unit’s size. You can add up to 3 items. If there’s only one media item, it’s stored as [].
  • IDs must be unique across nativeTexts and nativeSlots combined.
If nativeSlots breaks these rules, the API returns 400 AD_UNIT_NATIVE_SLOTS_NOT_ACCEPTABLE with the reason in detail.reason. For multiple media items, see Native Multi-Media.

List Units

Returns the project’s units, newest first, one page at a time. Deleted units are excluded by default.

Request

Requires the ad-unit:read scope.

Query Parameters

Request Example

Response Example

Returns 200 with items (the units) and next (the cursor for the next page). If there’s no next, this is the last page.
The order is mostly newest first, but older units may be out of order. Don’t rely on the order. Use next to read the following pages.

Get a Unit

Returns one unit. You can also get a deleted unit by ID. In that case, archived is true.

Request

Requires the ad-unit:read scope.

Request Example

Response

Returns 200 with a unit object.

Errors

  • 404 AD_UNIT_NOT_FOUND: The unit doesn’t exist or belongs to another project.

Update a Unit

Changes only the fields you send.

Request

Requires the ad-unit:write scope. The request body takes the same fields as when you create a unit, except app. You can’t change a unit’s app.

Query Parameters

How Updates Work

  • Fields you don’t send stay as they are. An empty body {} changes nothing.
  • In features, only the settings you send change. Other settings stay as they are. However, when you turn carouselActivated, videoSupported, or videoController on or off, dependent settings you don’t send (carouselShowIndicator, carouselRollingInterval, videoController, videoSkipDelayMs) change to their defaults when turned on and to their off values when turned off.
  • You can send null only for desc (clears the description), size (changes the unit to a native unit with no image or video), video (clears the video size), and features.carouselCountLimit (turns off the popup carousel count limit).
  • When you change the format and the current size isn’t a preset of the new format, you must also send size. Settings the new format doesn’t use are removed, and the new format’s settings are filled with defaults.
  • You can’t update deleted units (409 AD_UNIT_ARCHIVED).

Locked Fields

For units that have received ad requests from the SDK (connected: true) and units in an ad product’s creative set, you can’t change format, size, video, or the id of nativeSlots items (409 AD_UNIT_FIELD_LOCKED). You can change the name, description, and other settings.

Impact on Ad Products

If you change useTemplate, useWatermark, or features of a unit in an ad product, the unit may no longer match its creative set. The unit then gets the Needs Modification status (fixRequired) in that product, and ads aren’t served to it. For details, see Creative Sets in the Ad Product API. If too many products use the unit to reconcile them all at once, the API returns 409 AD_UNIT_RECONCILE_LIMIT_EXCEEDED and changes nothing. detail.limit holds the name of the limit that was hit, and detail.max holds its value.
If you take a get response, remove the response-only fields (_id, app, connected, archived, createdAt, updatedAt), and send the rest as is, nothing changes. Units created in the console long ago may store the numbers in features as strings (for example, "1000"). Convert them to numbers before you send them back.

Request Example

Response

Returns 200 with the updated unit object.

Errors

  • 404 AD_UNIT_NOT_FOUND: The unit doesn’t exist or belongs to another project.
  • 409 AD_UNIT_ARCHIVED: The unit has been deleted.
  • 409 AD_UNIT_CONFLICT: ifUpdatedAt differs from the unit’s updatedAt. Get the unit again, then update it.
  • 409 AD_UNIT_FIELD_LOCKED: You tried to change a locked field.
  • 409 AD_UNIT_RECONCILE_LIMIT_EXCEEDED: Too many products use this unit.

Delete a Unit

Deletes a unit. You can’t restore a deleted unit.

Request

Requires the ad-unit:write scope.

Request Example

Response Example

Returns 200 with the unit ID.
  • Deleted units no longer appear in the list, but you can still get them by ID (archived: true). Deleting a unit that’s already deleted also returns 200.
  • A deleted unit is removed from the creative sets of every ad product that uses it. Creative sets left empty are removed too, so a product can end up with no units.
Before you delete a unit, check with the Ad Product API whether any products use it. The product list doesn’t include unit IDs, so get each product and check unitGroups[].units.

Errors

  • 404 AD_UNIT_NOT_FOUND: The unit doesn’t exist or belongs to another project.
  • 409 AD_UNIT_RECONCILE_LIMIT_EXCEEDED: Too many products use this unit. Remove the unit from the products first.

Error Handling

Error Response

Error responses include statusCode. Errors whose errorCode in the table below isn’t - also include errorCode. Errors that point to a problem in the request also include detail. Handle errors by errorCode, or by statusCode when there’s no errorCode.
In detail.errors[], path is the location of the invalid field, and value is the value you sent. detail.errors holds up to 100 errors. Request format errors (VALIDATION_FAILED) also include the message and error fields. Errors in features are combined into one line in message, so check detail.errors[] for the error on each setting.

Error Codes

Retrying

  • If a write request (POST, PATCH, or DELETE) gets 502 or the connection drops without a response, the request may have been applied. Get the unit to check before resending. Create requests aren’t idempotent, so resending one as is can create a duplicate unit.
  • When you resend an update with ifUpdatedAt, you can get 409 AD_UNIT_CONFLICT if the earlier request was applied. Get the unit again to check.

Limits