Ad Unit Management API

You can use the RESTful-ish Ad Unit Management API to view and manage MAX ad units.

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.

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 along with the required fields in the request body, which are described below. You can create only a single ad unit per request.

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 define 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 define 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 and set its value to a comma-delimited list of values that name the 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.

A POST request to this endpoint will only apply 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 and 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 Required
disabled Indicates whether this network is enabled or disabled in this ad unit. false false
ad_network_app_id The Network App ID. Some networks will not have a value for this. See the Ad Networks table. ca-app-pub-3555987499620362~3024971981 depends on the ad network
ad_network_app_key The Network App Key. Some networks will not have a value for this. See the Ad Networks table. 123456789 depends on the ad network
ad_network_ad_units A list of objects that describe specific ad network ad units. See The ad_network_ad_units Object. depends on the ad network
frequency_cap_settings Deprecated; use frequency_capping_settings instead.   false
frequency_capping_settings A list of objects that describe how to frequency cap this ad unit. See The frequency_capping_settings Object. false
bid_floors An Object that describes the CPM floors for this ad unit. See The bid_floors Object. See The bid_floors Object. false

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. To change one part of a particular ad network configuration requires that you include all of the information associated with the MAX ad unit for that ad network. To add a new ad network ad unit line to an existing ad network, include all other ad network ad unit lines for that ad network in the request. If you mark all ad_network_ad_units as disabled for a given ad network, you disable that ad network.

Name Description Example Required
ad_network_ad_unit_id 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 true
disabled Indicates if this ad network ad unit is active. false false
cpm The CPM that will be paid for each impression of this ad unit. 20.00 true, except for bidding networks
countries An object that describes any country-whitelisting/blacklisting for this particular ad network ad unit. See The countries object. true

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 Required
type The type of frequency cap to use. time, session true
time_capping_settings 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} true, if type==time
session_capping_settings 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} true, if type==session
countries 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"] } true

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 includes and bid_floors object.

Name Description Example Required
country_group_name A name that describes the country group. "T1 EN Speaking" true
cpm The minimum CPM that will be paid for each impression of this ad unit. If no ads can hit this limit for a country in this group, the ad request will not be filled. 2.00 true
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

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 will refresh 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, and 60. 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 will refresh 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, and 60. 10

The segment Object

This object defines user segmentation targeting rules used to create different ad unit waterfalls for different segments of inventory. This is an extension of AppLovin’s deprecated /segments endpoint, which previously allowed user segmentation only for iOS users with and without an IDFA. 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 Data and Keyword Passing in this documentation for more information.

On the main ad unit, these objects are contained in a list called segments (plural) which is a read-only list of waterfall segmentation associated with that ad unit. When looking at a specific ad unit waterfall with segmentation defined, or to create a new waterfall, the segment object is associated with the key segment (singular).

Once you define a segment for a waterfall, you cannot update the segmentation. If that targeting is incorrect, delete the waterfall and recreate a new one with corrected targeting. The segment object is ignored in POST requests except when you are making a new waterfall.

Name Description Example
id The waterfall ID associated with this segment. Don’t include this value when you create a new waterfall. 81234
name The name of this waterfall. "No-ID iPhones"
id_type Device ID targeting. Options are "all" (default), "id_only", "no_id". "no_id"
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"]
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}
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"] ]

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. Only those ad units that are active will be returned in the response to a GET request to this endpoint. 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, and 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 and setting 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 and 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
name The name of the ad unit. "Mr. Bullet Rewarded"
platform The platform of the ad unit. ios, android
package_name The package name / bundle ID of the app associated with this ad unit. com.my.test.app
ad_format The format of the ad unit. INTER, BANNER, REWARD
ad_unit_id The ad unit ID. 1234567890abcdef
has_active_experiment Whether or not this ad unit has an active experiment (read-only). false
disabled Whether or not this ad unit is disabled (read-only). false

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, and 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.

