Campaigns

Overview

The CampaignService provides methods for creating, updating, deleting and retrieving campaigns. You can also create an app install campaign if your goal is to generate app downloads.

A campaign organizes one or more ad groups together and has its own budget and targeting settings. Campaigns allow you to manage your ads based on your advertising goals and business strategy. A campaign can include ads that run both in mobile search as well as in native positions within content streams across the Yahoo! network. You can control where your ads will run by configuring the channel attribute.

Fields

The Campaign object contains the following fields:

Name Description Type Add Update
advertiserID The ID of the advertiser to retrieve. long Required Optional (Read-Only)
budget The budget for your campaign in the currency provided in your billing settings. Using the budgetType attribute, you can either set a daily spend cap or provide a budget for the entire duration of the campaign. BigDecimal Required Optional
budgetType

Type of budget. Value can be:

  • LIFETIME” - the budget is for the entire duration of the campaign.
  • DAILY” - the budget is the daily spend amount. Daily spend will be capped at the budget value.
enum Required Optional
campaignName The name of the campaign. Maximum limit is 100 characters. string Required Optional
channel

The supply channel on which the campaign will run. The available options are:

  • NATIVE - will run in native positions on Yahoo! content streams
  • SEARCH - will run on mobile search supply
  • SEARCH_AND_NATIVE - will run on both mobile search and content streams supply

If channel is not set, default value will be SEARCH_AND_NATIVE. Please also note that for your ads to actually serve on the channels you have set, you will also need to set a bid for this channel.

enum Optional Optional
id The ID of the campaign. long N/A Required
language The language of the targeted audience. By default, this is set to en (for english). This can be set at the time of campaign creation and cannot be modified. For the list of supported languages, refer to the data dictionary section. string Optional Read-only
objective

The objective of the campaign. Value can be:

  • VISIT_WEB - This is the default value and it should be used if your goal is to generate traffic to your webpages. This objective supports CPC pricing type for both mobile SEARCH and NATIVE ad campaigns.
  • VISIT_OFFER - Use this objective for product ads campaigns. Note that the objective supports the CPC pricing type and SEARCH campaigns only.
  • PROMOTE_BRAND - Use this objective if your goal is to increase brand awareness. This objective supports CPM or CPV pricing type and NATIVE campaigns only.
  • INSTALL_APP - Use this objective if your goal is to generate app downloads. This objective supports CPC or CPV pricing type and NATIVE campaigns only. For more details, see the create an app install campaign section.

Objective can only be set at the time of campaign creation and cannot be modified.

string Optional Read-only
status

The status of the campaign. Valid values are:

  • ACTIVE
  • PAUSED
  • DELETED

Campaigns can be created in an ACTIVE state. If a campaign is in a PAUSED state, specify valid start and end dates at the ad group level in order to activate it.

enum Required Optional
isPartnerNetwork Applies only to SEARCH campaigns. Determines whether your campaign will run on the Yahoo partner network. This field accepts TRUE or FALSE and defaults to TRUE. For NATIVE campaigns this field must be set to TRUE. enum Optional Optional
defaultLandingUrl This field is required only for INSTALL_APP campaigns. It should be used to pass the App Store or Google Play Store app url, and cannot be updated once set. Note that tracking parameters and redirects should not be part of the defaultLandingUrl. These should be provided at the ad level through the ad landingUrl. string Optional Read-only
trackingPartner This field is required only for INSTALL_APP campaigns. Use this field to specify the vendor you are using in order to track app install conversions. For a list of approved third-party tracking partners, refer to the data dictionary. enum Required (only for INSTALL_APP campaigns) Read-only
appLocale This is an optional field for INSTALL_APP campaigns. It can be used to specify the desired locale of the app store, and will default to “en-us” if not specified. For a list of available locales, refer to the data dictionary. enum Optional Read-only
advancedGeoPos Applies only to SEARCH campaigns. For the locations you target, the recommended and default value is DEFAULT, which means you will reach people either physically in your targeted locations or who have expressed interest in these locations. LOCATION_OF_PRESENCE means reaching only people physically in the targeted location, and LOCATION_OF_INTEREST means targeting only people who have expressed interest in the location. enum Optional Optional
advancedGeoNeg Applies only to SEARCH campaigns. Similar to advancedGeoPos but applies only to locations you exclude. Valid values are DEFAULT (the default) and LOCATION_OF_PRESENCE. enum Optional Optional

Endpoint

Resource URI

https://api.admanager.yahoo.com/v1/rest/campaign/

Example Representations

Campaign

