Ad Unit Management API

You can view and manage MAX ad units by sending requests to the Ad Unit Management API.

Note

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.

There are five endpoints in this API:

1. 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.
2. The /ad_units endpoint
   • Make a GET request to /ad_units to view details about all of your ad units.
3. 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 currently 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.
4. 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.
5. The /test_devices endpoint
   • Make a GET request to /test_devices to view details about all of your test devices.

See also

“Automate Your Monetization With MAX’s New Ad Unit Management API” from AppLovin’s Blog.

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 are described below. You can create only a single ad unit per request.

Note

You cannot use this endpoint to create additional ad units for apps/platforms/ad formats combinations that already have an active ad unit. To create additional ad units in such a case, use the UI instead.

Target URL

https://o.applovin.com/mediation/v1/ad_unit

POST

Request Body

{
  "name": "My Inter Ad Unit",
  "platform": "ios",
  "package_name": "com.test.app",
  "ad_format": "INTER"
}

Response Body

{
  "id": "1234567890abcdef",
  "name": "My Inter Ad Unit",
  "platform": "ios",
  "package_name": "com.test.app",
  "ad_format": "INTER",
  "has_active_experiment": false,
  "disabled": false
}

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. However, 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 additional 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.

Note

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.

Target URL

https://o.applovin.com/mediation/v1/ad_unit/«ad-unit-ID»?fields=ad_network_settings,disabled_ad_network_settings,frequency_capping_settings,bid_floors,banner_refresh_settings,segments

Examples

GET

Response Body

{
  "id": "1234567890abcdef",
  "name": "My Inter Ad Unit",
  "platform": "ios",
  "package_name": "com.test.app",
  "ad_format": "INTER",
  "has_active_experiment": false,
  "disabled": false,
  "ad_network_settings": [
    {
      "FACEBOOK_NETWORK": {
        "disabled": false,
        "ad_network_ad_units": [
           {
             "ad_network_ad_unit_id": "8247030622430922_5618972399256249",
             "disabled": false
           }
        ]
      }
    },
    {
      "ADMOB_NETWORK": {
        "disabled": false,
        "ad_network_app_id": "ca-app-pub-3555987499620362~3024971981",
        "ad_network_ad_units": [
          {
            "ad_network_ad_unit_id": "ca-app-pub-3555987499620362/4382996128",
            "disabled": false,
            "cpm": "30.00",
            "countries": {
              "type": "INCLUDE",
              "values": [
                "us",
                "ca",
                "gb",
                "au"
              ]
            }
          },
          {
            "ad_network_ad_unit_id": "ca-app-pub-3555987499620362/5476585941",
            "disabled": false,
            "cpm": "20.00",
            "countries": {
              "type": "EXCLUDE",
              "values": [
                "us",
                "ca",
                "gb",
                "au"
              ]
            }
          }
        ]
      }
    }
  ],
  "frequency_capping_settings": [
    {
      "type": "time",
      "time_capping_settings": {
        "day_limit": 10,
        "minute_frequency": 10
      },
      "session_capping_settings": {
        "session_limit": 0
      },
      "countries" : {
        "type": "INCLUDE",
        "values" : [
          "ca",
          "us"
        ]
      }
    }
  ],
  "bid_floors": [
    {
      "country_group_name": "t1 eng",
      "cpm": "10.00",
      "countries": {
        "type": "INCLUDE",
        "values": [
          "au",
          "ca",
          "gb",
          "nz",
          "us"
        ]
      }
    },
    {
      "country_group_name": "eea",
      "cpm": "5.00",
      "countries": {
        "type": "INCLUDE",
        "values": [
          "at",
          "pt",
          "ro",
          "se",
          "si",
          "sk"
        ]
      }
    }
  ],
  "banner_refresh_settings":{
    "interval": 0
  },
  "segments":[
    {
      "id": 347324,
      "name": "LAT iPads",
      "id_type": "no_id",
      "device_type": "tablets",
      "genders": [],
      "ages": {},
      "keywords": []
    },
    {
      "id": 347341,
      "name": "Senior Men",
      "id_type": "all",
      "device_type": "all",
      "genders": [
        "male", "unknown"
      ],
      "ages": {
        "min_age": 65,
        "max_age": 99
      },
      "keywords": []
    },
    {
      "id": 347643,
      "name": "fruit keywords",
      "id_type": "all",
      "device_type": "all",
      "genders": [],
      "ages": {},
      "keywords": [
        [
          "+fruit:apple",
          "-fruit:banana"
        ],
        [
          "+fruit:orange",
          "+fruit:lemon"
        ]
      ]
    }
  ]
}