A POST request to this endpoint will only apply 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 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

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

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"
}
Name Description Example Required
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)
experiment_name The name of the ad unit experiment. "aggressive_freq_caps" true on Create and Edit, false on Promote and Deprecate
disabled Whether the ad unit is disabled. false false (read-only)
promote Whether you want to promote this experiment. true false
deprecate Whether you want to deprecate 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
ad_network_settings Ad network configuration. See the /ad_unit/ad_unit_id endpoint. false
frequency_capping_settings Frequency cap settings. See the /ad_unit/ad_unit_id endpoint. false
bid_floors Bid floors. See the /ad_unit/ad_unit_id endpoint. 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 along with 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)
name The name of the test device. "My Test Device" true
device_id The IDFA of the test device. "2fc1d626-22d4-4ba4-82e3-10ca1ad1abe1" true
disabled Status of device ID (disabled or enabled). false true
network Network for which the device ID is enabled for test mode APPLOVIN_NETWORK true

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, but 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 will include disabled & 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 or ad_network_app_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.

Account ID

Network Network API Name ad_network_app_id ad_network_app_key ad_network_ad_unit_id
* 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 that 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"
    }
  }
}
Nend integrations can include an API Key per ad_network_ad_unit. This is handled in the API by means of an object called extraParameters. See the example below:
{
  "NEND_NETWORK": {
    "disabled": false,
    "targets": {},
    "ad_network_ad_units": [
      {
        "ad_network_ad_unit_id": "819357",
        "extraParameters": {
          "apiKey": "a5c6e18661e43832b9d828c3a4af495b03fbb0ca"
        },
        "disabled": false,
        "cpm": "0.10",
        "countries": {
          "type": "INCLUDE",
          "values": []
        }
      }
    ]
  }
}
Adcolony Bidding ADCOLONY_NETWORK App ID Zone ID
AdMob ADMOB_NETWORK Google App ID Ad Unit ID
Amazon AMAZON_MARKETPLACE_NETWORK SDK Key Slot ID
BidMachine BIDMACHINE_BIDDING Source ID N/A
Chartboost CHARTBOOST_NETWORK App ID App Signature Ad Location
Criteo CRITEO_NETWORK Account ID Zone ID
DT Exchange FYBER_NETWORK App ID Spot ID
Google Ad Manager GOOGLE_AD_MANAGER_NETWORK Placement ID
HyprMX HYPRMX_NETWORK Distributor ID Placement Name
InMobi INMOBI_NETWORK Account ID Placement ID
InMobi Bidding INMOBI_BIDDING Placement ID
ironSource IRONSOURCE_NETWORK App Key Instance 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 Bidding FACEBOOK_NETWORK Placement ID
Meta Audience Network Native Bidding FACEBOOK_NATIVE_BIDDING Placement ID
Meta Audience Network FACEBOOK_MEDIATE Placement ID
Mintegral* MINTEGRAL_NETWORK App ID App Key Ad Unit ID
Mintegral Bidding* MINTEGRAL_BIDDING App ID App Key Ad Unit ID
MobileFuse MOBILEFUSE_NETWORK Publisher ID Placement ID
myTarget MYTARGET_NETWORK Slot ID
myTarget Bidding MYTARGET_BIDDING Slot ID
Nend NEND_NETWORK Spot ID
Ogury OGURY_PRESAGE_NETWORK 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
Smaato SMAATO_NETWORK Publisher ID Ad Space ID
Smaato Bidding SMAATO_BIDDING Publisher ID Ad Space ID
Tencent TENCENT_NETWORK App ID Ad Slot ID
Unity UNITY_NETWORK Game ID Placement ID
Vungle VUNGLE_NETWORK App ID Placement Reference ID
Vungle Bidding VUNGLE_BIDDING App ID Placement Reference ID
Yahoo VERIZON_NETWORK Site ID Placement ID
Yahoo Bidding VERIZON_BIDDING Site ID Placement ID
Yandex YANDEX_NETWORK Block ID