1. Help Center
  2. Advertiser
  3. Advertiser APIs

Advertiser Management API

Avatar
Vungle Agent
Follow

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.

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

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.

Campaign List API

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

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

Campaign Details API

Get campaign settings for a single campaign. To make campaign setting changes, you must put all targeting settings for the Targeting API and all budget settings for the Budget API (including both changed and unchanged settings).

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": "1a2b3c4d5e6f7g8h9i10j11k",
 "created": "2019-11-21T21:25:56.790Z",
 "updated": "2019-11-21T23:54:44.265Z",
 "is_deleted": false,
 "name": "Great Ad Campaign",
 "status": "active",
 "admin_status": "approved",
 "has_pending_changes": false,
 "budget": {
   "bid": 4.5,
   "type": "install",
   "daily": 10000,
   "total": 250000,
   "daily_spend_limit_type": "campaign",
   "daily_spend_limit_geos": [],
   "publisher_rates": []
   }
 },
 "dates": {
   "start": "2015-07-10T08:00:00.000Z",
   "end": "2015-08-08T08:00:00.000Z",
   "is_indefinite": false
 },
 "tracking": {
   "url": "http://something.net/rd?src=777ABCD1234CCCAAA&ofr=XXDBA86FCDB24AEAOU&advertising_id={{{ifa}}}&site_id={{{site_id}}}&click_label={{{id}}}&tracking_label={{{app_id}}}",
   "events_url": "",
   "events": [
     {
       "name": "postroll_click",
       "url": "http://something.net/rd?src=777ABCD1234CCCAAA&ofr=XXDBA86FCDB24AEAOU&advertising_id={{{ifa}}}&site_id={{{site_id}}}&click_label={{{id}}}&tracking_label={{{app_id}}}"
     }
   ]
 },
 "targeting": {
   "network": "wifi",
   "geo": {
     "region": "country",
     "countries": [
       {
         "code": "CA"
       },
       {
         "code": "MX"
       },
       {
         "code": "US"
       }
     ]
   },
   "versions": {
     "application": {
       "is_enabled": true,
       "min": 5,
       "max": null
     }
   },
   "devices": {
     "ipod": false,
     "phone": true,
     "tablet": true
   },
   "publisher": {
     "type": "none",
     "applications": []
   }
 },
 "account": {
   "id": "5dd6900d730da60011d2f385",
   "name": "My Account Name"
 },
 "application": {
   "id": "5de7908525758f0010c937f9",
   "name": "My App Name",
   "platform": "android"
 },
 "creatives": [
   {
     "id": "5dd6994f25758f0010c93b01",
     "name": "PLAYABLE_PLUS_15743463"
   },
   {
     "id": "5dd691c825758f0010c9383c",
     "name": "DYNAMIC_TEMPLATE_15743442"
   }
 ]
}

Targeting API

Use the Targeting API to update the targeting settings for your campaign. You must GET all Targeting settings for a single campaign, and then PUT all Targeting settings 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 Body 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"
  }
}

Budget API

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 GET all Budget settings for a single campaign, and then PUT all Budget settings 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 Body Example

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

Bidding API

Use the Bidding API to manage multi-bids for specific publishers and/or countries. Each request inserts, updates, or deletes the bids existing in the Multi-Bidder.

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 Bids

Apply a list of bids per country and/or application for a single 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 Body 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

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 Body 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
    }
  ]
}
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!

Submit a request
Was this article helpful?