Advertiser Management API

Vungle’s Advertiser Management APIs enable you to get and overwrite existing campaign targeting settings, budgets, default bids, and multi-bids.  To use the Advertiser Management API, please contact your Account Manager or email support@vungle.com.

General

Authentication, Headers, Error Codes

Authentication

The Bearer Token API is used for authentication for all Advertiser Management APIs. You need your account’s unique Secret Key and Refresh Token to retrieve the Bearer Token. You can find the Secret Key and Refresh Token in the Advertiser Dashboard's Account page, under the Advertiser Management API section (as shown below), after a Vungle admin has approved you to use these APIs.

image1.png

Method

GET

Endpoint

https://manage-ext.api.vungle.com/generate

The Bearer Token is valid for 60 minutes.

Request Body Example

GET https://manage-ext.api.vungle.com/generate

Request Headers Example

secret-key: 4eaaca71d77b2d9b45e117b20adfb13f
refresh-token: 66ba2d92d7644626635f07593321494472c800fc08b82f26bfa1ea866ec5f0c5

Response Example

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjU4YjZiYzVlMmM1MTEwOTE3MjAwMDFkMiIsImFjY291bnQiOiI1NjFlOGQ5NDZiOGQ5MGY2MWEwMDIyMzEiLCJhcGlUb2tlbiI6IjRlYWFjYTcxZDc3YjJkOWI0NWUxMTdiMjBhZGZiMTNmIiwiaWF0IjoxNjA2Nzg5ODgzLCJleHAiOjE2MDY3OTM0ODN9.TfWyNwWkKwM2AUk5DaCx49Ine1U0HTryceonlWBQux4"
}

Required Header Parameters

vungle-version: 1
Content-Type: application/json
Authorization: Bearer [Bearer_Token]

Error Codes

Code Status Explanation
200 Success The request was successfully processed by Vungle.
400 Bad Request The request was not understood by the server, generally due to bad syntax.

Example reasons:

  • Pub ID is incorrect
  • Duplicate Pub and/or Geo Bid
  • Geo is not in campaign targeting
  • Bid is outside of acceptable range
401 Authentication Error Make sure that the correct Bearer Token is present in the request.

404

Campaign Not Found Campaign ID does not exist in the Account.
413 Payload Too Large Multi-bidding is only allowed up to 10000 unique bids.
429 Too Many Requests The rate limit of 20 QPS per Token has been reached.
500 Vungle System Error There is a Vungle system error. Please try again later or contact your Account Manager.

Applications

Use the Applications API to get a list of the applications under your account and to create applications.

Retrieve Applications List

Method

GET

Endpoint

https://manage-ext.api.vungle.com/applications/

Parameters

Name Mandatory Datatype Description
page Yes Number Pagination instructions: which page to return
per_page Yes Number Pagination instructions: number of items to return per page
platform No String Target device operation system
Request Example
GET https://manage-ext.api.vungle.com/applications/?page=1&per_page=50

Response Example

{
    "id": "523456789876543212345ff8",
    "name": "App1",
    “store”: {
	"id”: “id345676548”,
    }
    “platform”: “iOS”
  },
  {
    "id": "512345678987654321234e06",
    "name": "App2",
    “platform”: “iOS”
    “store”: {
	"id”: “id345678902”,
    }
  }

Create an Application

Use the Application API to create applications under your account. 

Method

POST

Endpoint

https://manage-ext.api.vungle.com/applications

Parameters

Name Mandatory Datatype Description
name Yes String Application name
platform Yes String Target device operating system
bundleId Yes String App store ID

Request Example

POST https://manage-ext.api.vungle.com/applications

Response Example

{
    "id": "5ef59a51fc1ba31e101abff8",
    "name": "Uber",
    "bundleId”: “id368677368”,
    “platform”: “iOS”
  }

Campaigns

Retrieve Campaigns List