{
  "id": 31364,
  "status": "PAUSED",
  "advertiserId": 87292,
  "campaignName": "SampleCampaign",
  "budget": 3000,
  "language": "en",
  "budgetType": "LIFETIME",
  "channel": "SEARCH_AND_NATIVE",
  "objective": "PROMOTE_BRAND",
  "isPartnerNetwork": "TRUE",
  "advancedGeoPos": "DEFAULT",
  "advancedGeoNeg": "DEFAULT"
}

Campaign Array

[
  {
      "id": 31336,
      "status": "ACTIVE",
      "advertiserId": 87292,
      "campaignName": "Campaign1",
      "budget": 1100,
      "language": "en",
      "budgetType": "LIFETIME",
      "channel": "SEARCH"
      "objective": "VISIT_WEB",
      "isPartnerNetwork": "TRUE",
          "advancedGeoPos": "DEFAULT",
          "advancedGeoNeg": "DEFAULT"
  },
  {
      "id": 31337,
      "status": "PAUSED",
      "advertiserId": 87292,
      "campaignName": "Campaign2",
      "budget": 2000,
      "language": "en",
      "budgetType": "LIFETIME",
      "channel": "NATIVE"
      "objective": "PROMOTE_BRAND",
      "isPartnerNetwork": "TRUE",
          "advancedGeoPos": "DEFAULT",
          "advancedGeoNeg": "DEFAULT"
  }
]

Campaign Response

{
  "errors": null,
  "response": {
      "id": 31364,
      "status": "PAUSED",
      "advertiserId": 87292,
      "campaignName": "SampleCampaign",
      "budget": 3000,
      "language": "en",
      "budgetType": "LIFETIME",
      "channel": "SEARCH_AND_NATIVE"
      "objective": "VISIT_WEB",
      "isPartnerNetwork": "TRUE",
          "advancedGeoPos": "DEFAULT",
          "advancedGeoNeg": "DEFAULT"
  }
}

Operations

Read specific campaign data

Method: To retrieve data for a specific campaign, make a GET call with the ID parameter.

Example: GET call to retrieve a campaign:

https://api.admanager.yahoo.com/v1/rest/campaign/31336

The response will be the campaign associated with the given ID:

{
  "errors": null,
  "response": {
      "id": 31336,
      "status": "PAUSED",
      "advertiserId": 87292,
      "campaignName": "SampleCampaign",
      "budget": 100,
      "language": "en",
      "budgetType": "LIFETIME",
      "channel": "SEARCH_AND_NATIVE",
      "objective": "VISIT_WEB",
      "isPartnerNetwork": "TRUE",
          "advancedGeoPos": "DEFAULT",
          "advancedGeoNeg": "DEFAULT"
  }
}

Response: The campaign associated with the given ID.

Example: GET call with multiple IDs. Please note that when you pass multiple IDs all other filters besides ID will be ignored:

https://api.admanager.yahoo.com/v1/rest/campaign/?id=30429&id=30430

Response: The campaigns associated with the given IDs:

{
  "errors": null,
  "response": [
      {
          "id": 30429,
          "status": "PAUSED",
          "advertiserId": 19426,
          "campaignName": "Campaign1",
          "budget": 100,
          "language": "en",
          "budgetType": "DAILY",
          "channel": "SEARCH",
          "objective": "VISIT_WEB",
          "isPartnerNetwork": "TRUE",
                  "advancedGeoPos": "DEFAULT",
                  "advancedGeoNeg": "DEFAULT"
      },
      {
          "id": 30430,
          "status": "PAUSED",
          "advertiserId": 19426,
          "campaignName": "Campaign2",
          "budget": 500,
          "language": "en",
          "budgetType": "DAILY",
          "channel": "SEARCH",
          "objective": "VISIT_WEB",
          "isPartnerNetwork": "TRUE",
                  "advancedGeoPos": "DEFAULT",
                  "advancedGeoNeg": "DEFAULT"
      }
  ]
}

Read data for filtered list of campaigns

Method: To retrieve data for a filtered list of campaigns, make a GET call using the following parameters:

Name Description Type
advertiserId The ID of the advertiser to filter campaigns by. long
mr The maximum number of rows to retrieve. int
si The start index or the first element to retrieve. int

Example: GET call for a filtered list of campaigns:

https://api.admanager.yahoo.com/v1/rest/campaign/?advertiserId=87292&mr=2

{
  "errors": null,
  "response": [
      {
          "id": 31336,
          "status": "PAUSED",
          "advertiserId": 87292,
          "campaignName": "MobileSearch",
          "budget": 100,
          "language": "en",
          "budgetType": "LIFETIME",
          "channel": "SEARCH",
          "objective": "VISIT_WEB",
          "isPartnerNetwork": "TRUE",
                  "advancedGeoPos": "DEFAULT",
                  "advancedGeoNeg": "DEFAULT"
      },
      {
          "id": 31337,
          "status": "ACTIVE",
          "advertiserId": 87292,
          "campaignName": "NativeAds",
          "budget": 100,
          "language": "en",
          "budgetType": "LIFETIME",
          "channel": "NATIVE",
          "objective": "PROMOTE_BRAND",
          "isPartnerNetwork": "TRUE",
                  "advancedGeoPos": "DEFAULT",
                  "advancedGeoNeg": "DEFAULT"
      }
  ]
}

