add. Yandex Direct API. Version 5

add

Creates campaigns.

Attention. All monetary campaign parameters (daily budget, weekly budget, and average price for automatic strategies) are passed via the Yandex Direct API as integer numbers. The passed value is a monetary value in the advertiser's currency, multiplied by 1,000,000.

Restrictions

To get the limit on the number of campaigns for an advertiser, use the method Clients.get or AgencyClients.get (see the CAMPAIGNS_TOTAL_PER_CLIENT and CAMPAIGNS_UNARCHIVED_PER_CLIENT elements in the Restrictions array).

Maximum of 10 campaigns per method call.

Request

Request structure in JSON format:

{
  "method": "add",
  "params": { /* params */
    "Campaigns": [{  /* CampaignAddItem */
      "ClientInfo": (string),
      "Notification": {  /* Notification */
        "SmsSettings": {  /* SmsSettings */
          "Events": [( "MONITORING" | ... | "FINISHED" ), ... ],
          "TimeFrom": (string),
          "TimeTo": (string)
        },
        "EmailSettings": {  /* EmailSettings */
          "Email": (string),
          "CheckPositionInterval": (int),
          "WarningBalance": (int),
          "SendAccountNews": ( "YES" | "NO" ),
          "SendWarnings": ( "YES" | "NO" )
        }
      },
      "TimeZone": (string),
      "Name": (string), /* required */
      "StartDate": (string), /* required */
      "DailyBudget": {  /* DailyBudget */
        "Amount": (long), /* required */
        "Mode": ( "STANDARD" | "DISTRIBUTED" ) /* required */
      },
      "EndDate": (string),
      "NegativeKeywords": {  /* ArrayOfString */
        "Items": [(string), ... ] /* required */
      },
      "BlockedIps": {  /* ArrayOfString */
        "Items": [(string), ... ] /* required */
      },
      "ExcludedSites": {  /* ArrayOfString */
        "Items": [(string), ... ] /* required */
      },
      "TextCampaign": {  /* TextCampaignAddItem */
        ... text campaign params ...
      },
      "MobileAppCampaign": {  /* MobileAppCampaignAddItem */
        ... mobile app campaign params ...
      },
      "DynamicTextCampaign": {  /* DynamicTextCampaignAddItem */
        ... dynamic text campaign params ...
      },
      "CpmBannerCampaign": {  /* CpmBannerCampaignAddItem */
        ... cpm banner campaign params ...
      },
      "SmartCampaign": {  /* SmartCampaignAddItem */
        ... smart campaign params ...
      },
      "UnifiedCampaign": {  /* UnifiedCampaignAddItem */
        ... unified campaign params ...
      },
      "TimeTargeting": {  /* TimeTargetingAdd */
        "Schedule": {  /* ArrayOfString */
          "Items": [(string), ... ] /* required */
        },
        "ConsiderWorkingWeekends": ( "YES" | "NO" ), /* required */
        "HolidaysSchedule": {  /* TimeTargetingOnPublicHolidays */
          "SuspendOnHolidays": ( "YES" | "NO" ), /* required */
          "BidPercent": (int),
          "StartHour": (int),
          "EndHour": (int)
        }
      }
    }, ...] /* required */
  }
}