Use this API to get a list of campaigns under the account. This enables you to retrieve the relevant campaign ID to use with the Management API.

Method

GET

Endpoint

https://manage-ext.api.vungle.com/campaigns/list

Parameters

Name Mandatory Datatype Description
filter[application.id:in] no String Filter for specific application IDs (comma-separated)
filter[status:eq] no

String

Filter for status type (active or paused)
page yes number Pagination instructions: which page to return
per_page yes number Pagination instructions: number of items to return per page

Request Example

GET https://manage-ext.api.vungle.com/campaigns/list?page=1&per_page=50&filter[application.id:in]=012a34567bc89d012a34567b&filter[status:eq]=active

Response Example

Header: The expected response headers for this paginated call:

  • Vungle-Pagination-Total
  • Vungle-Pagination-Pages
  • Vungle-Pagination-Page
Response Body
  {
    "id": "5ef59a51fc1ba31e101abff8",
    "name": "My Campaign A",
    "status": "active",
    "application": {
      "id": "5d242d26b47a7f71a12b9574",
      "name": "My Awesome App"
    }
  },
  {
    "id": "5dcda089d117775a30258e06",
    "name": "My Campaign B",
    "status": "active",
    "application": {
      "id": "55b7adde5d682610380000b3",
      "name": "My Fun App"
    }
  }

Retrieve Campaign Details

GET all the campaign settings (including targeting and budget settings) for a single campaign. You will need all these settings, changed and unchanged, to make campaign setting changes:

  • To make targeting changes, you must PUT all targeting settings (including both changed and unchanged settings) using the Targeting API.
  • To make budget changes, you must PUT all budget settings (including both changed and unchanged settings) using the Budget API .
  • To attach creatives to a campaign, ensure that the campaign's creative_type value matches the creative's creative_type value. This value is returned as one of the campaign details (and the creative_type of a creative is returned as one of the creative details). Possible values for creative_type are:
    • mrec: MREC (medium rectangle) ads are similar to banners; they are rectangular and do not require a full screen view, typically displayed on the top or bottom of the screen, so that the user can continue to interact with the app while the ad is playing. 
    • banner: This ad format does not require a full screen; instead, the publisher determines the location of the ad container within their app. Banner ads may be displayed anywhere on the screen, and the user can continue using the app while the ad is being played. 
    • fullscreen: Full screen ads cover the interface of the hosting app; some full screen ads are rewarded.

Method

GET

Endpoint

https://manage-ext.api.vungle.com/campaigns/{id}

Parameters

Name Mandatory Datatype Description
id yes String Vungle Campaign ID

Request Example

GET https://manage-ext.api.vungle.com/campaigns/1a2b3c4d5e6f7g8h9i10j11k

Response Example

