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.

“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 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 an 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

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.

This endpoint does not allow you to disable or activate Ad Units. Instead, do that in the UI.

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

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.

The countries Object

This object defines which countries are included or excluded from a given ad_network_ad_unit.

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

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.

The banner_refresh_settings Object

This object defines the interval at which banner ad units should refresh and fetch a new nanner ad. If you set interval to 0, this ad unit will refresh at the MAX-defined default refresh rate.

The mrecr_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.

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.

Possible Errors

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

Possible Errors

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"
}

Possible Errors

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

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.

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 test devices, your request to this endpoint may time out or return a 500 response code. You can limit the number of test devices returned by adding the query parameter limit and setting its value to an integer that indicates how many test devices the request should return. To paginate through all test devices, add the query parameter offset and set its value to an integer that describes how many test devices 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 test devices, the response will return an empty array.

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

{
  "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_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": []
        }
      }
    ]
  }
}