POST

Request Body

{
  "id":"«ad-unit-ID»",
  "name":"«ad-unit-name»",
  "platform":"«ad-unit-platform»",
  "ad_format":"«ad-unit-format»",
  "package_name":"«ad-unit-package-name»",
  "ad_network_settings": [
    {
      "ADMOB_NETWORK": {
        "disabled": true,
        "ad_network_app_id": "ca-app-pub-3555987499620362~3024971981",
        "ad_network_ad_units": []
      }
    }
  ],
  "frequency_capping_settings": [
    {
      "type": "time",
      "time_capping_settings": {
        "day_limit": 10,
        "minute_frequency": 10
      },
      "session_capping_settings": {
        "session_limit": 0
      },
      "countries" : {
        "type": "INCLUDE",
        "values" : [
          "ca",
          "us"
        ]
      }
    }
  ]
}

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. Certain fields are required by each ad network. 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.
disabled	Indicates whether this network is enabled or disabled in this ad unit. Optional.	false
frequency_cap_settings	Deprecated.
frequency_capping_settings	A list of objects that describe how to frequency cap this ad unit. Optional.	See The frequency_capping_settings Object.

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 a given 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 a given ad_network_ad_unit.

Name	Description	Example	Required
type	Indicates whether these countries should be whitelisted or blacklisted.	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

There are two styles of frequency cap: 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 within 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 currently 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 minute_frequency to 0 if type=session.	{"day_limit": 10, "minute_frequency": 10}
type (required)	The type of frequency cap to use.	time, session

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 here.	{ "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 used to create different ad unit waterfalls for different segments of inventory. You can do user segmentation by ID status, device type, gender, age, and keywords. The latter three of these options are based on data that the publisher defines. See the SDK Integration Guides > Platform > Overview > Data and Keyword Passing documentation for more information.

On the main ad unit, segment objects are contained 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).

Note

Once 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.

Name	Description	Example
ages	An object describing the age range to target via parameters min_age and max_age. The lowest age accepted is 17 and the highest is 99.	{"min_age": 35, "max_age": 50}
device_type	Device type targeting. Options are "all" (default), "phones", "tablets".	"tablets"
genders	A list of genders to target. Options are "male", "female", "unknown". Passing all options is equivalent to passing an empty list, and an empty list will be returned.	["male","unknown"]
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"
keywords	A list of keyword lists. Items within a sub-list must all be present to match, but any sub-list that matches will result in this waterfall being eligible.	[ ["+fruit:apple","-fruit:banana"], ["+fruit:orange","+fruit:lemon"] ]
name	The name of this waterfall.	"No-ID iPhones"

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 additional 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 additional 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 should be skipped 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

https://o.applovin.com/mediation/v1/ad_units

Examples

GET

Response Body

[
  {
    "name": "My Inter Ad Unit",
    "platform": "ios",
    "package_name": "com.test.app",
    "ad_format": "INTER",
    "ad_unit_id": "45de6aa565cf865f",
    "has_active_experiment": false,
    "disabled": false
  },
  {
    "name": "My Rewarded Ad Unit",
    "platform": "android",
    "package_name": "com.test.app",
    "ad_format": "REWARD",
    "ad_unit_id": "565c45df8e6aa65f",
    "has_active_experiment": false,
    "disabled": false
  }
]

The Ad Unit Object

Name	Description	Example
ad_format	The format of the ad unit.	INTER, BANNER, REWARD
ad_unit_id	The ad unit ID.	1234567890abcdef
disabled	Whether or not this ad unit is disabled (read-only).	false
has_active_experiment	Whether or not this ad unit has an active experiment (read-only).	false
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.