{
  "id": "61b43aee2801d000105c87b5",
  "created": "2021-12-11T05:45:18.770Z",
  "updated": null,
  "is_deleted": false,
  "admin_status": "pending",
  "status": "active",
  "name": "23e23e2",
  "vungle_name": "23e23e2",
  "format": "vungle_mraid",
  "endcard_url": "https://s3.amazonaws.com/vungle2-cdn-qa/templates/custom_creative_bundles/61b43a45c3af740010e421ae/1643338354065/1643338354065-3.7.1.zip",
  "hasUnapprovedPlayable": false,
"creative_type": "mrec", "campaigns": [ { "id": "61d88c4e0c2f3e00167b1059", "name": "qedqeqd" } ], "targeting": { "is_streaming": false, "devices": { "phone": true, "tablet": true }, "lifetime_cap": { "is_enabled": false, "value": 0 }, "ad_backoff": { "is_enabled": false, "value": 0 } }, "tags": [], "tracking": { "events": [ { "name": "mute", "url": "" }, { "name": "unmute", "url": "" }, { "name": "video_close", "url": "" }, { "name": "postroll_click", "url": "" }, { "name": "postroll_view", "url": "" } ] }, "replacements": [ { "key": "SKOVERLAY_AUTO", "value": "false", "name": "StoreKit Overlay Auto Show" }, { "key": "CREATIVE_VIEW_TYPE", "value": "video_and_endcard", "name": "Creative View Type" }, { "key": "ENDCARD", "value": "https://s3.amazonaws.com/vungle2-cdn-qa/templates/custom_creative_bundles/61b43a45c3af740010e421ae/1643338354065/1643338354065-3.7.1.zip", "name": "Endcard" }, { "key": "CTA_BUTTON_URL", "value": "https://apps.apple.com/us/app/dvd-netflix/id1169772776?uo=4", "name": "CTA URL" }, { "key": "FULL_CTA", "value": "false", "name": "Full Screen Clickable" }, { "key": "VIDEO_SHOW_CTA", "value": "false", "name": "Video CTA" }, { "key": "DOWNLOAD_BUTTON_DELAY_SECONDS", "value": "3.5", "name": "Video CTA Delay" } ], "postBundle": "", "application": { "id": "61841462f992697fe955fe7b", "admin_status": "approved", "name": "DVD Netflix", "category": "Entertainment", "platform": "ios", "skanDecouplingCampaign": null, "tags": [], "targeting": { "tags": { "type": "deny", "tags": [] }, "publisher": { "applications": [] } }, "account": {}, "settings": { "click_look_back_period": {}, "view_look_back_period": {} }, "store": { "id": "1169772776", "company": "DVD.com, A Netflix Company", "rating": "3.5", "thumbnail": "https://vungle2-cdn-qa.s3.amazonaws.com/madmen/assets/61841462f992697fe955fe7b/icon.png", "url": "https://apps.apple.com/us/app/dvd-netflix/id1169772776?uo=4", "iab": [ { "id": "IAB9", "name": "Hobbies & Interests", "type": "declared_by_dev" }, { "id": "IAB1-5", "name": "Movies", "type": "inferred" }, { "id": "IAB1", "name": "Arts & Entertainment", "type": "inferred" } ], "content_tag": "4+", "original_category": "Entertainment", "original_name": "DVD Netflix", "is_free": true, "orientation": null }, "surge_override_settings": { "is_enabled": false, "value": 0 }, "skadnetwork_settings": { "is_capable": true, "is_enabled": false, "is_changeable": true, "is_redownload_billed": true, "skadnetwork_postback_destination": null, "usage": {} } }, "language": { "code": "en", "name": "English", "is_enforced": false }, "template": { "id": "61c149b4ea8fdc0016943315", "name": "Adaptive Creative Multi-Page", "protocol": "vungle_mraid", "format": "multi_page_fullscreen", "cdn_url": "https://s3.amazonaws.com/vungle2-cdn-qa/templates/d27ebfe068ded442a445e0426b6d8978.zip", "is_custom_creative": true, "template_category": { "adaptive-creative": true }, "originalTemplateID": "5d7936a80ed7e506be620bf0" }, "account": { "id": "5ed6e3489e1ed7000f3d05dc", "name": "Sergey Kuznetsov" } }

Update Campaign Target Settings

Use the Targeting API to update the targeting settings for your campaign. You must first GET all Targeting settings for a single campaign as described in the Retrieve Campaign Details section, and then PUT all Targeting settings, changed and unchanged, for the campaign, containing any edits.

Note: This API currently does not include device model targeting.

Method

PUT

Endpoint

https://manage-ext.api.vungle.com/campaigns/{id}/targeting

Parameters

Name Mandatory Datatype Description
id Yes String Campaign ID
network Yes String User’s network connection: “All” or “Wifi only”
geo.region Yes String Geo value must be “region”: “country”
geo.countries Yes String Countries to target
geo.countries.code Yes String List countries to target by ISO 3166 2-letter country code (e.g. US, CA, MX)
versions.application.is_enabled Yes Boolean OS versions to target (e.g., 'min': 5 to 'max': 13.1)

