Campaigns

Overview

In BrightRoll DSP, a campaign is an advertising goal that defines a strategy for delivering ads within a set time period. Campaigns are typically defined by flight dates, bid prices, total budgets, daily budget caps, and KPI metrics (to measure campaign effectiveness).

Every campaign belongs to a specific advertiser and inherits default settings (time zone, currency, budget) from the advertiser. Campaign-level flight dates (start and end dates), frequency capping, and budget settings override line item-level settings.

Endpoint

https://dspapi.admanagerplus.yahoo.com/traffic/campaigns

Fields

The Campaign object contains the following fields:

Name Description Type Add Update
id ID of the campaign. integer N/A Required
name Name of the campaign. Must be unique. text Required Optional
status

Current status of the campaign.

  • ACTIVE - Active/Running
  • PAUSED - Paused
  • INACTIVE - Not active/Ended

Following status types are read-only:

  • STOP_TOTAL_BUDGET - Total budget reached
  • STOP_DAILY_BUDGET - Daily budget reached
  • NOT_STARTED - Not started yet
  • ENDED - Ended
  • NO_ADS_ADDED - No Ads added
  • ERROR - Error
text Required Optional
goalType

Key performance indicator (KPI) for the campaign.

  • CTR - Click through rate percentage.
  • CPC - Cost per click conversion amount.
  • CPA - Cost per action amount.
  • CPCV - Cost Per Completed View for video.
  • VCPM - Viewable CPM for video.
  • ROAS - Return On Ad Spend.
text Required Optional
goalValue Value to be set as a goal for the Goal Type (KPI). Note that if goalType is set to CTR, this value must be a percentage between 0 and 100. float Required Optional
frequencyCapPeriodType

Frequency capping method. You can specify frequency capping at either the Line or Campaign level. Note that setting frequency capping at the Campaign level will override any capping set at the Line level.

  • LINE_LEVEL_ONLY - Line Level Only: Frequency capping is set for each line in the campaign.
  • MINUTES - Campaign Level Duration: Minutes
  • HOURLY - Campaign Level Duration: Hourly
  • DAILY - Campaign Level Duration: Daily
  • WEEKLY - Campaign Level Duration: Weekly
  • MONTHLY - Campaign Level Duration: Monthly
text Optional Optional
frequencyCapValue Maximum number of impressions to serve per the frequencyCapPeriodType. integer Optional Optional
demoVendor

Demographic Targeting Data Provider for Video. BrightRoll DSP uses Yahoo and third-party data verification vendors to provide targeting verification when you set up demographic targeting for video ads. Important: Once the campaign is created, this value can not be changed.

  • YAHOO
  • COMSCORE
  • NIELSEN
text Optional Optional
timezone If you leave out this field or set it to null, BrightRoll DSP uses the time zone set up for the advertiser by default. You can override the default time zone when you create a campaign. Note: After you save a campaign, you can change the flight dates, but you cannot update the timezone. Use the tzId field from Timezones response. Some example values: America/New_York, Etc/GMT. text Optional Optional
currency If you leave out this field or set it to null, BrightRoll DSP uses the currency set up for the advertiser by default. You can override the default currency when you create a campaign. Use the code field from the Currency Types response. Some example values: USD, CAD. text Optional Optional
accountId Advertiser/account ID. Refer to Advertisers. integer Required Optional
dailyBudget Daily Budget amount. (1): Required if dailyBudgetType is SPECIFIED_AMOUNT. float Required (1) Optional
dailyBudgetType

Daily Budget type is used to put a cap on the daily spend for your campaign, evenly allocate the total budget across remaining days, or spend the entire campaign budget on available inventory.

  • TOTAL_BUDGET - No Daily Budget: The entire campaign budget is available. This is the default value if not specified.
  • SPECIFIED_AMOUNT - Specified Amount: Specify a daily cap for the entire campaign in the dailyBudget field.
  • AUTO_ALLOCATED - Auto Allocated: The remaining overall budget is auto-allocated, establishing an expected daily rate of spend across the remaining duration of the campaign.
text Optional Optional
unlimitedBudget Set this to true if you have an unlimited budget. boolean Optional Optional
budget Total campaign budget amount. (1): Required if unlimitedBudget is false. float Required (1) Optional
startDate Campaign start date in yyyy-MM-dd format. Note: Start time depends on the campaign’s time zone. text Required Optional
endDate Campaign end date in yyyy-MM-dd format. Note: End time depends on the campaign’s time zone. Setting an end date is optional. text Optional Optional

Read Campaign (Single)

To retrieve data for a specific Campaign, make a GET call with the id parameter.

GET https://dspapi.admanagerplus.yahoo.com/traffic/campaigns/{id}
Name Description Type
id Campaign ID (Required) integer

The response will be the Campaign associated with the given ID.

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/campaigns/1

Example Response

{
  "response": {
    "status": "INACTIVE",
    "dailyBudgetType": "TOTAL_BUDGET",
    "goalType": "CTR",
    "frequencyCapPeriodType": "UNLIMITED",
    "timezone": "America/Chicago",
    "currency": "USD",
    "demoVendor": "YAHOO",
    "id": 258035,
    "name": "test_campaign",
    "createdAt": "2016-10-26T21:55:07Z",
    "startDate": "2016-10-26T05:00:00Z",
    "endDate": "2016-10-31T05:00:00Z",
    "updatedAt": "2016-11-04T22:25:43Z",
    "goalValue": 0,
    "frequencyCapValue": 0,
    "accountId": 1,
    "budget": 100
  },
  "errors": null,
  "timeStamp": "2017-05-17T17:34:03Z"
}