Note

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.

Target URL

https://o.applovin.com/mediation/v1/ad_unit_experiment/«ad-unit-ID»?fields=ad_network_settings,frequency_capping_settings,bid_floors

Examples

GET

Response Body

{
  "id": "e74c3b7797b0ce7a",
  "experiment_name": "add_admob_inter_lines",
  "platform": "ios",
  "ad_format": "INTER",
  "package_name": "com.testapp.test",
  "disabled": false,
  "promote": false,
  "deprecate": false,
  "ad_network_settings": [
    {
      "ADMOB_NETWORK": {
        "disabled": true,
        "ad_network_app_id": "ca-app-pub-3555987499620362~3024971981",
        "ad_network_ad_units": []
      }
    }
  ],
  "frequency_capping_settings": [
    {
      "type": "time",
      "time_capping_settings": {
        "day_limit": 10,
        "minute_frequency": 10
      },
      "session_capping_settings": {
        "session_limit": 0
      },
      "countries" : {
        "type": "INCLUDE",
        "values" : [
          "ca",
          "us"
        ]
      }
    }
  ],
  "bid_floors": [
    {
      "country_group_name": "t1 eng",
      "cpm": "10.00",
      "countries": {
        "type": "INCLUDE",
        "values": [
          "au",
          "ca"
        ]
      }
    }
  ]
}

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.

{
  "experiment_name": "test_adjusting_frequency_cap",
  "frequency_capping_settings": […]
}

Create Experiment Response Body

{
  "id": "e74c3b7797b0ce7a",
  "experiment_name": "test_adjusting_frequency_cap",
  "disabled": false,
  "promote": false,
  "deprecate": false,
  "ad_network_settings":[{…}], // same as parent ad unit
  "frequency_capping_settings": […],
  "bid_floors":[{…}] // same as parent ad unit
}

Deprecate Experiment Request Body

Caution

When you make a request to this endpoint to deprecate an experiment, any updates you simultaneously attempt to make to the ad unit settings will be ignored; they will not be applied.

{
  "id": "e74c3b7797b0ce7a",
  "experiment_name": "test_adjusting_frequency_cap",
  "promote": false,
  "deprecate": true
}

Deprecate Experiment Response Body

{
  "message": "Experiment successfully deprecated"
}

Promote Experiment Request Body

Caution

When you make a request to this endpoint to promote an experiment, any updates you simultaneously attempt to make to the ad unit settings will be ignored; they will not be applied.

{
  "id": "e74c3b7797b0ce7a",
  "experiment_name": "test_adjusting_frequency_cap",
  "promote": true,
  "deprecate": false
}

Promote Experiment Response Body

{
  "message": "Experiment successfully promoted"
}

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 are described below. You can create only a single test device per request.

Target URL

https://o.applovin.com/mediation/v1/test_device

Example

Request Body

{
  "name": "My Test Device",
  "device_id": "2fc1d626-22d4-4ba4-82e3-10ca1ad1abe1",
  "disabled": false,
  "network": "APPLOVIN_NETWORK"
}

Response Body

{
  "name": "My Test Device",
  "device_id": "2fc1d626-22d4-4ba4-82e3-10ca1ad1abe1",
  "disabled": false,
  "network": "APPLOVIN_NETWORK"
}

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	Status of device ID (disabled or enabled).	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

Note

You cannot use this endpoint to create additional 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.

The /test_device/«test-device-ID» Endpoint

Use this endpoint to view (GET) or edit (POST) a test device configuration.

Target URL

https://o.applovin.com/mediation/v1/test_device/«test-device-ID»

Example

Target URL

https://o.applovin.com/mediation/v1/test_device/2fc1d626-22d4-4ba4-82e3-10ca1ad1abe1

GET

Response Body

{
  "name": "My Test Device",
  "device_id": "2fc1d626-22d4-4ba4-82e3-10ca1ad1abe1",
  "disabled": false,
  "network": "APPLOVIN_NETWORK"
}

POST

Request Body