is_enabled must be set to 'true' to use this targeting

versions.application.min Yes Decimal Min OS version to target (e.g. “min”: 5.1 or “0” for no min version)
versions.application.max Yes Decimal Max OS version to target (e.g. “max”: 13.1 or “0” for no max OS version)
devices Yes Boolean iOS device types to target (e.g. ipod, phone, tablet) Not required for non-iOS campaigns.
publisher.applications.type Yes String Enable Pub App targeting

'None' = disabled 

'Allow' = target publisher apps

'Deny' = exclude publisher apps

applications Yes Array List of publisher apps to target or exclude. Use empty array if application targeting not used (“None”)

Request Example

{
  "targeting": {
    "network": "all",
    "geo": {
      "region": "country",
      "countries": [
        {
          "code": "US"
        },
        {
          "code": "CA"
        }
      ]
    },
    "versions": {
      "application": {
        "is_enabled": true,
        "min": 5.1,
        "max": null
      }
    },
    "devices": {
      "ipod": false,
      "phone": true,
      "tablet": true
    },
    "publisher": {
      "applications": [],
      "type": "allow"
    }
  },
  "application": {
    "id": "MyApplicationId123"
  }
}

Update Campaign Budget Settings (Default Bid, Budgets, Pricing Type)

Use the Budget API to update campaign default bid, daily budget, total budget, and campaign pricing type. Each response updates a single campaign. You must first GET all Budget settings for a single campaign as described in the Retrieve Campaign Details section, and then PUT all Budget settings, changed and unchanged, for the campaign, containing any edits.

Method

PUT

Endpoint

https://manage-ext.api.vungle.com/campaigns/{id}/budget

Parameters

Name Mandatory Datatype Description
id yes String Campaign ID
bid yes Decimal Default campaign bid
daily yes Decimal Campaign daily budget
total yes Decimal Campaign total budget
type yes String Campaign bid type (only 'install' is allowed)

Request Example

{
  "budget": {
    "bid": 20.50,
    "daily": 10000,
    "total": 1000000,
    "type": "install"
  }
}

Update Campaign Budget by Country

Update daily geographical budget by country. 

Method

PUT

Endpoint

https://manage-ext.api.vungle.com//campaigns/{id}/budget/geo

Parameters

Name Mandatory Datatype Description
id Yes String Vungle Campaign ID
geo.geo Yes String ISO 3166 2-letter country code of Geo object (e.g., US, CA, MX) 
geo.rate Yes Currency (USD) Maximum budget for this country, must be >0

Request Header Example

PUT https://manage-ext.api.vungle.com/campaigns/1a2b3c4d5e6f7g8h9i10j11k/budget/geo

Request Body Example

{
   "geo": [{
       "geo": "BH",
       "rate": 1.0
   }, {
       "geo": "CN",
       "rate": 2.0
   }]
}

Response Example

{
   "messages": [
       "Budget successfully updated."
   ]
}

Insert or Update Bids in a Campaign's Multi-Bidder

Apply a list of bids per country and/or application for a single campaign.

Bid logic:

  • The default campaign bid will take effect when no specific Publisher, Country, or Publisher-Country bid is set.
  • The Publisher bid will take effect where no specific Country is set.
  • The Country bid will take effect where no specific Publisher is set.
  • Bids can be set with a maximum of 8 decimal places.
  • Vungle supports a maximum of 10000 bids per campaign.

Insert/update bid logic:

  • Define Application bid with only application ID and bid value.
  • Define Country bid with country code, "*" for application ID, and bid value.
  • Define Country-Application bid with country, application, and bid values.
  • Country and Country-Application bids must have that country in the campaign’s geo targeting or you will get an invalid error.
  • For any Publisher Application and/or Country combination, if a bid already exists, this POST will change that bid. If a bid does not exist, this POST will add that bid to the campaign.

