You can view and manage MAX ad units by sending requests to the Ad Unit Management API.
There are five endpoints in this API:
- The
/ad_unit endpoint:
- Make a
GET request to /ad_unit/«ad-unit-ID» to view details about a particular ad unit.
- Make a
POST request to /ad_unit/ to create a new ad unit.
- Make a
POST request to /ad_unit/«ad-unit-ID» to manage the ad network configurations of an ad unit.
- Make a
GET request to /ad_unit/«ad-unit-ID»/«segment-ID» to get the waterfall for a segment for an ad unit.
- Make a
POST request to /ad_unit/«ad-unit-ID»/«segment-ID» to create, edit, deprecate, promote, or remove a waterfall for a segment for an ad unit.
- The
/ad_units endpoint
- Make a
GET request to /ad_units to view details about all your ad units.
- The
/ad_unit_experiment endpoint
- Make a
GET request to /ad_unit_experiment/«ad-unit-ID» to view details about an ad unit experiment.
- Make a
POST request to /ad_unit_experiment/«ad-unit-ID» to create a new ad unit experiment if the ad unit does not have an active one.
- Make a
POST request to /ad_unit_experiment/«ad-unit-ID» to promote or deprecate an ad unit experiment.
- Make a
GET request to /ad_unit_experiment/«ad-unit-ID»/«segment_id» to get the waterfall for a segment for an ad unit experiment.
- Make a
POST request to /ad_unit_experiment/«ad-unit-ID»/«segment_id» to create, edit, deprecate, promote, or remove a waterfall for a segment for an ad unit experiment.
- The
/test_device endpoint
- Make a
POST request to /test_device to create a new test device.
- Make a
GET request to /test_device/«test-device-ID» to view details about a particular test device.
- Make a
POST request to /test_device/«test-device-ID» to manage the configurations of a test device.
- The
/test_devices endpoint
- Make a
GET request to /test_devices to view details about all your test devices.
The following sections of this page explain these endpoints in greater detail.
The /ad_unit endpoint
To create an ad unit, make a POST request to this endpoint.
Include the required fields in the request body, which this page describes below.
You can create only a single ad unit per request.
Target URL
POST
Request body
Response body
Table of request/response body fields
| Name | Description | Example | Required on creation (POST) |
|---|
ad_format | The format of the ad unit. | INTER, BANNER, REWARD | true |
disabled | Whether or not this ad unit is disabled (read-only). | false | false |
has_active_experiment | Whether or not this ad unit has an active experiment (read-only). | false | false |
id | The ad unit ID. Do not include this when you create an ad unit. This is returned in the response to a creation request. | 1234567890abcdef | false |
name | The name of the ad unit. | "Mr. Bullet Rewarded" | true |
package_name | The package name / bundle ID of the app associated with this ad unit. | com.my.test.app | true |
platform | The platform of the ad unit. | ios, android | true |
template_size | The native ad template. Native ad units only. | small_template_1, medium_template_1, custom_template_1 | true |
The /ad_unit/«ad-unit-ID» endpoint
Use this endpoint to view (GET) or edit (POST) an ad unit configuration.
(To create, update, promote, or disable ad unit experiments, see the /ad_unit_experiment/ endpoint, described below.)
MAX uses the CPM values that you set here to define your waterfall.
If you configure your account and the particular ad network to use Auto-CPM, then the values that you set here are default CPM values that apply only until Auto-CPM learns new values.
To get a more detailed view of your ad unit, include the query parameter fields.
Set its value to a comma-delimited list of values that name any more fields you would like to see.
Possible fields include ad_network_settings (active only), disabled_ad_network_settings (disabled only), frequency_capping_settings, bid_floors, segments, banner_refresh_settings, and mrec_refresh_settings.
See the descriptions below of the objects that correspond to these fields values.
Target URL
Examples
GET
Response body
POST
Request body
Response
The response returns all ad unit details.
The ad_network_settings array
The ad_network_settings array contains one Ad Network Object per configured ad network.
The Network API Name (for example, FACEBOOK_NETWORK) is the key for each Ad Network Object.
Each ad network requires certain fields.
See the ad network object table below, and the tables that follow it, to learn the meaning of these fields.
Consult the ad networks table for network-specific instructions on how to set the Network API Name object key and certain of the fields.
The ad network object
| Name | Description | Example |
|---|
ad_network_ad_units | A list of objects that describe specific ad network ad units. Required by some ad networks. | See the ad_network_ad_units object. |
ad_network_app_id | The Network App ID. Some networks do not have a value for this. Required by some ad networks. See the ad networks table. | ca-app-pub-3555987499620362~3024971981 |
ad_network_app_key | The Network App Key. Some networks do not have a value for this. Required by some ad networks. See the ad networks table. | 123456789 |
bid_floors | An Object that describes the CPM floors for this ad unit. See the bid_floors object. | Optional. |
|
The ad_network_ad_units object
Changes that you make to a particular ad network do not affect the configuration of other ad networks.
You do not need to make a request that includes all ad networks if you are only updating one of them.
To change one part of a particular ad network configuration, you must include all of the information associated with the MAX ad unit for that ad network.
To add a new ad unit to an existing ad network, include all other ad unit for that ad network in the request.
If you mark all ad units as disabled for an ad network, you disable that ad network.
| Name | Description | Example |
|---|
ad_network_ad_unit_id (required) | The ID of this ad network ad unit. Some networks do not have a value for this and may return “N/A”. See the Ad Networks table below | ca-app-pub-3555987499620362/4382996128 |
cpm (required, except for bidding networks) | The CPM that will be paid for each impression of this ad unit. | 20.00 |
countries (required) | An object that describes any country-whitelisting/blacklisting for this particular ad network ad unit. | See the countries object. |
disabled (optional) | Indicates if this ad network ad unit is active. | false |
The countries object
This object defines which countries are included or excluded from an ad_network_ad_unit.
| Name | Description | Example | Required |
|---|
type | Indicates whether to whitelist or blacklist these countries. | INCLUDE, EXCLUDE | true |
values | A list of two-letter ISO country codes. An empty list means all countries, regardless of whether type is INCLUDE or EXCLUDE. | ["us", "ca", "jp"] | true |
The frequency_capping_settings object
The two styles of frequency cap are session-based and time-based.
For session-based frequency caps, each user will see at most that many ads in a session.
For time-based caps, users will see a set number of ads in a set time frame (which you define in minutes).
| Name | Description | Example |
|---|
countries (required) | Countries that this cap should apply to. See the countries object for a description of the fields. Frequency capping only supports type=INCLUDE. Countries in frequency_capping_objects must be disjoint. | { "type": "INCLUDE", "values": ["at", "pt", "ro", "se", "si", "sk"] } |
session_capping_settings (required if type==session) | An object that describes the maximum ads per session (session_limit) a user should see. Set session_limit=0 if type=time. | {"session_limit": 10} |
time_capping_settings (required if type=time) | An object that describes how many ads per day (day_limit) along with how many minutes between ads (minute_frequency). Set day_limit and to if =. |
The bid_floors object
This object defines any CPM bid floors that you want to associate with particular countries.
Any countries for which you do not define bid floors will have no floor.
Include the full list of floors on any update requests that include a bid_floors object.
| Name | Description | Example | Required |
|---|
countries | A list of countries to associate with this bid floor. See the countries object for the description of this object. Only type=INCLUDE is supported. | { "type": "INCLUDE", "values": ["at", "pt", "ro", "se", "si", "sk"] } | true |
country_group_name | A name that describes the country group. | "T1 EN Speaking" | true |
cpm | The minimum CPM value that ad networks must bid for each impression of this ad unit. If no ads can serve above this limit for a country in this group, MAX does not fill the ad request. | 2.00 | true |
The banner_refresh_settings object
This object defines the interval at which banner ad units should refresh and fetch a new banner ad.
If you set interval to 0, this ad unit refreshes at the MAX-defined default refresh rate.
| Name | Description | Example |
|---|
interval | The number of seconds to wait before refreshing a banner placement. Possible values are 0, 10, 15, 20, 30, 45, 60, and 300. | 10 |
The mrec_refresh_settings object
This object defines the interval at which MREC ad units should refresh and fetch a new MREC ad.
If you set interval to 0, this ad unit refreshes at the MAX-defined default refresh rate.
| Name | Description | Example |
|---|
interval | The number of seconds to wait before refreshing an MREC placement. Possible values are 0, 10, 15, 20, 30, 45, 60, and 300. | 10 |
The segment object
This object defines user segmentation targeting rules that create different ad unit waterfalls for different segments of inventory.
You can do user segmentation by ID status and device type.
See the SDK integration guides > Platform > Overview > Data and keyword passing documentation for more information.
On the main ad unit, segment objects are in a list called segments (plural).
This is a read-only list of waterfall segmentation associated with that ad unit.
When you look at a specific ad unit waterfall with segmentation defined, or when you create a new waterfall, the segment object is associated with the key segment (singular).
| Name | Description | Example |
|---|
device_type | Device type targeting. Options are "all" (default), "phones", "tablets". | "tablets" |
id | The waterfall ID associated with this segment. Don’t include this value when you create a new waterfall. | 81234 |
id_type | Device ID targeting. Options are "all" (default), "id_only", "no_id". | "no_id" |
name | The name of this waterfall. | "No-ID iPhones" |
segment_keys | An array that indicates which keys and values define the segment. | [ "+101:202" ] |
Possible errors
| Name | Description | Example |
|---|
Bad Request | HTTP Response Code | 400 |
Unauthorized | HTTP Response Code | 401 |
Forbidden | HTTP Response Code | 403 |
The /ad_units endpoint
Use this endpoint to view basic details of all active ad units.
A GET request to this endpoint returns only those ad units that are active.
This API does not allow you to disable or activate ad units.
Do that in the UI instead.
You can get a more detailed view of all active ad units if you include the query parameter fields in your request.
Set its value to a comma-delimited list of names of the fields you would like to see.
Possible fields include ad_network_settings, frequency_capping_settings, and bid_floors.
The field values that are returned when you request these other fields are the same as those in the corresponding objects that would be returned automatically if you were to request a single ad unit by using the /ad_unit/«ad-unit-ID» endpoint.
If there are too many ad units, your request to this endpoint may time out or return a 500 response code.
You can limit the number of ad units returned by adding the query parameter limit.
Set its value to an integer that indicates how many ad units the request should return.
To paginate through all ad units, add the query parameter offset.
Set its value to an integer that describes how many ad units in the total list to skip before the first result in the result set.
If this offset value is larger than the total number of ad units, the response will return an empty array.
Target URL
Examples
GET
Response body
The ad unit object
| Name | Description | Example |
|---|
ad_format | The format of the ad unit. | INTER, BANNER, REWARD |
disabled | Whether this ad unit is disabled (read-only). | false |
has_active_experiment | Whether this ad unit has an active experiment (read-only). | false |
id | The ad unit ID. | 1234567890abcdef |
name | The name of the ad unit. | "Mr. Bullet Rewarded" |
package_name | The package name / bundle ID of the app associated with this ad unit. | com.my.test.app |
platform | The platform of the ad unit. | ios, android |
Possible errors
| Name | Description | Example |
|---|
Bad Request | HTTP Response Code | 400 |
Unauthorized | HTTP Response Code | 401 |
Forbidden | HTTP Response Code | 403 |
The /ad_unit_experiment/«ad-unit-ID» endpoint
Use this endpoint to create, view, edit, promote, or deprecate ad unit experiments.
To get a more detailed view of all ad unit experiments, include the query parameter fields in your request.
Set its value to a comma-separated list of field names whose values you would like to see.
Possible fields include ad_network_settings, frequency_capping_settings, and bid_floors.
See the descriptions above of the objects that correspond to these fields values.
Target URL
Examples
GET
Response body
POST
Create experiment request body
When you make a request to this endpoint to create an experiment, exclude the id value from your request body or set that value to null.
Create experiment response body
Deprecate experiment request body
Deprecate experiment response body
Promote experiment request body
Promote experiment response body
The ad unit experiment object
| Name | Description | Example | Required |
|---|
ad_network_settings | Ad network configuration. | See the /ad_unit/«ad-unit-ID» endpoint. | false |
bid_floors | Bid floors. | See the /ad_unit/«ad-unit-ID» endpoint. | false |
deprecate | Whether you want to deprecate this experiment. | true | false |
disabled | Whether the ad unit is disabled. | false | false (read-only) |
experiment_name | The name of the ad unit experiment. | "aggressive_freq_caps" | true on Create and Edit, false on Promote and Deprecate |
frequency_capping_settings | Frequency cap settings. | See the /ad_unit/«ad-unit-ID» endpoint. | false |
id | The ad unit ID (Same as parent ad unit ID). | "e74c3b7797b0ce7a" | true on Edit, Promote, or Deprecate; false on Create (must be missing or empty) |
promote | Whether you want to promote this experiment. | true | false |
test_group_allocation | Percentage of users that are part of this test. Possible values are: 50, 25, 10, and 5. | 25 | false |
Possible errors
| Name | Description | Example |
|---|
Bad Request | HTTP Response Code | 400 |
Unauthorized | HTTP Response Code | 401 |
Forbidden | HTTP Response Code | 403 |
The /test_device endpoint
To create a test device, make a POST request to this endpoint.
Include the required fields in the request body, which this page describes below.
You can create only a single test device per request.
Target URL
Example
Request body
Response body
Table of request/response body fields
| Name | Description | Example | Required on creation (POST) |
|---|
device_id | The IDFA of the test device. | "2fc1d626-22d4-4ba4-82e3-10ca1ad1abe1" | true |
disabled | Whether the status of the device is disabled. | false | true |
name | The name of the test device. | "My Test Device" | true |
network | Network for which the device ID is enabled for test mode. | APPLOVIN_NETWORK | true |
The /test_device/«test-device-ID» endpoint
Use this endpoint to view (GET) or edit (POST) a test device configuration.
Target URL
Example
Target URL
GET
Response body
POST
Request body
Response body
This JSON object is the same as those returned by the /test_device endpoint.
The /test_devices endpoint
Use this endpoint to view basic details of all test devices in your account.
The response includes both disabled and enabled test devices.
Target URL
Example
Response body
These JSON objects are the same as those returned by the /test_device endpoint.
Multiple waterfalls
You can create more waterfalls for an ad unit based on user segmentation.
You can create waterfalls, edit waterfalls, and create/edit/deprecate/promote waterfall experiments by using a similar structure to that described for the other requests documented on this page.
To specify the segment that you want to apply the request to, append /«segment-ID» to the end of the endpoint, where «segment-ID» is the id value from the segment object in the ad unit response.
New segments start with the same waterfall as the default waterfall configured for the ad unit.
See the segment object for more details on how you define user segmentation.
Examples
GET
Get the waterfall for segment ID 213 for ad unit 1234567890abcdef:
Get the experiment waterfall for segment ID 213 for ad unit 1234567890abcdef:
POST
Create a new waterfall for No-ID iPhone users for ad unit 1234567890abcdef:
Remove the waterfall for segment ID 213 for ad unit 1234567890abcdef (set disabled to true):
Ad networks
This table provides the mapping between the names that the Ad Unit API uses for an ad network and app identifiers to the names used in each ad network.
If a network has an ad_network_app_id (ID) or ad_network_app_key (Key) value listed here, that value is required when you issue a request to update an ad_network_settings object.
If a network does not have a value listed here for those fields, no value is required.
| Network | Network API name | ID | Key | Ad unit ID |
|---|
| AdMob | ADMOB_NETWORK | Google App ID | ⸺ | Ad Unit ID |
| AdMob Native | ADMOB_NATIVE_NETWORK | Google App ID | ⸺ | Ad Unit ID |
| BidMachine Bidding | BIDMACHINE_BIDDING | Source ID | ⸺ | ⸺ |
| BIGO Ads Bidding | BIGO_BIDDING | App ID | ⸺ | Slot ID |
| Chartboost | CHARTBOOST_NETWORK | App ID | App Signature | Ad Location |
| Chartboost Bidding | CHARTBOOST_BIDDING | App ID | App Signature | Ad Location |
| CSJ | CSJ_NETWORK | App ID | ⸺ | Slot ID |
| DT Exchange | FYBER_NETWORK | App ID | ⸺ | Spot ID |
| DT Exchange Bidding | FYBER_BIDDING | App ID | ⸺ | Placement ID |
| Google Ad Manager | GOOGLE_AD_MANAGER_NETWORK | ⸺ | ⸺ | Placement ID |
| Google Ad Manager Native | GOOGLE_AD_MANAGER_NATIVE_NETWORK | ⸺ | ⸺ | Placement ID |
| Google Bidding | ADMOB_BIDDING |
1 Mintegral Bidding can include another Placement ID.
The API handles this in the object called extraParameters in the top level object.
The extraParameters object has a field called ad_network_optional_placement_id that takes this Placement ID value.
See the example below:
| Indicates whether this network is disabled in this ad unit. Optional. |
frequency_cap_settings | Deprecated. | |
minute_frequency
0
type
session
{"day_limit": 10, "minute_frequency": 10} |
type (required) | The type of frequency cap to use. | time, session |
| HyprMX | HYPRMX_NETWORK | Distributor ID | ⸺ | Placement Name |
| InMobi | INMOBI_NETWORK | Account ID | ⸺ | Placement ID |
| InMobi Bidding | INMOBI_BIDDING | Account ID | ⸺ | Placement ID |
| ironSource | IRONSOURCE_NETWORK | App Key | ⸺ | Instance ID |
| ironSource Bidding | IRONSOURCE_BIDDING | App Key | ⸺ | Instance ID |
| Liftoff Monetize | VUNGLE_NETWORK | App ID | ⸺ | Placement Reference ID |
| Liftoff Monetize Bidding | VUNGLE_BIDDING | App ID | ⸺ | Placement Reference ID |
| LINE | LINE_NETWORK | App ID | ⸺ | Slot ID |
| LINE Ads Network | LINE_BIDDING | App ID | ⸺ | Slot ID |
| LINE Native | LINE_NATIVE_NETWORK | App ID | ⸺ | Slot ID |
| Maio | MAIO_NETWORK | Media ID | ⸺ | Zone ID |
| Meta Audience Network Bidding | FACEBOOK_NETWORK | ⸺ | ⸺ | Placement ID |
| Meta Audience Network Native Bidding | FACEBOOK_NATIVE_BIDDING | ⸺ | ⸺ | Placement ID |
| Mintegral Bidding1 | MINTEGRAL_BIDDING | App ID | App Key | Ad Unit ID |
| Mintegral Native Bidding1 | MINTEGRAL_NATIVE_BIDDING | App ID | App Key | Ad Unit ID |
| MobileFuse Bidding | MOBILEFUSE_BIDDING | ⸺ | ⸺ | Placement ID |
| MobileFuse Native Bidding | MOBILEFUSE_NATIVE_BIDDING | ⸺ | ⸺ | Placement ID |
| Moloco Bidding | MOLOCO_BIDDING | ⸺ | App Key | Ad Unit ID |
| Ogury | OGURY_PRESAGE_NETWORK | Asset Key | ⸺ | Ad Unit ID |
| Ogury Bidding | OGURY_PRESAGE_BIDDING | Asset Key | ⸺ | Ad Unit ID |
| Pangle | TIKTOK_NETWORK | App ID | ⸺ | Slot ID |
| Pangle Bidding | TIKTOK_BIDDING | App ID | ⸺ | Slot ID |
| Pangle Native | TIKTOK_NATIVE_NETWORK | App ID | ⸺ | Slot ID |
| Pangle Native Bidding | TIKTOK_NATIVE_BIDDING | App ID | ⸺ | Slot ID |
| PubMatic Bidding | PUBMATIC_BIDDING | Publisher ID | Profile ID | Ad Unit ID |
| Smaato | SMAATO_NETWORK | Publisher ID | ⸺ | Ad Space ID |
| Smaato Bidding | SMAATO_BIDDING | Publisher ID | ⸺ | Ad Space ID |
| Smaato Native Bidding | SMAATO_NATIVE_BIDDING | Publisher ID | ⸺ | Ad Space ID |
| Tencent | TENCENT_NETWORK | App ID | ⸺ | Ad Slot ID |
| Unity Bidding | UNITY_BIDDING | Game ID | ⸺ | Placement ID |
| Verve Group Bidding | VERVE_BIDDING | App Token | ⸺ | Zone Reference |
| VK Ad Network | MYTARGET_NETWORK | ⸺ | ⸺ | Placement ID |
| VK Ad Network Bidding | MYTARGET_BIDDING | ⸺ | ⸺ | Placement ID |
| VK Ad Network Native Bidding | MYTARGET_NATIVE_BIDDING | ⸺ | ⸺ | Placement ID |
| Yandex | YANDEX_NETWORK | ⸺ | ⸺ | Block ID |
| Yandex Bidding | YANDEX_BIDDING | ⸺ | ⸺ | Block ID |
| YSO Network Bidding | YSO_BIDDING | ⸺ | ⸺ | Key |
This API is rate-limited to 2000 requests per hour.
You must authenticate each API request.
To do so, add an Api-Key HTTP header to your request and set its value to your account’s Management Key.
You can find your Management Key in your AppLovin dashboard under Account > General > Keys.
You cannot use this endpoint to create more ad units for apps/platforms/ad formats combinations that already have an active ad unit.
To create more ad units in such a case, use the UI instead.
A POST request to this endpoint only applies changes to those fields that are present in your request.
If any fields are missing in your request, the values corresponding to those missing fields in your ad unit will remain unchanged.
After you define a segment for a waterfall, you cannot update the segmentation.
If that targeting is incorrect, delete the waterfall and then create a new one with corrected targeting.
The segment object is ignored in POST requests except when you make a new waterfall.
A POST request to this endpoint only applies changes to those fields that are present in your request.
If any fields are missing in your request, the values corresponding to those missing fields in your ad unit remain the same as those in the parent ad unit.
For example, if you only define the experiment_name value, the ad unit experiment will otherwise be a precise copy of the parent ad unit.
When you make a request to this endpoint to deprecate an experiment, any updates you simultaneously attempt to make to the ad unit settings are ignored; they are not applied.
When you make a request to this endpoint to promote an experiment, any updates you simultaneously attempt to make to the ad unit settings are ignored; they are not applied.
You cannot use this endpoint to create more test device IDs for device IDs already registered as a test device.
Instead, you can use POST requests to /test_device/«test-device-ID» to disable or change the network for the device ID with the same request body, by sending different values for the disabled or network field.