{
  "name": "My Test Device",
  "device_id": "2fc1d626-22d4-4ba4-82e3-10ca1ad1abe1",
  "disabled": true,
  "network": "FACEBOOK_NETWORK"
}

Response Body

{
  "name": "My Test Device",
  "device_id": "2fc1d626-22d4-4ba4-82e3-10ca1ad1abe1",
  "disabled": true,
  "network": "FACEBOOK_NETWORK"
}

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

https://o.applovin.com/mediation/v1/test_devices

Example

Response Body

{
  "name": "My Test Device",
  "device_id": "2fc1d626-22d4-4ba4-82e3-10ca1ad1abe1",
  "disabled": false,
  "network": "APPLOVIN_NETWORK"
},
{
  "name": "My Test Device 2",
  "device_id": "2fc1d626-22d4-4ba4-82e3-10ca1ad1abe2",
  "disabled": false,
  "network": "FACEBOOK_NETWORK"
}

These JSON objects are the same as those returned by the /test_device endpoint.

Multiple Waterfalls

You can create additional waterfalls for a given 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:

https://o.applovin.com/mediation/v1/ad_unit/1234567890abcdef/213

Get the experiment waterfall for segment ID 213 for ad unit 1234567890abcdef:

https://o.applovin.com/mediation/v1/ad_unit_experiment/1234567890abcdef/213

POST

Create a new waterfall for No-ID iPhone users for ad unit 1234567890abcdef:

https://o.applovin.com/mediation/v1/ad_unit/1234567890abcdef

{
  "id": "1234567890abcdef", // ad unit ID
  "name": "MyApp_iOS_Banners", // ad unit name
  "platform": "ios",
  "ad_format": "BANNER",
  "package_name": "com.company.myapp",
  "disabled": false,
  "segment": {
    "name": "No-ID iPhones", // waterfall name
    "id_type": "no_id",
    "device_type": "phones"
  }
}

Remove the waterfall for segment ID 213 for ad unit 1234567890abcdef (set disabled to true):

https://o.applovin.com/mediation/v1/ad_unit/1234567890abcdef/213

{
  "id": "1234567890abcdef", // ad unit ID
  "name": "MyApp_iOS_Banners", // ad unit name
  "platform": "ios",
  "ad_format": "BANNER",
  "package_name": "com.company.myapp",
  "disabled": 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 within 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
AdColony Bidding	ADCOLONY_NETWORK	App ID	⸺	Zone 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
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	Google App ID	⸺	Ad Unit ID
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 Native	LINE_NATIVE_NETWORK	App ID	⸺	Slot ID
Maio	MAIO_NETWORK	Media ID	⸺	Zone ID
Meta Audience Network	FACEBOOK_MEDIATE	⸺	⸺	Placement ID
Meta Audience Network Bidding	FACEBOOK_NETWORK	⸺	⸺	Placement ID
Meta Audience Network Native Bidding	FACEBOOK_NATIVE_BIDDING	⸺	⸺	Placement ID
Mintegral1	MINTEGRAL_NETWORK	App ID	App Key	Ad Unit 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	MOBILEFUSE_NETWORK	Publisher ID	⸺	Placement 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
Tapjoy Bidding	TAPJOY_NETWORK	SDK Key	⸺	Placement Name
Tencent	TENCENT_NETWORK	App ID	⸺	Ad Slot ID
Unity Ads	UNITY_NETWORK	Game ID	⸺	Placement 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

¹ Mintegral / Mintegral Bidding can include an additional Placement ID. This is handled in the API by means of the object called extraParameters within 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:

{
  "MINTEGRAL_NETWORK": {
    "disabled": false,
    "targets": {},
    "ad_network_ad_units": [
      {
        "ad_network_ad_unit_id": "1232524",
        "extraParameters": null,
        "disabled": false,
        "cpm": "1.23",
        "countries": {
          "type": "INCLUDE",
          "values": []
        }
      }
    ],
    "ad_network_app_id": "testappId",
    "ad_network_app_key": "testappKey",
    "extraParameters": {
      "ad_network_optional_placement_id": "1234354"
    }
  }
}