Ad Units

Set up new ad units, fetch data, update or delete existing ad units by making a request to the ad units resource.

JSON Representation

{
    "appKey": "string",
    "appName": "string",
    "dailyImpressionCap": "integer",
    "hourlyImpressionCap": "integer",
    "format": "string",
    "name": "string",
    "refreshInterval": "integer",
    "key": "string"
}

Interstitial

{
    "appKey": "string",
    "appName": "string",
    "dailyImpressionCap": "integer",
    "hourlyImpressionCap": "integer",
    "format": "string",
    "name": "string",
    "key": "string"
}

Rewarded

{
    "appKey": "string",
    "appName": "string",
    "dailyImpressionCap": "integer",
    "hourlyImpressionCap": "integer",
    "format": "string",
    "key": "string",
    "name": "string",
    "rewardCallbackUrl": "URLstring",
    "rewards": [{
        "amount": "integer",
        "currencyName": "string"
    }, {
        "amount": "integer",
        "currencyName": "string"
    }]
}

Native

{
    "appKey": "string",
    "appName": "string",
    "dailyImpressionCap": integer,
    "hourlyImpressionCap": integer,
    "format": "string",
    "key": "string",
    "name": "string",
    "native_placement": "enum",
    "native_positioning_data": "object( nativePositioning )"
}

Native Positioning

{
    "fixed": [{
        "position": integer
    }, {
        "position": integer
    }, {
        "position": integer
    }],
    "repeating": {
        "interval": integer
    }
}

Field Definitions

Name Description Required for Post (Create)
appKey Which app does this ad unit belong yes
format Supported values: “banner”, “medium_rectangle”, “fullscreen”, “native”, “rewarded_video” yes
key system generated unique id (read only) no
name name of the Ad Unit yes
weeklyImpressionCap Also known as Frequency Cap. Max weekly impressions per user 0 signifies no impression cap. no
dailyImpressionCap Also known as Frequency Cap. Max daily impressions per user 0 signifies no impression cap. no
hourlyImpressionCap Also known as Frequency Cap. Max hourly impressions per user 0 signifies no impression cap. no
nativePlacement Native placement should be “1”, “2”, “3” or “4” based on the mapping below. If nativePlacement field is passed in for non-native ad units, an error is retruned yes, if the ad format is ‘native’
nativePositioningData A JSON value used to describe how often a native ad is shown in a feed or list of various native entities (documentation). no
refreshInterval Banner and MRECT only How often (in seconds) should the ad unit refresh itself and get a new ad. Valid values: 0 or any number greater than 10. no
rewardedCallbackUrl When a rewarded video is complete, indicate the endpoint to hit to ensure the person who sees the ad is paid. no
reward The reward object (currencyName) must be set up within the Publisher UI before it can be assigned to an ad unit. No

nativePositioningData

{
    "fixed": [
        [
            {
                "position": "1"
            },
            {
                "position": "4"
            },
            {
                "position": "7"
            }
        ]
    ]
}
{
    "fixed": [
        {
            "position": "1"
        },
        {
            "position": "4"
        },
        {
            "position": "7"
        }
    ],
    "repeating": {
        "interval": 4
    }
}

Reward JSON

{
    "amount": "integer",
    "currencyName": "string"
}

GET (Read)

https://api.mopub.com/v1/adunits/ : returns all ad units

https://api.mopub.com/v1/adunits?[FILTER]: see supported filters below

‘https://api.mopub.com/v1/orders/[key]’: uses an explicit object ID

Filters

If no filter is used, then all objects are returned in a list format. If the filter matches multiple objects, then a list format is returned.

Support filters:

  • appKey
  • name (not case-sensitive)
  • appType (ios or android)
  • format (banner, fullscreen, rewarded, medium_rectangle, native)

POST (Create)

https://api.mopub.com/v1/adunits/

Example JSON for the body of the POST request.

{
    "appKey": "jhai8u98hjiionzzzzzz",
    "appName": "MoPub Sample",
    "format": "banner",
    "name": "Banner Ad unit",
    "refreshInterval": "30"
}

A successful POST will return the JSON representation for the newly created ad unit.

PUT (Update)

Usage Details The operation described here, ‘set’, will just take a dictionary in as “data” and update the object with the settings of that dictionary.

  • Uses http PUT method
  • Request body is json format (not form-data)
  • The response is the modified object

Supported Fields

  • name
  • frequency caps
  • refresh rates
  • disable_autocpm (network line item only)

Example

https://api-staging.mopub.com/v1/adunits/5197a8e32adc47a8beb08e3dd87c22ww

{
    "op": "set",
    "data": {
        "name": "New Name"
    }
}

Last updated February 19, 2021

TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.

© 2021 MoPub (a division of Twitter, Inc.)