Params structure (for JSON) / AddRequest structure (for SOAP)
Parameter	Type	Description	Required
`Campaigns`	array of CampaignAddItem	Campaigns to add.	Yes
CampaignAddItem structure
`ClientInfo`	string	Client name (maximum of 255 characters). The default value is the name from the advertiser's settings. Can't be set for UnifiedCampaign.	No
`Notification`	Notification	Settings for SMS and email notifications.	No
`TimeZone`	string	Time zone of the advertiser's location. Use the Dictionaries.get method to get a reference list of time zones. The default value is Europe/Moscow.	No
`Name`	string	Campaign name (maximum of 255 characters).	Yes
`StartDate`	string	Start date for displaying ads, in the format YYYY-MM-DD. Can't be earlier than the current date. Ad displays begin at 00:00 Moscow time (regardless of the TimeZone parameter). The start time for displays is affected by the time targeting settings (the TimeTargeting parameter). Ad displays are possible only if at least one ad has passed review and funds have been credited to the campaign or shared account. If you set a budget for a custom period for the campaign, the value in this field is ignored, and the strategy period is prioritized instead.	Yes
`DailyBudget`	DailyBudget	Settings for the daily budget of a campaign. Daily budget management is available if a manual display strategy is selected in the campaign. Otherwise, an attempt to set the daily budget results in an error.	No
`EndDate`	string	End date for displaying ads, in the format YYYY-MM-DD. Ad impressions end at 24:00 Moscow time (regardless of the TimeZone parameter).	No
`NegativeKeywords`	ArrayOfString	Array of negative keywords that are shared by all the keywords of a campaign. Restriction. This parameter is not supported for campaigns with the “Display campaign” type. 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. Spaces, dashes, and operators are not counted as part of the total length.	No
`BlockedIps`	ArrayOfString	Array of IP addresses that campaign ads should not be shown to. Maximum of 25 items in the array.	No
`ExcludedSites`	ArrayOfString	Array of display places where the ad shouldn't be displayed: Domain names of websites. IDs of mobile apps (the bundle ID for iOS, or the package name for Android). Names of ad exchanges (SSPs). You can get a list of names using the Dictionaries.get method. Maximum of 1000 items in the array. Maximum of 255 characters per array item.	No
`TextCampaign`	TextCampaignAddItem	Settings for campaigns with the “Text & Image ads” type. For a data structure description, see add: TextCampaign parameters.	Either TextCampaign, MobileAppCampaign, DynamicTextCampaign, or CpmBannerCampaign, or SmartCampaign
`MobileAppCampaign`	MobileAppCampaignAddItem	Settings for “Ads for mobile apps” campaigns. For a data structure description, see add: MobileAppCampaign parameters.
`DynamicTextCampaign`	DynamicTextCampaignAddItem	Settings for campaigns with the “Dynamic ads” type. For a data structure description, see add: DynamicTextCampaign parameters.
`CpmBannerCampaign`	CpmBannerCampaignAddItem	Settings for the “Display campaign” type. For a data structure description, see add: CpmBannerCampaign parameters.
`SmartCampaign`	SmartCampaignAddItem	Settings for “Smart banners” campaigns. For a data structure description, see add: SmartCampaign parameters.
`UnifiedCampaign`	UnifiedCampaignAddItem	Settings for campaigns with the “Unified performance campaign” type. For a data structure description, see add: UnifiedCampaign parameters.
`TimeTargeting`	TimeTargetingAdd	Settings for time targeting and hourly bid adjustments. Specified for the time zone set in the TimeZone parameter.	No
Notification structure
`SmsSettings`	SmsSettings	Settings for sending SMS notifications. The phone number to send notifications to is taken from the advertiser's Yandex profile (see My numbers in the Yandex Passport Help). Can't be set for UnifiedCampaign.	No
`EmailSettings`	EmailSettings	Settings for sending email notifications.	No
SmsSettings structure
`Events`	array of SmsEventsEnum	Events to notify of by SMS: MONITORING — Pausing and resuming ad displays by site availability monitoring using Metrica data. MODERATION — Ads accepted or rejected after review. MONEY_IN — Funds deposited to the campaign balance (not used when a shared account is enabled). MONEY_OUT — Funds used up on the campaign balance (not used when a shared account is enabled). FINISHED — End of the campaign.	No
`TimeFrom`	string	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. The default value is 9:00.	No
`TimeTo`	string	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. The default value is 21:00.	No
EmailSettings structure
`Email`	string	The email address for sending notifications of campaign events. The default value is the advertiser's address.	No
`CheckPositionInterval`	int	The frequency of checking the traffic forecast: 15, 30 or 60 minutes. The default value is 60. A notification is sent if the traffic forecast is lower than the one that the bid covered at the time of configuration. Can't be set for UnifiedCampaign.	No
`WarningBalance`	int	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, from 1 to 50. The default value is 20. If the client has the shared account enabled, this parameter is not used. Can't be set for UnifiedCampaign.	No
`SendAccountNews`	YesNoEnum	Whether to send notifications of events related to the campaign. It is set for campaigns that have a personal Yandex manager. For campaigns that are not handled by a personal manager, the passed value is ignored. The default value is NO.	No
`SendWarnings`	YesNoEnum	Whether to send email notifications. The default value is NO. Can't be set for UnifiedCampaign.	No
DailyBudget structure
`Amount`	long	The daily campaign budget in the advertiser currency, multiplied by 1,000,000. The minimum daily budget for each currency is listed in the currency reference. To get the list of currencies, use the Dictionaries.get method.	Yes
`Mode`	DailyBudgetModeEnum	Mode for displaying ads: STANDARD — standard DISTRIBUTED — distributed See the Average daily budget section under “Manual bid management” in the Help for Yandex Direct.	Yes
TimeTargetingAdd structure
`Schedule`	ArrayOfString	Settings for time targeting and hourly bid adjustments. Maximum of 7 items in the array. Each array item contains 25 comma-separated numbers. The first number is the number of the day of the week: from 1 (Monday) to 7 (Sunday). The next 24 numbers are a sequence of bid coefficients for displaying ads in the corresponding hours. Coefficients are specified as percentages from 0 to 200. The value must be a multiple of 10: If the coefficient is 0, no ads are served during this hour. Example of an array element: 1, 0, 0, 50, 50, 100, 100, 150, 200, 200, 150, 100, 100, 80, 70, 100, 100, 100, 50, 50, 40, 30, 0, 0, 0 Note. If the array is missing an element for one of the days of the week, all the bid coefficients are set to 100 for this day. If an automatic display strategy is selected, the coefficient 0 means displays are not allowed, and any other coefficient means displays are allowed (in other words, it is equivalent to 100).	No
`ConsiderWorkingWeekends`	YesNoEnum	Whether to change the display schedule when a work day is moved to Saturday or Sunday because of a public holiday. For example, if a work day is moved from Monday to Saturday and the value is YES, on the Saturday work day, ads are displayed according to the Monday schedule, and on the Monday holiday, they are displayed according to the Saturday schedule.	Yes
`HolidaysSchedule`	TimeTargetingOnPublicHolidays	Display settings on public holidays. If the time zone specified in the TimeZone parameter belongs to Russia, Ukraine, Belarus, Kazakhstan, or Turkey, we use the holiday calendar for the appropriate country. In all other cases, we use the Russian calendar.	No
TimeTargetingOnPublicHolidays structure
`SuspendOnHolidays`	YesNoEnum	Whether to suspend ads on public holidays: YES — suspend; NO — don't suspend. Note. The BidPercent, StartHour and EndHour parameters can only be set when SuspendOnHolidays has the value NO.	Yes
`BidPercent`	int	The bid coefficient for displays on public holidays. Specified as a percentage from 0 to 200. The value must be a multiple of 10.	No
`StartHour`	int	The time (in hours) to start displays on public holidays. From 0 to 23.	When the SuspendOnHolidays parameter has the value NO
`EndHour`	int	The time (in hours) to end displays on public holidays. From 0 to 24.	When the SuspendOnHolidays parameter has the value NO


