Campaigns¶
Overview¶
A campaign is an advertising goal that defines a strategy for delivering ads within a set time period. You set up a campaign by defining its flight dates, budgets, frequency caps, demographic targeting data provider, and campaign goals.
Every campaign belongs to a specific advertiser and inherits default settings (time zone, currency, etc.) from the advertiser-level settings. Campaign flight dates, frequency caps, and budget settings constrain line-level settings.
You can set one of the following campaign budget types:
- A single budget that applies to all lines in the campaign as defined by the
dailyBudgetType
,dailyBudget
,totalBudgetType
,budget
,campaignStartDate
, andcampaignEndDate
. - Multiple budget schedules apply to the lines under the campaign as defined in the
budgetSchedules
array.
Hierarchy¶
A Campaign
is an advertiser-level object.
Endpoint¶
/traffic/campaigns
Use the following HTTP methods:
- Use the
GET
method to view a campaign. - Use the
POST
method to create a new campaign. - Use the
PUT
method to update an existing campaign.
Resources¶
Campaign¶
The Campaign
object contains the following fields:
Field | Description | Data Type | Create | Update |
---|---|---|---|---|
id |
Specifies the campaign ID. | integer |
N/A | Required |
name |
Specifies the unique campaign name. | string |
Required | Optional |
status |
Specifies the current status of the campaign. Allowed values:
In addition, the resource may return the following read-only status values:
|
string |
Required | Optional |
goalType |
Specifies the campaign KPI. Options include:
|
string |
Required | Optional |
goalValue |
Specifies the target value for the Note: If |
number |
Required | Optional |
frequencyCapPeriodType |
Specifies the frequency capping method. Options include:
Defaults to |
string |
Optional | Optional |
frequencyCapValue |
Specifies the maximum number of impressions to serve per Defaults to |
number |
Optional | Optional |
demoVendor |
Specifies the demographic targeting data provider for video campaigns. The Verizon Media DSP uses Yahoo and third-party data verification vendors to provide targeting verification when you set up demographic targeting for video ads. Options include:
Important: You cannot change this value on an active campaign. Defaults to |
string |
Optional | Optional |
timezone |
Specifies the campaign time zone. Uses the advertiser’s time zone if you do not specify a value. To learn more, see Timezones. Some example values: Note: Once a campaign is saved, you cannot update the |
string |
Optional | Optional |
currency |
Specifies the campaign currency. Uses the advertiser’s currency if you do not specify a value. To learn more, see Currency Types. Some example values: Note: Once a campaign is saved, you cannot update the |
string |
Optional | Optional |
accountId |
Specifies the advertiser ID. To learn more, see Advertisers. |
integer |
Required | Optional |
budgetSchedules |
Specifies an array of Budget Schedule objects. A Budget Schedule defines a budget you can use when you set up lines under the campaign. To learn more, see Budget Schedule Object. Once you set up budget schedules, you cannot remove them from a campaign. Budget schedule date ranges cannot overlap. |
array |
Optional | Optional |
dailyBudgetType |
Specifies the daily budget type. Options include:
Important: If you define the Defaults to |
string |
Optional | Optional |
dailyBudget |
Specifies the daily budget. Important: If you define the Required if |
number |
Optional | Optional |
totalBudgetType |
Specifies the total budget type. Options include:
Important: If you define the Defaults to |
string |
Optional | Optional |
budget |
Specifies the total budget for the campaign. Important: If you define the Required if the |
number |
Optional | Optional |
campaignStartDate |
Specifies the beginning of the campaign in Important: If you define the Note: The start time depends on the campaign’s time zone. Required if a single budget is defined for the campaign. |
string |
Optional | Optional |
campaignEndDate |
Specifies the end of the campaign in Important: If you define the |
string |
Optional | Optional |
Budget Schedule Object¶
A Budget Schedule is a campaign-level budget you can define. Budget schedules are useful if you want to run evergreen lines instead of having to continually define new lines every time your lines end.
The campaign
object’s budgetSchedules
array defines one or more Budget Schedule objects.
If you specify the budgetSchdule
object attributes, omit the campaign
object’s dailyBudget
, dailyBudgetType
, totalBudgetType
, and budget
attributes; or set them to null.
Important
Once you specify budget schedules, you cannot remove them from a campaign. Budget schedule date ranges cannot overlap.
Field | Description | Data Type | Create | Update |
---|---|---|---|---|
id |
Specifies the budget schedule ID. | integer |
N/A | Required |
scheduleName |
Specifies a unique name for the budget schedule. | string |
Required | Optional |
startDate |
Specifies the beginning of the budget schedule in yyyy-MM-dd format. |
string |
Required | Required |
endDate |
Specifies the ending of the budget schedule in yyyy-MM-dd format. |
string |
Required | Required |
scheduleBudgetType |
Specifies the method used to allocate spending in the budget schedule. Options include:
|
string |
Required | Required |
scheduleBudget |
Specifies the total budget for the budget schedule. | string |
Required | Optional |
scheduleDailyBudget |
Specifies the daily budget for the budget schedule. Required if the |
string |
Optional | Optional |
View Campaign¶
Get data for a specific campaign.
GET /traffic/campaigns/{id}
Parameters¶
Parameter | Parameter Type | Description | Data Type | Required |
---|---|---|---|---|
id |
path | Specifies the campaign ID. | integer |
Y |
Example Request URL¶
GET https://dspapi.admanagerplus.yahoo.com/traffic/campaigns/364677
Example Response¶
{
"response": {
"status": "NOT_STARTED",
"totalBudgetType": "SPECIFIED_AMOUNT",
"dailyBudgetType": "TOTAL_BUDGET",
"goalType": "CPA",
"frequencyCapPeriodType": "DAILY",
"timezone": "America/Los_Angeles",
"currency": "USD",
"campaignStartDate": "2018-03-10T08:00:00Z",
"campaignEndDate": "2018-03-16T07:00:00Z",
"id": 364677,
"name": "test budget3",
"createdAt": "2017-09-21T20:45:50Z",
"updatedAt": "2017-09-28T23:01:34Z",
"goalValue": 0,
"frequencyCapValue": 10,
"accountId": 1356341,
"budget": 7440.7,
"dailyBudget": 3
},
"errors": null,
"timeStamp": "2018-12-20T17:42:56Z"
}
View Campaigns¶
Get a filtered list of campaigns.
GET /traffic/campaigns?accountId={accountId}&query={query}&page={page}&limit={limit}&sort={sort}&dir={dir}
All of the following parameters are query parameters.
Parameters¶
Parameter | Description | Data Type | Required |
---|---|---|---|
accountId |
Specifies the advertiser ID. | integer |
Y |
query |
Specifies the search term to use for filtering an advertiser’s campaigns. Use URL encoding conventions (i.e. replace spaces with a |
string |
N |
page |
Specifies the page number. | integer |
N |
limit |
Specifies the total number of items to return. Maximum allowed value is 100 . |
integer |
N |
sort |
Specifies the column to sort by. | string |
N |
dir |
Specifies the sort direction. Allowed values:
|
string |
N |
Example Request URL¶
GET https://dspapi.admanagerplus.yahoo.com/traffic/campaigns?accountId=1356341&query=test&page=1&limit=2
Example Response¶
{
"response": [
{
"status": "INACTIVE",
"totalBudgetType": "SPECIFIED_AMOUNT",
"dailyBudgetType": "TOTAL_BUDGET",
"goalType": "CTR",
"frequencyCapPeriodType": "UNLIMITED",
"timezone": "America/New_York",
"currency": "CHF",
"demoVendor": "YAHOO",
"campaignStartDate": "2017-06-28T04:00:00Z",
"id": 319128,
"name": "testBudget",
"createdAt": "2017-06-27T17:43:44Z",
"updatedAt": "2017-06-27T17:43:44Z",
"goalValue": 0,
"frequencyCapValue": 0,
"accountId": 311375,
"budget": 2
},
{
"status": "INACTIVE",
"goalType": "CTR",
"frequencyCapPeriodType": "UNLIMITED",
"timezone": "America/Los_Angeles",
"currency": "USD",
"demoVendor": "YAHOO",
"budgetSchedules": [
{
"scheduleBudget": 100.01,
"scheduleDailyBudget": 6.12,
"scheduleBudgetType": "SPECIFIED_AMOUNT",
"scheduleName": "schedule1",
"startDate": "2018-12-22T08:00:00Z",
"endDate": "2018-12-27T08:00:00Z",
"id": 695833
},
{
"scheduleBudget": 22.02,
"scheduleBudgetType": "TOTAL_BUDGET",
"scheduleName": "schedule2",
"startDate": "2018-12-28T08:00:00Z",
"endDate": "2018-12-30T08:00:00Z",
"id": 695834
},
{
"scheduleBudget": 140,
"scheduleBudgetType": "AUTO_ALLOCATED",
"scheduleName": "schedule3",
"startDate": "2019-01-01T08:00:00Z",
"endDate": "2019-01-05T08:00:00Z",
"id": 695835
}
],
"id": 661249,
"name": "multiple budget schedule test",
"createdAt": "2018-10-19T18:31:28Z",
"updatedAt": "2018-12-19T20:19:27Z",
"goalValue": 0,
"frequencyCapValue": 0,
"accountId": 311375,
"budget": null
}
],
"errors": null,
"timeStamp": "2018-12-19T20:19:57Z"
}
Create Campaign¶
Create a new campaign.
POST /traffic/campaigns
Parameters¶
All fields are specified in the body of the application/json payload.
Example Request URL¶
POST https://dspapi.admanagerplus.yahoo.com/traffic/campaigns
Example Request Body (Single Schedule)¶
{
"name": "test budget 4",
"campaignStartDate": "2018-12-24",
"campaignEndDate": "2018-12-27",
"totalBudgetType": "UNLIMITED",
"budget": null,
"dailyBudget": 3,
"dailyBudgetType": "TOTAL_BUDGET",
"goalType": "CTR",
"goalValue": 0,
"accountId": 1356341,
"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",
"demoVendor": "YAHOO",
"campaignStartDate": "2018-12-24T08:00:00Z",
"campaignEndDate": "2018-12-27T08:00:00Z",
"id": 696162,
"name": "test budget 4",
"createdAt": "2018-12-20T18:22:16Z",
"updatedAt": "2018-12-20T18:22:16Z",
"goalValue": 0,
"frequencyCapValue": 10,
"accountId": 1356341,
"budget": null,
"dailyBudget": 3
},
"errors": null,
"timeStamp": "2018-12-20T18:22:16Z"
}
Example Request Body (Multi Schedule)¶
{
"name": "test budget 22",
"campaignStartDate": "2018-12-24",
"budgetSchedules": [
{
"scheduleBudget": 100.01,
"scheduleBudgetType": "SPECIFIED_AMOUNT",
"scheduleDailyBudget": 6.12,
"startDate": "2018-12-22",
"endDate": "2019-02-26",
"scheduleName": "schedule1"
},
{
"scheduleBudget": 22.02,
"scheduleBudgetType": "TOTAL_BUDGET",
"startDate": "2019-02-27",
"endDate": "2019-02-28",
"scheduleName": "schedule2"
},
{
"scheduleBudget": 140,
"scheduleBudgetType": "AUTO_ALLOCATED",
"startDate": "2019-03-01",
"endDate": "2019-03-05",
"scheduleName": "schedule3"
}
],
"goalType": "CTR",
"goalValue": 5,
"accountId": 1356341,
"status": "ACTIVE",
"frequencyCapValue": 10,
"frequencyCapPeriodType": "DAILY",
"timezone": "America/Chicago",
"currency": "CAD",
"demoVendor": "COMSCORE",
"budget": 432.6
}
Example Response¶
{
"response": {
"id": 748390,
"name": "test budget 22",
"createdAt": "2019-02-16T00:45:15Z",
"updatedAt": "2019-02-16T00:45:15Z",
"goalValue": 5,
"frequencyCapValue": 10,
"accountId": 1356341,
"status": "ACTIVE",
"goalType": "CTR",
"timezone": "America/Chicago",
"currency": "CAD",
"demoVendor": "COMSCORE",
"budgetSchedules": [
{
"id": 749323,
"startDate": "2018-12-22T06:00:00Z",
"endDate": "2019-02-26T06:00:00Z",
"scheduleBudget": 100.01,
"scheduleDailyBudget": 6.12,
"scheduleBudgetType": "SPECIFIED_AMOUNT",
"scheduleName": "schedule1"
},
{
"id": 749325,
"startDate": "2019-03-01T06:00:00Z",
"endDate": "2019-03-05T06:00:00Z",
"scheduleBudget": 140,
"scheduleBudgetType": "AUTO_ALLOCATED",
"scheduleName": "schedule3"
},
{
"id": 749324,
"startDate": "2019-02-27T06:00:00Z",
"endDate": "2019-02-28T06:00:00Z",
"scheduleBudget": 22.02,
"scheduleBudgetType": "TOTAL_BUDGET",
"scheduleName": "schedule2"
}
],
"frequencyCapPeriodType": "DAILY"
},
"errors": null,
"timeStamp": "2019-02-16T00:45:19.783Z"
}
Update Campaign¶
Update an existing campaign.
PUT /traffic/campaigns/{id}
Partial updates are supported; values of supported fields that are not in the payload remain unchanged.
Parameters¶
Specify the Campaign id in the url path. Specify all other fields in the body of the application/json payload.
Example Request URL¶
PUT https://dspapi.admanagerplus.yahoo.com/traffic/campaigns/696153
Example Request Body (Single Schedule)¶
{
"totalBudgetType": "SPECIFIED_AMOUNT",
"budget": 7440.7,
"goalType": "CPA",
"campaignEndDate": "2018-03-16"
}
Example Request Body (Multi Schedule)¶
{
"budgetSchedules": [
{
"scheduleBudget": 140.01,
"scheduleDailyBudget": 6.55,
"scheduleBudgetType": "SPECIFIED_AMOUNT",
"scheduleName": "schedule1-updated",
"startDate": "2018-12-22",
"endDate": "2018-12-27",
"id": 695833
}
]
}
Example Response¶
{
"response": {
"status": "ACTIVE",
"goalType": "CTR",
"frequencyCapPeriodType": "DAILY",
"timezone": "America/Los_Angeles",
"currency": "USD",
"demoVendor": "YAHOO",
"budgetSchedules": [
{
"scheduleBudget": 22.02,
"scheduleBudgetType": "TOTAL_BUDGET",
"scheduleName": "schedule2",
"startDate": "2018-12-28T08:00:00Z",
"endDate": "2018-12-30T08:00:00Z",
"id": 695834
},
{
"scheduleBudget": 140,
"scheduleBudgetType": "AUTO_ALLOCATED",
"scheduleName": "schedule3",
"startDate": "2019-01-01T08:00:00Z",
"endDate": "2019-01-05T08:00:00Z",
"id": 695835
},
{
"scheduleBudget": 140.01,
"scheduleDailyBudget": 6.55,
"scheduleBudgetType": "SPECIFIED_AMOUNT",
"scheduleName": "schedule1-updated",
"startDate": "2018-12-22T08:00:00Z",
"endDate": "2018-12-27T08:00:00Z",
"id": 695833
}
],
"id": 696153,
"name": "test budget 56747",
"createdAt": "2018-12-20T02:36:59Z",
"updatedAt": "2018-12-20T17:53:12Z",
"goalValue": 0,
"frequencyCapValue": 10,
"accountId": 1356341,
"budget": null
},
"errors": null,
"timeStamp": "2018-12-20T17:53:13Z"
}
Delete Campaign¶
The DSP Traffic API does not support the deletion of campaigns.