CreateOrUpdateCampaign
Creates a campaign with the specified parameters, or changes the parameters of an existing campaign.
Disabled method. Use version 5 of the API.
For information about the compatibility of methods between versions 4 and 5, see the Migration guide.
For a method, there is a version of GetCampaignsList (Live).
Restrictions
For editing campaigns, no more than 100 calls per day per campaign. For creating campaigns, no more than 100 calls per day.
Input data
The input data structure in JSON is shown below.
{
"method": "CreateOrUpdateCampaign",
"param": {
/* CampaignInfo */
"Login": (string),
"CampaignID": (int),
"Name": (string),
"FIO": (string),
"StartDate": (date),
"Strategy": {
/* CampaignStrategy */
"StrategyName": (string),
"MaxPrice": (float),
"AveragePrice": (float),
"WeeklySumLimit": (float),
"ClicksPerWeek": (int)
},
"SmsNotification": {
/* SmsNotificationInfo */
"MetricaSms": (string),
"ModerateResultSms": (string),
"MoneyInSms": (string),
"MoneyOutSms": (string),
"SmsTimeFrom": (string),
"SmsTimeTo": (string)
},
"EmailNotification": {
/* EmailNotificationInfo */
"Email": (string),
"WarnPlaceInterval": (int),
"MoneyWarningValue": (int),
"SendAccNews": (string),
"SendWarn": (string)
},
"StatusBehavior": (string),
"TimeTarget": {
/* TimeTargetInfo */
"ShowOnHolidays": (string),
"HolidayShowFrom": (int),
"HolidayShowTo": (int),
"DaysHours": [
{ /* TimeTargetItem */
"Hours": [
(int)
...
],
"Days": [
(int)
...
]
}
...
],
"TimeZone": (string)
},
"StatusContextStop": (string),
"ContextLimit": (string),
"ContextLimitSum": (int),
"ContextPricePercent": (int),
"AutoOptimization": (string),
"StatusMetricaControl": (string),
"DisabledDomains": (string),
"DisabledIps": (string),
"StatusOpenStat": (string),
"ConsiderTimeTarget": (string),
"MinusKeywords": [
(string)
...
],
"AddRelevantPhrases": (string),
"RelevantPhrasesBudgetLimit": (int),
}
}
Parameters are described below.
Parameter | Description | Required |
CampaignInfo object | ||
---|---|---|
Login | Login name of the campaign owner (username of the Yandex user that the ad campaign is run for). When creating a campaign, direct advertisers set their own Yandex username, while advertising agencies set their client's username. When getting campaign parameters, the username of the advertiser's chief representative is returned. | Yes |
CampaignID | The campaign ID. To create a campaign, it is set to 0; to change the parameters of an existing campaign, the campaign ID is specified. | Yes |
Name | The campaign name. | Yes |
FIO | First name and last name of the campaign owner. | Yes |
Strategy | Defines the display strategy on search. Contains the CampaignStrategy object with the strategy parameters. | Yes |
EmailNotification | The EmailNotificationInfo object with parameters for sending notifications by email. | Yes |
SmsNotification | The SmsNotificationInfo object with parameters for sending SMS notifications. To get notifications, you must subscribe to them (see the Help section Subscribe to SMS notifications). The phone number to send notifications to is taken from the user data (see the Help section Mobile numbers). | No |
StartDate | Date to start impressions, The date can be in the future. In this case, impressions begin on the specified date, if the moderator approved the ad and funds were transferred to the campaign balance. | No |
StatusBehavior | Enable behavioral targeting — Yes / No. The predefined value is Yes. | No |
TimeTarget | The TimeTargetInfo object with time targeting parameters. | No |
StatusContextStop | Do not use keywords in the Yandex Advertising Network that were disabled on the search for a low CTR — Yes/No. The predefined value is No (when a keyword is disabled on the search, it continues being used in the Yandex Advertising Network). Restriction. This parameter is no longer relevant for new keywords, since keywords are no longer excluded for a low CTR. | No |
ContextLimit | Budget limit for impressions in the Yandex Advertising Network:
| No |
ContextLimitSum | Maximum percentage of the budget to be spent on displaying ads in the Yandex Advertising Network. The value must be a multiple of ten or equal to zero: 0, 10, 20... 100. When the value is 0, impressions are disabled in the Yandex Advertising Network. The predefined NULL value does not put any restrictions on the budget, which is the same as setting Default in the ContextLimit parameter. | No |
ContextPricePercent | Maximum bid in the Yandex Advertising Network, as a percentage of the bid on search. The value is a multiple of ten: 10, 20... 100. The predefined value is 100. | No |
AutoOptimization | Enable automatic keyword optimization — Yes/No. The predefined value is No. | No |
StatusMetricaControl | Stop displays when the advertiser's web site is not available — Yes/No. Availability is detected by the results of monitoring performed by Yandex Direct. | No |
DisabledDomains | List of display places where the ad shouldn't be displayed:
Maximum of 1000 display places. Values are comma-separated. For example, | No |
DisabledIps | List of IP addresses that campaign ads should not be shown to. Addresses are separated by commas, such as | No |
StatusOpenStat | When redirecting to the advertiser's web site, append an OpenStat tag to the URL — Yes/No. The predefined value is No. | No |
ConsiderTimeTarget | When calculating the price for the display position, ignore bids in competitors' ads that are currently stopped by their schedule — Yes/No. The predefined value is No (all ads are factored into the calculation). | No |
MinusKeywords | Array of negative keywords that are shared by all the keywords of a campaign. A keyword should be specified without the minus sign before the first word. Maximum of 7 words per keyword. The maximum length of each word is 35 characters. The maximum combined length of negative keywords in the array is 20,000 characters. The “!” operator or “+” operator before a word is not included in the total length. | No |
AddRelevantPhrases | Add additional relevant keywords to ads — Yes/No. | No |
RelevantPhrasesBudgetLimit | Maximum percent of the budget to be spent on clicks on additional relevant keywords. The value is a multiple of ten: 10, 20, ..., 100. The predefined value is 100. | No |
CampaignStrategy object | ||
StrategyName | Name of the bid management strategy. Strategies with manual control:
Automatic strategies:
Two additional manual strategies can be set, but their parameters cannot be configured via the API (only via the web interface):
The last two strategies are set up via the Yandex Direct web interface. However, either of their names may be present in the response from the GetCampaignsParams method, or be input to the CreateOrUpdateCampaign method. In this case, the API does not change the parameters that were set in the web interface for these strategies. | Yes |
MaxPrice | Maximum bid. Can be set for the WeeklyBudget and WeeklyPacketOfClicks strategies. | No |
AveragePrice | Average bid for the AverageClickPrice strategy. Can also be set for the WeeklyPacketOfClicks strategy. | For the AverageClickPrice strategy |
WeeklySumLimit | Maximum weekly budget for the WeeklyBudget strategy. Can also be set for the AverageClickPrice strategy. | For the WeeklyBudget strategy |
ClicksPerWeek | Number of clicks per week for the WeeklyPacketOfClicks strategy. | For the WeeklyPacketOfClicks strategy |
SmsNotificationInfo object | ||
MetricaSms | Notify of Yandex Metrica site monitoring results — Yes/No. | No |
ModerateResultSms | Notify of ad moderation results — Yes/No. | No |
MoneyInSms | Notify when funds are credited to the campaign balance — Yes/No. The predefined value is No. When the client has the shared account enabled, it returns the value of the corresponding parameter for the shared account. | No |
MoneyOutSms | Notify when the campaign balance is out of funds — Yes/No. The predefined value is No. When the client has the shared account enabled, it returns the value of the corresponding parameter for the shared account. | No |
SmsTimeFrom | The allowed starting time for sending SMS notifications of campaign events. Specified in the format HH:MM; minutes are set in multiples of 15 (0, 15, 30, 45). For example, “19:45”. | No |
SmsTimeTo | The ending time for sending SMS notifications of campaign events. Specified in the format HH:MM; minutes are set in multiples of 15 (0, 15, 30, 45). For example, “19:45”. | No |
EmailNotificationInfo object | ||
Email | The email address for sending notifications of campaign events. | Yes |
WarnPlaceInterval | How often to check the position of ads: every 15, 30, or 60 minutes. Notification is sent if the ad moved to a lower position than the one that the bid covered when it was set up. | Yes |
MoneyWarningValue | The minimal balance; notification is sent when the account balance is reduced to this amount. Set as a percentage of the amount of the last payment. The predefined value is 20. When the client has the shared account enabled, it returns the value of the corresponding parameter for the shared account. | Yes |
SendAccNews | Notify of campaign events — Yes/No. It is set for campaigns that have a personal Yandex manager. The predefined value is No. | No |
SendWarn | Whether to send email notifications — Yes/No. The predefined value is No. | No |
TimeTargetInfo object | ||
ShowOnHolidays | Show ads on holiday non-work days — Yes/No (does not include normal Saturdays and Sundays). The predefined value is Yes. | No |
HolidayShowFrom | The time at which ads start being displayed on public holidays. If omitted, ads are displayed according to the schedule in the DaysHours parameter. | No |
HolidayShowTo | The time at which ads stop being displayed on public holidays. If omitted, ads are displayed according to the schedule in the DaysHours parameter. | No |
DaysHours | Array of TimeTargetItem objects that determines the schedule for ad displays (time targeting). | Yes |
TimeZone | Time zone where the ad campaign owner is located. To get the list of time zones, use the GetTimeZones method. | No |
TimeTargetItem object | ||
Hours | Array of integers from 0 to 23. The number 0 corresponds to the time interval from 00:00 to 00:59, the number 1 corresponds to the interval from 01:00 to 01:59, and so on. The predefined value is an array of the numbers from 0 to 23, which equals all 24 hours of the day. | Yes |
Days | Array of integers from 1 to 7. The number 1 corresponds to Monday, and 7 corresponds to Sunday. Ads are displayed on the specified days during the time set in the Hours parameter. The predefined value is an array of the numbers from 1 to 7, which equals a complete week. | Yes |
Parameter | Description | Required |
CampaignInfo object | ||
---|---|---|
Login | Login name of the campaign owner (username of the Yandex user that the ad campaign is run for). When creating a campaign, direct advertisers set their own Yandex username, while advertising agencies set their client's username. When getting campaign parameters, the username of the advertiser's chief representative is returned. | Yes |
CampaignID | The campaign ID. To create a campaign, it is set to 0; to change the parameters of an existing campaign, the campaign ID is specified. | Yes |
Name | The campaign name. | Yes |
FIO | First name and last name of the campaign owner. | Yes |
Strategy | Defines the display strategy on search. Contains the CampaignStrategy object with the strategy parameters. | Yes |
EmailNotification | The EmailNotificationInfo object with parameters for sending notifications by email. | Yes |
SmsNotification | The SmsNotificationInfo object with parameters for sending SMS notifications. To get notifications, you must subscribe to them (see the Help section Subscribe to SMS notifications). The phone number to send notifications to is taken from the user data (see the Help section Mobile numbers). | No |
StartDate | Date to start impressions, The date can be in the future. In this case, impressions begin on the specified date, if the moderator approved the ad and funds were transferred to the campaign balance. | No |
StatusBehavior | Enable behavioral targeting — Yes / No. The predefined value is Yes. | No |
TimeTarget | The TimeTargetInfo object with time targeting parameters. | No |
StatusContextStop | Do not use keywords in the Yandex Advertising Network that were disabled on the search for a low CTR — Yes/No. The predefined value is No (when a keyword is disabled on the search, it continues being used in the Yandex Advertising Network). Restriction. This parameter is no longer relevant for new keywords, since keywords are no longer excluded for a low CTR. | No |
ContextLimit | Budget limit for impressions in the Yandex Advertising Network:
| No |
ContextLimitSum | Maximum percentage of the budget to be spent on displaying ads in the Yandex Advertising Network. The value must be a multiple of ten or equal to zero: 0, 10, 20... 100. When the value is 0, impressions are disabled in the Yandex Advertising Network. The predefined NULL value does not put any restrictions on the budget, which is the same as setting Default in the ContextLimit parameter. | No |
ContextPricePercent | Maximum bid in the Yandex Advertising Network, as a percentage of the bid on search. The value is a multiple of ten: 10, 20... 100. The predefined value is 100. | No |
AutoOptimization | Enable automatic keyword optimization — Yes/No. The predefined value is No. | No |
StatusMetricaControl | Stop displays when the advertiser's web site is not available — Yes/No. Availability is detected by the results of monitoring performed by Yandex Direct. | No |
DisabledDomains | List of display places where the ad shouldn't be displayed:
Maximum of 1000 display places. Values are comma-separated. For example, | No |
DisabledIps | List of IP addresses that campaign ads should not be shown to. Addresses are separated by commas, such as | No |
StatusOpenStat | When redirecting to the advertiser's web site, append an OpenStat tag to the URL — Yes/No. The predefined value is No. | No |
ConsiderTimeTarget | When calculating the price for the display position, ignore bids in competitors' ads that are currently stopped by their schedule — Yes/No. The predefined value is No (all ads are factored into the calculation). | No |
MinusKeywords | Array of negative keywords that are shared by all the keywords of a campaign. A keyword should be specified without the minus sign before the first word. Maximum of 7 words per keyword. The maximum length of each word is 35 characters. The maximum combined length of negative keywords in the array is 20,000 characters. The “!” operator or “+” operator before a word is not included in the total length. | No |
AddRelevantPhrases | Add additional relevant keywords to ads — Yes/No. | No |
RelevantPhrasesBudgetLimit | Maximum percent of the budget to be spent on clicks on additional relevant keywords. The value is a multiple of ten: 10, 20, ..., 100. The predefined value is 100. | No |
CampaignStrategy object | ||
StrategyName | Name of the bid management strategy. Strategies with manual control:
Automatic strategies:
Two additional manual strategies can be set, but their parameters cannot be configured via the API (only via the web interface):
The last two strategies are set up via the Yandex Direct web interface. However, either of their names may be present in the response from the GetCampaignsParams method, or be input to the CreateOrUpdateCampaign method. In this case, the API does not change the parameters that were set in the web interface for these strategies. | Yes |
MaxPrice | Maximum bid. Can be set for the WeeklyBudget and WeeklyPacketOfClicks strategies. | No |
AveragePrice | Average bid for the AverageClickPrice strategy. Can also be set for the WeeklyPacketOfClicks strategy. | For the AverageClickPrice strategy |
WeeklySumLimit | Maximum weekly budget for the WeeklyBudget strategy. Can also be set for the AverageClickPrice strategy. | For the WeeklyBudget strategy |
ClicksPerWeek | Number of clicks per week for the WeeklyPacketOfClicks strategy. | For the WeeklyPacketOfClicks strategy |
SmsNotificationInfo object | ||
MetricaSms | Notify of Yandex Metrica site monitoring results — Yes/No. | No |
ModerateResultSms | Notify of ad moderation results — Yes/No. | No |
MoneyInSms | Notify when funds are credited to the campaign balance — Yes/No. The predefined value is No. When the client has the shared account enabled, it returns the value of the corresponding parameter for the shared account. | No |
MoneyOutSms | Notify when the campaign balance is out of funds — Yes/No. The predefined value is No. When the client has the shared account enabled, it returns the value of the corresponding parameter for the shared account. | No |
SmsTimeFrom | The allowed starting time for sending SMS notifications of campaign events. Specified in the format HH:MM; minutes are set in multiples of 15 (0, 15, 30, 45). For example, “19:45”. | No |
SmsTimeTo | The ending time for sending SMS notifications of campaign events. Specified in the format HH:MM; minutes are set in multiples of 15 (0, 15, 30, 45). For example, “19:45”. | No |
EmailNotificationInfo object | ||
Email | The email address for sending notifications of campaign events. | Yes |
WarnPlaceInterval | How often to check the position of ads: every 15, 30, or 60 minutes. Notification is sent if the ad moved to a lower position than the one that the bid covered when it was set up. | Yes |
MoneyWarningValue | The minimal balance; notification is sent when the account balance is reduced to this amount. Set as a percentage of the amount of the last payment. The predefined value is 20. When the client has the shared account enabled, it returns the value of the corresponding parameter for the shared account. | Yes |
SendAccNews | Notify of campaign events — Yes/No. It is set for campaigns that have a personal Yandex manager. The predefined value is No. | No |
SendWarn | Whether to send email notifications — Yes/No. The predefined value is No. | No |
TimeTargetInfo object | ||
ShowOnHolidays | Show ads on holiday non-work days — Yes/No (does not include normal Saturdays and Sundays). The predefined value is Yes. | No |
HolidayShowFrom | The time at which ads start being displayed on public holidays. If omitted, ads are displayed according to the schedule in the DaysHours parameter. | No |
HolidayShowTo | The time at which ads stop being displayed on public holidays. If omitted, ads are displayed according to the schedule in the DaysHours parameter. | No |
DaysHours | Array of TimeTargetItem objects that determines the schedule for ad displays (time targeting). | Yes |
TimeZone | Time zone where the ad campaign owner is located. To get the list of time zones, use the GetTimeZones method. | No |
TimeTargetItem object | ||
Hours | Array of integers from 0 to 23. The number 0 corresponds to the time interval from 00:00 to 00:59, the number 1 corresponds to the interval from 01:00 to 01:59, and so on. The predefined value is an array of the numbers from 0 to 23, which equals all 24 hours of the day. | Yes |
Days | Array of integers from 1 to 7. The number 1 corresponds to Monday, and 7 corresponds to Sunday. Ads are displayed on the specified days during the time set in the Hours parameter. The predefined value is an array of the numbers from 1 to 7, which equals a complete week. | Yes |
Output data
The method returns the ID of the created or edited campaign, as shown in the following example.
{
"data": 3193279
}
Examples of input data
Python
{
"Login":"agrom",
"CampaignID":3193279,
"Name":"Promotion of home appliances",
"FIO":"Alex Gromov",
"Strategy":{
"StrategyName":"WeeklyBudget",
"WeeklySumLimit":400,
"MaxPrice":8
},
"TimeTarget":{
"TimeZone":"Europe/Moscow",
"DaysHours":[
{
"Hours":[1,2,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23],
"Days":[1,2,3,4,5]
},
{
"Hours":[10,11,12,13,14,15,16,17,18,19,20],
"Days":[6,7]
}
],
"ShowOnHolidays":"Yes"
},
"StatusBehavior":"Yes",
"StatusContextStop":"No",
"ContextLimit":"Default",
"ContextLimitSum":30,
"ContextPricePercent":100,
"AutoOptimization":"Yes",
"StatusMetricaControl":"Yes",
"DisabledDomains": "domain1.ru,domain2.ru",
"DisabledIps": "64.234.23.21",
"StatusOpenStat":"No",
"ConsiderTimeTarget":"Yes",
"AddRelevantPhrases":"No",
"RelevantPhrasesBudgetLimit":100,
"MinusKeywords":[],
"SmsNotification":{
"SmsTimeFrom":"09:00",
"MoneyInSms":"Yes",
"SmsTimeTo":"21:00",
"MoneyOutSms":"Yes",
"ModerateResultSms":"Yes",
"MetricaSms":"Yes"
},
"EmailNotification":{
"MoneyWarningValue":20,
"SendAccNews":"Yes",
"WarnPlaceInterval":60,
"SendWarn":"Yes",
"Email":"agrom@yandex.ru"
}
}
PHP
array(
"Login" => "agrom",
"CampaignID" => 3193279,
"Name" => "Promotion of home appliances",
"FIO" => "Alex Gromov",
"Strategy" => array(
"StrategyName" => "WeeklyBudget",
"WeeklySumLimit" => 400,
"MaxPrice" => 8
),
"TimeTarget" => array(
"TimeZone" => "Europe/Moscow",
"DaysHours" => array(
array(
"Hours" => array(1,2,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23),
"Days" => array(1,2,3,4,5)
),
array(
"Hours" => array(10,11,12,13,14,15,16,17,18,19,20),
"Days" => array(6,7)
)
),
"ShowOnHolidays" => "Yes"
),
"StatusBehavior" => "Yes",
"StatusContextStop" => "No",
"ContextLimit" => "Default",
"ContextLimitSum" => 30,
"ContextPricePercent" => 100,
"AutoOptimization" => "Yes",
"StatusMetricaControl" => "Yes",
"DisabledDomains" => "domain1.ru,domain2.ru",
"DisabledIps" => "64.234.23.21",
"StatusOpenStat" => "No",
"ConsiderTimeTarget" => "Yes",
"AddRelevantPhrases" => "No",
"RelevantPhrasesBudgetLimit" => 100,
"MinusKeywords" => array(),
"SmsNotification" => array(
"SmsTimeFrom" => "09:00",
"MoneyInSms" => "Yes",
"SmsTimeTo" => "21:00",
"MoneyOutSms" => "Yes",
"ModerateResultSms" => "Yes",
"MetricaSms" => "Yes"
),
"EmailNotification" => array(
"MoneyWarningValue" => 20,
"SendAccNews" => "Yes",
"WarnPlaceInterval" => 60,
"SendWarn" => "Yes",
"Email" => "agrom@yandex.ru"
)
)
Perl
{
'Login' => 'agrom',
'CampaignID' => 3193279,
'Name' => 'Promotion of home appliances',
'FIO' => 'Alex Gromov',
'Strategy' => {
'StrategyName' => 'WeeklyBudget',
'WeeklySumLimit' => 400,
'MaxPrice' => 8
},
'TimeTarget' => {
'TimeZone' => 'Europe/Moscow',
'DaysHours' => [
{
'Hours' => [1,2,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23],
'Days' => [1,2,3,4,5]
},
{
'Hours' => [10,11,12,13,14,15,16,17,18,19,20],
'Days' => [6,7]
}
],
'ShowOnHolidays' => 'Yes'
},
'StatusBehavior' => 'Yes',
'StatusContextStop' => 'No',
'ContextLimit' => 'Default',
'ContextLimitSum' => 30,
'ContextPricePercent' => 100,
'AutoOptimization' => 'Yes',
'StatusMetricaControl' => 'Yes',
'DisabledDomains' => 'domain1.ru,domain2.ru',
'DisabledIps' => '64.234.23.21',
'StatusOpenStat' => 'No',
'ConsiderTimeTarget' => 'Yes',
'AddRelevantPhrases' => 'No',
'RelevantPhrasesBudgetLimit' => 100,
'MinusKeywords' => [],
'SmsNotification' => {
'SmsTimeFrom' => '09:00',
'MoneyInSms' => 'Yes',
'SmsTimeTo' => '21:00',
'MoneyOutSms' => 'Yes',
'ModerateResultSms' => 'Yes',
'MetricaSms' => 'Yes'
},
'EmailNotification' => {
'MoneyWarningValue' => 20,
'SendAccNews' => 'Yes',
'WarnPlaceInterval' => 60,
'SendWarn' => 'Yes',
'Email' => 'agrom@yandex.ru'
}
}