Prerequisites
- You need an API key with the
ad-unit:readandad-unit:writescopes. 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:writegets403on read (GET) requests. Create and update responses include the full unit, but you also needad-unit:readto read units separately. - Look up the ID of the app to create units in with the App API.
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
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,carouselShowIndicatorandcarouselRollingIntervalare 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 return400 VALIDATION_FAILED.
Request Example
Response Example
Returns201 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:nativeSlotsdoesn’t follow the rules.404 PROJECT_APP_NOT_FOUND:appisn’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
Setformat 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.dimensionsto the matching ratio (16:9or9:16). - Rewarded unit creatives are always 9:16 videos.
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.
Banner
Native
Popup (Bottom and Center)
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
canSupportThemeDarkonly 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,
carouselRollingIntervalis checked whencarouselActivatedis on.
Native Texts and Media
- Each
nativeTextsitem hasid(lowercase letters, digits, and_),label,maxLength(maximum number of characters, greater than 0), andoptional(whether the item is optional). You can add up to 50 items. headline(ad headline) andbody(ad description) can only be in the first or second position ofnativeTexts.- Each
nativeSlotsitem hasid,label(optional),w, andh. You can usenativeSlotsonly for native units with an image or video. The first media item must have theidm1and the same size as the unit’ssize. You can add up to 3 items. If there’s only one media item, it’s stored as[]. - IDs must be unique across
nativeTextsandnativeSlotscombined.
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
ad-unit:read scope.
Query Parameters
Request Example
Response Example
Returns200 with items (the units) and next (the cursor for the next page). If there’s no next, this is the last page.
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
ad-unit:read scope.
Request Example
Response
Returns200 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
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 turncarouselActivated,videoSupported, orvideoControlleron 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
nullonly fordesc(clears the description),size(changes the unit to a native unit with no image or video),video(clears the video size), andfeatures.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 changeuseTemplate, 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.
Request Example
Response
Returns200 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:ifUpdatedAtdiffers from the unit’supdatedAt. 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
ad-unit:write scope.
Request Example
Response Example
Returns200 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 returns200. - 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.
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 includestatusCode. 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.
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, orDELETE) gets502or 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 get409 AD_UNIT_CONFLICTif the earlier request was applied. Get the unit again to check.