Note: For CPM campaigns, bids are per impression, not per 1000 impressions.

Method

POST

Endpoint

https://manage-ext.api.vungle.com/campaigns/{id}/multibidding

Parameters

Name Mandatory Datatype Description
id Yes String Campaign ID
pub_app_id Yes String Publisher App ID
Use “*” when setting a Country only bid
name No String Publisher App Name
Value can be null, since App ID is the required publisher identifier
geo Yes String ISO 3166 2-letter country code (e.g., 'US' or 'GB') or null if publisher bid only
rate Yes Decimal You can insert/update a maximum of 10000 bids per campaign

Request Example

{
  "publisher_rates": [
    {
      "pub_app_id": "ObjectId",
      "name": "Fun game 1",
      "geo": "US",
      "rate": 50
    },
    {
      "pub_app_id": "ObjectId",
      "name": "Fun game 2",
      "geo": "",
      "rate": 0.25
    },
    {
      "pub_app_id": “*”,
      "name": "",
      "geo": "AU",
      "rate": 0.8
    }
  ]
}

Notes to explain request body example:

  • For publisher application 'Fun game 1', in the US, the rate will be $50.
  • For publisher application 'Fun game 2', the default rate will be $0.25. Note that geo is required but can be an empty string.
  • For AU users, the default bid will be $0.8 if there is no Publisher + Country bid or Publisher-level bid for that Publisher. Note that the pub_app_id must be set as "*".

Delete Bids in a Campaign's Multi-Bidder

Delete a list of publisher and/or country multi-bids.

Method

DELETE

Endpoint

https://manage-ext.api.vungle.com/campaigns/{id}/multibidding

Parameters

Name Mandatory Datatype Description
id Yes String Campaign ID
pub_app_id Yes String Publisher App ID
Use “*” when setting a Country only bid
name No String Publisher App Name
Value can be null, because App ID is the required publisher identifier
geo Yes String ISO 3166 2-letter country code (e.g., 'US' or 'GB') or null if publisher bid only
rate Yes Decimal You can insert/update a maximum of 10000 bids per campaign

Request Example

{
  "publisher_rates": [
    {
      "pub_app_id": "ObjectId",
      "name": "Fun game 1",
      "geo": "US",
      "rate": 50
    },
    {
      "pub_app_id": "ObjectId",
      "name": "Fun game 2",
      "geo": "",
      "rate": 0.25
    },
    {
      "pub_app_id": “*”,
      "name": "",
      "geo": "AU",
      "rate": 0.8
    }
  ]
}

Attach a Creative to a Campaign

Use this call to attach a Creative to a Campaign. To attach creatives to a campaign, ensure that the campaign's creative_type value matches the creative's creative_type value. This value is returned as one of the creative details (and the creative_type of a campaign is returned as one of the campaign details). Possible values for creative_type are:

  • mrec: MREC (medium rectangle) ads are similar to banners; they are rectangular and do not require a full screen view, typically displayed on the top or bottom of the screen, so that the user can continue to interact with the app while the ad is playing.
  • banner: This ad format does not require a full screen; instead, the publisher determines the location of the ad container within their app. Banner ads may be displayed anywhere on the screen, and the user can continue using the app while the ad is being played.
  • fullscreen: Full screen ads cover the interface of the hosting app; some full screen ads are rewarded.

Method

PUT

Endpoint

https://manage-ext.api.vungle.com/campaigns/{id}/attach

Parameters

Name Mandatory Datatype Description
id Yes String Campaign ID
creative_id Yes String Creative ID

Request Example

{ “creativeId”: ”MyCreativeId123” }

Response Example

{ 
"messages": ["success message(s)"]
}

Detach a Creative From a Campaign

Detach a Creative from a Campaign.

Method

PUT

Endpoint

https://manage-ext.api.vungle.com/campaigns/{id}/detach

Parameters