Params structure (for JSON) / AddRequest structure (for SOAP)
Parameter	Type	Description	Required
`Campaigns`	array of CampaignAddItem	Campaigns to add.	Yes
CampaignAddItem structure
`ClientInfo`	string	Client name (maximum of 255 characters). The default value is the name from the advertiser's settings. Can't be set for UnifiedCampaign.	No
`Notification`	Notification	Settings for SMS and email notifications.	No
`TimeZone`	string	Time zone of the advertiser's location. Use the Dictionaries.get method to get a reference list of time zones. The default value is Europe/Moscow.	No
`Name`	string	Campaign name (maximum of 255 characters).	Yes
`StartDate`	string	Start date for displaying ads, in the format YYYY-MM-DD. Can't be earlier than the current date. Ad displays begin at 00:00 Moscow time (regardless of the TimeZone parameter). The start time for displays is affected by the time targeting settings (the TimeTargeting parameter). Ad displays are possible only if at least one ad has passed review and funds have been credited to the campaign or shared account. If you set a budget for a custom period for the campaign, the value in this field is ignored, and the strategy period is prioritized instead.	Yes
`DailyBudget`	DailyBudget	Settings for the daily budget of a campaign. Daily budget management is available if a manual display strategy is selected in the campaign. Otherwise, an attempt to set the daily budget results in an error.	No
`EndDate`	string	End date for displaying ads, in the format YYYY-MM-DD. Ad impressions end at 24:00 Moscow time (regardless of the TimeZone parameter).	No
`NegativeKeywords`	ArrayOfString	Array of negative keywords that are shared by all the keywords of a campaign. Restriction. This parameter is not supported for campaigns with the “Display campaign” type. 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. Spaces, dashes, and operators are not counted as part of the total length.	No
`BlockedIps`	ArrayOfString	Array of IP addresses that campaign ads should not be shown to. Maximum of 25 items in the array.	No
`ExcludedSites`	ArrayOfString	Array of display places where the ad shouldn't be displayed: Domain names of websites. IDs of mobile apps (the bundle ID for iOS, or the package name for Android). Names of ad exchanges (SSPs). You can get a list of names using the Dictionaries.get method. Maximum of 1000 items in the array. Maximum of 255 characters per array item.	No
`TextCampaign`	TextCampaignAddItem	Settings for campaigns with the “Text & Image ads” type. For a data structure description, see add: TextCampaign parameters.	Either TextCampaign, MobileAppCampaign, DynamicTextCampaign, or CpmBannerCampaign, or SmartCampaign
`MobileAppCampaign`	MobileAppCampaignAddItem	Settings for “Ads for mobile apps” campaigns. For a data structure description, see add: MobileAppCampaign parameters.
`DynamicTextCampaign`	DynamicTextCampaignAddItem	Settings for campaigns with the “Dynamic ads” type. For a data structure description, see add: DynamicTextCampaign parameters.
`CpmBannerCampaign`	CpmBannerCampaignAddItem	Settings for the “Display campaign” type. For a data structure description, see add: CpmBannerCampaign parameters.
`SmartCampaign`	SmartCampaignAddItem	Settings for “Smart banners” campaigns. For a data structure description, see add: SmartCampaign parameters.
`UnifiedCampaign`	UnifiedCampaignAddItem	Settings for campaigns with the “Unified performance campaign” type. For a data structure description, see add: UnifiedCampaign parameters.
`TimeTargeting`	TimeTargetingAdd	Settings for time targeting and hourly bid adjustments. Specified for the time zone set in the TimeZone parameter.	No
Notification structure
`SmsSettings`	SmsSettings	Settings for sending SMS notifications. The phone number to send notifications to is taken from the advertiser's Yandex profile (see My numbers in the Yandex Passport Help). Can't be set for UnifiedCampaign.	No
`EmailSettings`	EmailSettings	Settings for sending email notifications.	No
SmsSettings structure
`Events`	array of SmsEventsEnum	Events to notify of by SMS: MONITORING — Pausing and resuming ad displays by site availability monitoring using Metrica data. MODERATION — Ads accepted or rejected after review. MONEY_IN — Funds deposited to the campaign balance (not used when a shared account is enabled). MONEY_OUT — Funds used up on the campaign balance (not used when a shared account is enabled). FINISHED — End of the campaign.	No
`TimeFrom`	string	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. The default value is 9:00.	No
`TimeTo`	string	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. The default value is 21:00.	No
EmailSettings structure
`Email`	string	The email address for sending notifications of campaign events. The default value is the advertiser's address.	No
`CheckPositionInterval`	int	The frequency of checking the traffic forecast: 15, 30 or 60 minutes. The default value is 60. A notification is sent if the traffic forecast is lower than the one that the bid covered at the time of configuration. Can't be set for UnifiedCampaign.	No
`WarningBalance`	int	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, from 1 to 50. The default value is 20. If the client has the shared account enabled, this parameter is not used. Can't be set for UnifiedCampaign.	No
`SendAccountNews`	YesNoEnum	Whether to send notifications of events related to the campaign. It is set for campaigns that have a personal Yandex manager. For campaigns that are not handled by a personal manager, the passed value is ignored. The default value is NO.	No
`SendWarnings`	YesNoEnum	Whether to send email notifications. The default value is NO. Can't be set for UnifiedCampaign.	No
DailyBudget structure
`Amount`	long	The daily campaign budget in the advertiser currency, multiplied by 1,000,000. The minimum daily budget for each currency is listed in the currency reference. To get the list of currencies, use the Dictionaries.get method.	Yes
`Mode`	DailyBudgetModeEnum	Mode for displaying ads: STANDARD — standard DISTRIBUTED — distributed See the Average daily budget section under “Manual bid management” in the Help for Yandex Direct.	Yes
TimeTargetingAdd structure
`Schedule`	ArrayOfString	Settings for time targeting and hourly bid adjustments. Maximum of 7 items in the array. Each array item contains 25 comma-separated numbers. The first number is the number of the day of the week: from 1 (Monday) to 7 (Sunday). The next 24 numbers are a sequence of bid coefficients for displaying ads in the corresponding hours. Coefficients are specified as percentages from 0 to 200. The value must be a multiple of 10: If the coefficient is 0, no ads are served during this hour. Example of an array element: 1, 0, 0, 50, 50, 100, 100, 150, 200, 200, 150, 100, 100, 80, 70, 100, 100, 100, 50, 50, 40, 30, 0, 0, 0 Note. If the array is missing an element for one of the days of the week, all the bid coefficients are set to 100 for this day. If an automatic display strategy is selected, the coefficient 0 means displays are not allowed, and any other coefficient means displays are allowed (in other words, it is equivalent to 100).	No
`ConsiderWorkingWeekends`	YesNoEnum	Whether to change the display schedule when a work day is moved to Saturday or Sunday because of a public holiday. For example, if a work day is moved from Monday to Saturday and the value is YES, on the Saturday work day, ads are displayed according to the Monday schedule, and on the Monday holiday, they are displayed according to the Saturday schedule.	Yes
`HolidaysSchedule`	TimeTargetingOnPublicHolidays	Display settings on public holidays. If the time zone specified in the TimeZone parameter belongs to Russia, Ukraine, Belarus, Kazakhstan, or Turkey, we use the holiday calendar for the appropriate country. In all other cases, we use the Russian calendar.	No
TimeTargetingOnPublicHolidays structure
`SuspendOnHolidays`	YesNoEnum	Whether to suspend ads on public holidays: YES — suspend; NO — don't suspend. Note. The BidPercent, StartHour and EndHour parameters can only be set when SuspendOnHolidays has the value NO.	Yes
`BidPercent`	int	The bid coefficient for displays on public holidays. Specified as a percentage from 0 to 200. The value must be a multiple of 10.	No
`StartHour`	int	The time (in hours) to start displays on public holidays. From 0 to 23.	When the SuspendOnHolidays parameter has the value NO
`EndHour`	int	The time (in hours) to end displays on public holidays. From 0 to 24.	When the SuspendOnHolidays parameter has the value NO

