Advertiser Management API

Vungle Agent

March 22, 2023 00:49

Liftoff Direct 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 Liftoff admin has approved you to use these APIs.

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 Liftoff.
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	Liftoff System Error	There is a Liftoff 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 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	Liftoff 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"
   }
 ]
}

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	Liftoff 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.
Liftoff Direct 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 assign a Creative to a Campaign. To attach creatives to a campaign, ensure that the campaign's creativeType value matches the creative's creativeType value. This value is returned as one of the creative details (and the creativeType of a campaign is returned as one of the campaign details). Possible values for creativeType 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
`campaignId`	Yes	String	Campaign ID
`creativeId`	Yes	String	Creative ID

Request Example

{ “creativeId”: ”MyCreativeId123” }

Response Example

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

Detach a Creative From a Campaign

Unassign a creative from a campaign.

Method

PUT

Endpoint

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

Parameters

Name	Mandatory	Datatype	Description
`campaignId`	Yes	String	Campaign ID
`creativeId`	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)"]
  }

General

Authentication, Headers, Error Codes

Authentication

Required Header Parameters

Error Codes

Applications

Retrieve Applications List

Create an Application

Campaigns

Retrieve Campaigns List

Retrieve Campaign Details

Update Campaign Target Settings

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

Update Campaign Budget by Country

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

Delete Bids in a Campaign's Multi-Bidder

Attach a Creative to a Campaign

Detach a Creative From a Campaign

Creatives

Retrieve Creatives List

Retrieve Creative Details

Pause a Creative

Activate a Creative

Questions?