Name Mandatory Datatype Description
id Yes String Campaign ID
creative_id Yes String Creative ID

Request Example

{ “creativeId”: ”MyCreativeId123” }

Response Example

{ 
"messages": ["success message(s)"]
}

Creatives

Retrieve Creatives List

Retrieve a list of creatives, their names, and the names of their parent campaigns. 

Method

GET

Endpoint

https://manage-ext.api.vungle.com/creatives/list

Parameters

Name Mandatory Datatype Description
id No Array of String Creative IDs to return
name No String Creative name substring
campaigns No Array of String Campaign IDs if you choose to restrict the returned list of creatives to only those creatives that are attached to the provided Campaign IDs

Request Example: Filter by Creative Name

GET /creatives?filter[name:eq]=CreativeName

Response Example: Filtered by Creative Name

[{
"id": "ObjectID of the creative",
"name": "name of the creative",
"status": "status of the creative",
"applicationId": "ObjectID of the associated application",
"parentCampaignIds": ["ObjectID(s) of attached campaigns"],
"creative_type": "one of fullscreen, mrec or banner"
}]

Request Example: Filter by Campaign ID

GET /creatives?filter[campaign.id:in]=60d583f37cd62b6d03621108,50d583f37cd62b6d03921103

Response Example: Filtered by Campaign ID

[
  {
    "id": "5ed745d29291b60016cf8d77",
    "name": "CreativeName1",
    "status": "active",
    "applicationId": "5e9a2fb0de290200108b4370",
    "parentCampaignIds": [
      "60d5837f7cd62b6d03621107",
      "60d583f37cd62b6d03621108"
    ],
    "creative_type": "fullscreen"
  }, {
    "id": "5ed745d29291b60016cf8d77",
    "name": "CreativeName2",
    "status": "active",
    "applicationId": "5e9a2fb0de290200108b4370",
    "parentCampaignIds": [
      "40d5837f7cd62b6d03721109",
      "50d583f37cd62b6d03921103"
    ],
    "creative_type": "mrec"
  }
]

Retrieve Creative Details

GET the creative details for a single creative, including its ID, name, status, application ID of the parent app, and campaign IDs of all its parent campaigns. The response also returns the creative's creative_type, which is a value of interest when you attach a creative to a campaign (the campaign's creative_type must match that of the creative).

Method

GET

Endpoint

https://manage-ext.api.vungle.com/creatives/{id}

Parameters

Name Mandatory Datatype Description
id Yes String Creative ID

Request Example

GET https://manage-ext.api.vungle.com/creatives/5ef59a51fc1ba31e101abff8

Response Example

{
  "id": "ObjectID of the creative",
  "name": "name of the creative",
  "status": "status of the creative",
  "applicationId": "ObjectID of the associated application",
  "parentCampaignIds": ["ObjectID(s) of attached campaigns"],
  "creative_type": "one of fullscreen, mrec or banner"
}

Pause a Creative

Change the status of a creative to 'Paused'. 

Method

PUT

Endpoint

https://manage-ext.api.vungle.com/creatives/{id}/pause

Parameters

Name Mandatory Datatype Description
id Yes String Creative ID

Request Example

PUT https://manage-ext.api.vungle.com/creatives/5ef59a51fc1ba31e101abff8/pause

Response Example

{
    "messages": ["success message(s)"]
  }

Activate a Creative

Change the status of a creative to 'Active'. 

Method

PUT

Endpoint

https://manage-ext.api.vungle.com/creatives/{id}/activate

Parameters

Name Mandatory Datatype Description
id Yes String Creative ID

Request Example

PUT https://manage-ext.api.vungle.com/creatives/5ef59a51fc1ba31e101abff8/activate

Response Example

{
    "messages": ["success message(s)"]
  }
Powered by Creativity Driven by Performance Sign Up Here

Questions?

Need further assistance, feel free to reach out to us, we’re here to help!

Was this article helpful?