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: 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 when 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
totalBudgetType
  • SPECIFIED_AMOUNT - Put a cap on the total campaign budget. Must provide the total campaign budget in the budget field.
  • UNLIMITED - Indicate unlimited campaign budget.
text Required Optional
budget Total campaign budget amount. (1): Required when totalBudgetType is SPECIFIED_AMOUNT. float Required (1) Optional
campaignStartDate Campaign start date in yyyy-MM-dd format. Note: Start time depends on the campaign’s time zone. text Required Optional
campaignEndDate 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 Required?
id Campaign ID integer Y

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

Example Request

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

Example Response

{
  "response": {
    "status": "ACTIVE",
    "totalBudgetType": "UNLIMITED",
    "dailyBudgetType": "TOTAL_BUDGET",
    "goalType": "CPA",
    "frequencyCapPeriodType": "UNLIMITED",
    "timezone": "America/New_York",
    "currency": "INR",
    "demoVendor": "COMSCORE",
    "campaignStartDate": "2016-11-08T05:00:00Z",
    "campaignEndDate": "2018-03-16T04:00:00Z",
    "id": 261340,
    "name": "budget test",
    "createdAt": "2016-11-08T00:03:36Z",
    "updatedAt": "2017-07-28T21:18:22Z",
    "goalValue": 1111,
    "frequencyCapValue": 0,
    "accountId": 8338,
    "budget": null,
    "dailyBudget": 123
  },
  "errors": null,
  "timeStamp": "2017-07-28T21:24:35Z"
}

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={query}
Name Description Type Required?
accountId Account or Advertiser ID integer Y
page Page number integer N
limit Total number of items to return. Maximum allowed value is 100. integer N
sort Column to sort by text N
dir Sort direction. Valid values: asc, desc text N
query Search term. Use url encoding conventions (i.e. a space should be replaced with a + or %20). text N

The response will be a list of matching Campaigns.

Example Request

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

Example Response

{
  "response": [
    {
      "status": "INACTIVE",
      "totalBudgetType": "SPECIFIED_AMOUNT",
      "dailyBudgetType": "TOTAL_BUDGET",
      "goalType": "ROAS",
      "frequencyCapPeriodType": "UNLIMITED",
      "timezone": "America/Halifax",
      "currency": "EUR",
      "demoVendor": "YAHOO",
      "campaignStartDate": "2015-12-04T04:00:00Z",
      "campaignEndDate": "2016-01-29T04:00:00Z",
      "id": 174746,
      "name": "4234",
      "createdAt": "2015-12-04T22:31:06Z",
      "updatedAt": "2016-06-25T00:49:16Z",
      "goalValue": 4,
      "frequencyCapValue": 0,
      "accountId": 8338,
      "budget": 342
    },
    {
      "status": "ENDED",
      "totalBudgetType": "SPECIFIED_AMOUNT",
      "dailyBudgetType": "TOTAL_BUDGET",
      "goalType": "ROAS",
      "frequencyCapPeriodType": "UNLIMITED",
      "timezone": "America/Halifax",
      "currency": "USD",
      "campaignStartDate": "2015-12-08T04:00:00Z",
      "campaignEndDate": "2015-12-31T04:00:00Z",
      "id": 175880,
      "name": "Karim Test",
      "createdAt": "2015-12-08T19:16:27Z",
      "updatedAt": "2017-01-05T04:40:37Z",
      "goalValue": 3,
      "frequencyCapValue": 0,
      "accountId": 8338,
      "budget": 100
    }
  ],
  "errors": null,
  "timeStamp": "2017-07-28T21:26:32Z"
}

Update Campaign

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

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

Example Request

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

Example Payload

{
  "totalBudgetType": "SPECIFIED_AMOUNT",
  "budget": 7440.7,
  "goalType": "CPA",
  "campaignEndDate": "2018-03-16"
}

Example Response

{
  "response": {
    "status": "ACTIVE",
    "totalBudgetType": "SPECIFIED_AMOUNT",
    "dailyBudgetType": "TOTAL_BUDGET",
    "goalType": "CPA",
    "frequencyCapPeriodType": "UNLIMITED",
    "timezone": "America/New_York",
    "currency": "INR",
    "demoVendor": "COMSCORE",
    "campaignStartDate": "2016-11-08T05:00:00Z",
    "campaignEndDate": "2018-03-16T04:00:00Z",
    "id": 261340,
    "name": "budget test",
    "createdAt": "2016-11-08T00:03:36Z",
    "updatedAt": "2017-07-28T21:40:45Z",
    "goalValue": 1111,
    "frequencyCapValue": 0,
    "accountId": 8338,
    "budget": 7440.7,
    "dailyBudget": 123
  },
  "errors": null,
  "timeStamp": "2017-07-28T21:40:45Z"
}

Create Campaign

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

Example Request

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

Example Payload

{
  "name": "test budget3",
  "campaignStartDate": "2018-03-10",
  "campaignEndDate": "2018-03-16",
  "totalBudgetType": "UNLIMITED",
  "budget": null,
  "dailyBudget": 3,
  "dailyBudgetType": "TOTAL_BUDGET",
  "goalType": "CTR",
  "goalValue": 0,
  "accountId": 7987,
  "currency": "USD",
  "status": "ACTIVE",
  "frequencyCapValue": 10,
  "frequencyCapPeriodType": "DAILY",
  "timezone": "America/Los_Angeles"
}

Example Response

{
  "response": {
    "status": "ACTIVE",
    "totalBudgetType": "UNLIMITED",
    "dailyBudgetType": "TOTAL_BUDGET",
    "goalType": "CTR",
    "frequencyCapPeriodType": "DAILY",
    "timezone": "America/Los_Angeles",
    "currency": "USD",
    "campaignStartDate": "2018-03-10T08:00:00Z",
    "campaignEndDate": "2018-03-16T07:00:00Z",
    "id": 333251,
    "name": "test budget3",
    "createdAt": "2017-07-28T20:41:14Z",
    "updatedAt": "2017-07-28T20:41:14Z",
    "goalValue": 0,
    "frequencyCapValue": 10,
    "accountId": 7987,
    "budget": null,
    "dailyBudget": 3
  },
  "errors": null,
  "timeStamp": "2017-07-28T20:41:14Z"
}

Delete Campaign

Campaign deletion is not supported by the API.