Read Campaigns (Filtered)

To retrieve a filtered list of Campaigns, make a GET call with the supported query parameters.

GET https://dspapi.admanagerplus.yahoo.com/traffic/campaigns?accountId={accountId}&page={page}&limit={limit}&sort={sort}&dir={dir}&query={search query}
Name Description Type
accountId Account or Advertiser ID (Required) integer
page Page number integer
limit Total number of items to return. Maximum allowed value is 100. integer
sort Column to sort by text
dir Sort direction. Valid values: asc, desc text
query Search term. Use url encoding conventions (i.e. a space should be replaced with a + or %20). text

The response will be the list of Campaigns matching the given filter(s).

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/campaigns?accountId=1&page=1&limit=2&query=test+order

Example Response

{
  "response": [
    {
      "status": "INACTIVE",
      "dailyBudgetType": "TOTAL_BUDGET",
      "goalType": "CTR",
      "frequencyCapPeriodType": "UNLIMITED",
      "timezone": "America/Los_Angeles",
      "currency": "USD",
      "id": 52029,
      "name": "test order tomorrow",
      "createdAt": "2015-05-14T18:56:28Z",
      "startDate": "2015-05-15T07:00:00Z",
      "updatedAt": "2015-05-14T18:56:28Z",
      "goalValue": 0,
      "frequencyCapValue": 0,
      "accountId": 1,
      "budget": 1000
    },
    {
      "status": "INACTIVE",
      "dailyBudgetType": "TOTAL_BUDGET",
      "goalType": "CTR",
      "frequencyCapPeriodType": "UNLIMITED",
      "timezone": "America/New_York",
      "currency": "USD",
      "id": 52030,
      "name": "test order tomorrow 201505141224",
      "createdAt": "2015-05-14T19:24:37Z",
      "startDate": "2015-05-15T04:00:00Z",
      "updatedAt": "2015-05-14T19:24:37Z",
      "goalValue": 0,
      "frequencyCapValue": 0,
      "accountId": 1,
      "budget": 12
    }
  ],
  "errors": null,
  "timeStamp": "2017-06-15T23:13:02Z"
}

Update Campaign

To update an existing Campaign, make a PUT call with a Campaign object payload and id parameter. The response will be the updated Campaign.

PUT https://dspapi.admanagerplus.yahoo.com/traffic/campaigns/{id}
Name Description Type
id Campaign ID (Required) integer

Example Request

PUT https://dspapi.admanagerplus.yahoo.com/traffic/campaigns/1

Example Payload

{
  "name": "test_campaign_3",
  "budget": 500.50
}

Example Response

{
  "response": {
    "id": 1,
    "name": "test_campaign_3",
    "createdAt": "2016-10-26T21:55:07Z",
    "startDate": "2016-10-26T04:00:00Z",
    "endDate": "2016-10-31T04:00:00Z",
    "updatedAt": "2017-05-17T17:41:16Z",
    "status": "INACTIVE",
    "goalType": "CTR",
    "goalValue": 25,
    "frequencyCapValue": 0,
    "frequencyCapPeriodType": "LINE_LEVEL_ONLY",
    "timezone": "Etc/GMT",
    "currency": "USD",
    "accountId": 1,
    "budget": 500.5,
    "dailyBudgetType": "SPECIFIED_AMOUNT",
    "dailyBudget": 1
  },
  "errors": null,
  "timeStamp": "2017-04-12T04:49:06Z"
}

Create Campaign

To create a new Campaign, make a POST call with the Campaign object payload. The response will be the newly created Campaign.

Example Request

POST https://dspapi.admanagerplus.yahoo.com/traffic/campaigns

Example Payload

{
  "name": "test_order_1234",
  "startDate": "2018-03-10",
  "endDate": "2018-03-15",
  "budget": 10,
  "dailyBudget": 3,
  "dailyBudgetType": "AUTO_ALLOCATED",
  "goalType": "CTR",
  "goalValue": 0,
  "accountId": 8338,
  "currency": "USD",
  "status": "ACTIVE",
  "frequencyCapValue": 10,
  "frequencyCapPeriodType": "DAILY",
  "timezone": "Etc/GMT",
  "demoVendor": "COMSCORE"
}

Example Response

{
  "response": {
    "status": "ACTIVE",
    "dailyBudgetType": "AUTO_ALLOCATED",
    "goalType": "CTR",
    "frequencyCapPeriodType": "DAILY",
    "id": 294403,
    "name": "test_order_1234",
    "createdAt": "2017-04-14T05:09:01Z",
    "startDate": "2018-03-10T05:00:00Z",
    "endDate": "2018-03-15T04:00:00Z",
    "updatedAt": "2017-04-14T05:09:01Z",
    "goalValue": 0,
    "frequencyCapValue": 10,
    "timezoneId": "Etc/GMT",
    "currency": "USD",
    "accountId": 8338,
    "budget": 10,
    "dailyBudget": 3,
    "demoVendor": "COMSCORE"
  },
  "errors": null,
  "timeStamp": "2017-04-12T04:49:06Z"
}

Delete Campaign

Campaign deletion is not supported by the API.