Response

Response structure in JSON format:

{
  "result": { /* result */
    "AddResults": [{  /* ActionResult */
      "Id": (long),
      "Warnings": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
      }, ... ],
      "Errors": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
      }, ... ]
    }, ... ]
  }
}


Result structure (for JSON) / AddResponse structure (for SOAP)
Parameter	Type	Description
`AddResults`	array of ActionResult	Results of adding campaigns.
ActionResult structure
`Id`	long	ID of the created campaign. Returned if there are no errors, see Operations on object arrays.
`Warnings`	array of ExceptionNotification	Warnings that occurred during the operation.
`Errors`	array of ExceptionNotification	Errors that occurred during the operation.


Result structure (for JSON) / AddResponse structure (for SOAP)
Parameter	Type	Description
`AddResults`	array of ActionResult	Results of adding campaigns.
ActionResult structure
`Id`	long	ID of the created campaign. Returned if there are no errors, see Operations on object arrays.
`Warnings`	array of ExceptionNotification	Warnings that occurred during the operation.
`Errors`	array of ExceptionNotification	Errors that occurred during the operation.

Was the article useful?

Please tell us what you didn't like about this article:

Campaigns: managing campaigns

TextCampaign

Contents

Restrictions Request Response

Campaigns: managing campaigns

TextCampaign