Response: The list of campaigns matching the given filter.

Update existing campaigns

Method: To update one or more existing campaigns, make a PUT call to the Campaign endpoint with one or more campaign objects. Specify the fields to update; please note that id is the only required parameter, all other fields are optional. The result will be the list of updated campaigns. Partial update is supported; fields that are either not passed or passed as null will be ignored for the update. For example, in order to update the budget for a campaign:

PUT https://api.admanager.yahoo.com/v1/rest/campaign

Data passed
{
   "id": 31336,
   "budget":500
}

Example response
{
  "errors": null,
  "response": {
      "id": 31336,
      "status": "PAUSED",
      "campaignName": "NativeAds",
      "advertiserId": 87292,
      "budget": 500,
      "language": "en",
      "budgetType": "LIFETIME",
      "channel": "NATIVE",
      "objective": "PROMOTE_BRAND",
      "isPartnerNetwork": "TRUE",
          "advancedGeoPos": "DEFAULT",
          "advancedGeoNeg": "DEFAULT"
  }
}

Create a new campaign

Method: To create a new campaign, make a POST call to the Campaign endpoint with the required fields. Batch create is supported; either a campaign or a campaign array can be passed. The response will be the newly created campaign, or a list of multiple new campaigns if an array is passed.

Example 1: Create a campaign that will run only on native content streams:

POST https://api.admanager.yahoo.com/v1/rest/campaign

Data passed
{
  "status":"PAUSED",
  "campaignName":"NativeAdsCampaign",
  "budget": 3000,
  "language": "en",
  "budgetType": "LIFETIME",
  "advertiserId": 87292,
  "channel":"NATIVE",
  "objective": "PROMOTE_BRAND",
  "isPartnerNetwork": "TRUE",
  "advancedGeoPos": "DEFAULT",
  "advancedGeoNeg": "DEFAULT"
}

Example response
{
  "errors": null,
  "response": {
      "id": 31466,
      "status": "PAUSED",
      "advertiserId": 87292,
      "campaignName": "NativeAdsCampaign",
      "budget": 3000,
      "language": "en",
      "budgetType": "LIFETIME",
      "channel": "NATIVE",
      "objective": "PROMOTE_BRAND",
      "isPartnerNetwork": "TRUE,
          "advancedGeoPos": "DEFAULT",
          "advancedGeoNeg": "DEFAULT"
  }
}

Example 2: Create multiple campaigns by passing in an array of campaigns:

POST https://api.admanager.yahoo.com/v1/rest/campaign

Data passed
[
  {
      "status": "PAUSED",
      "campaignName": "MobileSearch1",
      "budget": 100,
      "language": "en",
      "budgetType": "DAILY",
      "advertiserId": 87292,
      "channel": "SEARCH",
      "objective": "VISIT_WEB",
      "isPartnerNetwork": "TRUE",
          "advancedGeoPos": "DEFAULT",
          "advancedGeoNeg": "DEFAULT"
  },
  {
      "status": "PAUSED",
      "campaignName": "MobileSearch2",
      "budget": 200,
      "language": "en",
      "budgetType": "LIFETIME",
      "advertiserId": 87292,
      "channel": "SEARCH",
      "objective": "VISIT_WEB",
      "isPartnerNetwork": "TRUE",
          "advancedGeoPos": "DEFAULT",
          "advancedGeoNeg": "DEFAULT"
  }
]

Example response
{
  "errors": null,
  "response": [
      {
          "id": 31467,
          "status": "PAUSED",
          "advertiserId": 87292,
          "campaignName": "MobileSearch1",
          "budget": 100,
          "language": "en",
          "budgetType": "DAILY",
          "channel": "SEARCH",
          "objective": "VISIT_WEB",
              "isPartnerNetwork": "TRUE",
                  "advancedGeoPos": "DEFAULT",
                  "advancedGeoNeg": "DEFAULT"
      },
      {
          "id": 31468,
          "status": "PAUSED",
          "advertiserId": 87292,
          "campaignName": "MobileSearch2",
          "budget": 200,
          "language": "en",
          "budgetType": "LIFETIME",
          "channel": "SEARCH",
          "objective": "VISIT_WEB",
              "isPartnerNetwork": "TRUE",
                  "advancedGeoPos": "DEFAULT",
                  "advancedGeoNeg": "DEFAULT"
      }
  ]
}

Create an app install campaign

Method: To create an app install campaign, you will need to set the objective to INSTALL_APP, and to provide a link to your app in the defaultLandingUrl field. Note that tracking parameters and redirects should not be part of the defaultLandingUrl. These should be provided at the ad level through the ad landingUrl. Also note that trackingPartner is required in the request, but will not be returned in the response. You can refer to the dictionary service for supported trackingPartner values.

POST https://api.admanager.yahoo.com/v1/rest/campaign

Data passed
  {
      "budgetType": "DAILY",
              "budget": 800,
              "status": "ACTIVE",
              "objective": "INSTALL_APP",
              "advertiserId": 11610,
              "campaignName": "Flickr Android app install campaign",
              "defaultLandingUrl": "https://play.google.com/store/apps/details?id=com.yahoo.mobile.client.android.flickr",
              "channel": "NATIVE",
              "trackingPartner": "appsflyer",
              "appLocale":"en-us"
  }



Example response
{
  "errors": null,
  "timestamp": "2015-02-05 6:10:46",
      "response": {
         "language": "en",
         "budget": 800,
         "budgetType": "DAILY",
         "id": 338558004,
         "status": "ACTIVE",
         "objective": "INSTALL_APP",
         "campaignName": "Flickr Android app install campaign",
         "advertiserId": 11610,
         "isPartnerNetwork": "TRUE",
         "defaultLandingUrl": "https://play.google.com/store/apps/details?id=com.yahoo.mobile.client.android.flickr",
         "channel": "NATIVE",
         "appLocale":"en-us"
       }
}

Delete a campaign

Method: To delete one or more campaigns, make a PUT call to the Campaign endpoint. The following parameters are required for the PUT call:

Field Description
id The ID of the campaign to delete.
status The status of the campaign should be set to DELETED in order to delete the campaign.

Example:

PUT https://api.admanager.yahoo.com/v1/rest/campaign

Data passed
{
  "id": 31336,
  "status": "DELETED"
}

Example response
{
  "errors": null,
  "response": [
      {
          "id": 31336,
          "status": "DELETED",
          "advertiserId": 87292,
          "campaignName": "MobileSearch1",
          "budget": 100,
          "language": "en",
          "budgetType": "DAILY",
          "channel": "SEARCH",
          "objective": "VISIT_WEB",
              "isPartnerNetwork": "TRUE",
                  "advancedGeoPos": "DEFAULT",
                  "advancedGeoNeg": "DEFAULT"
      }
  ]
}

Frequency capping

You can define the number of times users can be exposed to your campaign in a given time period. Note that this only applies to PROMOTE_BRAND campaigns. For other campaign types, the frequency is managed and optimized by Gemini.

Endpoint

Resource URI

https://api.admanager.yahoo.com/v1/rest/frequency

You can set frequency capping by making a POST call passing in the following fields:

Name Description Type Add Update
id The unique identifier long NA Required
value The number of times a given user will be exposed to your campaign. int Required Optional
type The time interval for which the frequency cap is set. Currently this must be set to DAILY or WEEKLY. enum Required Optional (Read-Only)
advertiserId The advertiser id. long Required Optional (Read-Only)
parentType Must be set to CAMPAIGN. enum Required Optional (Read-Only)
parentId The ID of the parent campaign. long Required Optional (Read-Only)
status Valid values are ACTIVE, PAUSED and DELETED. Will default to ACTIVE if not provided. enum Optional Optional

For example, to set frequency capping for a campaign:

PUT https://api.admanager.yahoo.com/v1/rest/frequency

Data passed
{
  "value": 10,
  "type": "DAILY",
  "advertiserId": 11610,
  "parentType": "CAMPAIGN",
  "parentId": 332817035,
  "id": 299239189394
}


Example response
{
  "errors": null,
  "timestamp": "2015-08-22 1:58:45",
  "response": {
      "type": "DAILY",
      "id": 295617989759,
      "status": "ACTIVE",
      "parentId": 332817035,
      "parentType": "CAMPAIGN",
      "advertiserId": 11610,
      "value": "10"
  }
}

To delete frequency capping for a campaign:

PUT https://api.admanager.yahoo.com/v1/rest/frequency

Data passed
{
  "id": 295617989759,
  "status": "DELETED"
}


Example response
{
  "errors": null,
  "timestamp": "2015-08-22 2:08:50",
  "response": {
      "type": "DAILY",
      "status": "DELETED",
      "id": 295617989759,
      "parentId": 332817035,
      "parentType": "CAMPAIGN",
      "advertiserId": 11610,
      "value": "10"
  }
}