Documentation
API version 4 and Live 4
Methods
Disabled methods

CreateOrUpdateBanners (Live)

Creates or changes ad groups, ads, and keywords.
Attention! 

Disabled method. Use version 5 of the API.

For information about the compatibility of methods between versions Live 4 and 5, see the Migration guide.

If the campaign is active, ads that have been added or changed are automatically submitted for moderation. For campaigns with “Draft” status, you can submit an ad for moderation by using the ModerateBanners
[no-highlight[

Submits an ad with “Draft” status for moderation.

More ModerateBanners

]no-highlight]
method.

Restrictions

Attention! The method only supports text and image ads. To work with all types of ads, use the Ads service in version 5 of the API. More about ad types...

A maximum of 1000 ads can be passed per method call.

The method can be called for a single campaign no more than 1000 times per day. Points are used when this method is invoked (see Point limitations). If there are not enough points available, the error message 152 is returned.

To update just the CPC, we recommend using the UpdatePrices (Live)
[no-highlight[

Sets bids and/or priorities for the specified keywords.

More UpdatePrices (Live)

]no-highlight]
method, which does not use points.

Each campaign may have a maximum of 1000 ad groups. There may be up to 50 ads per group. There may be up to 200 keywords per group.

New in the Live 4 version

Added the AutoMinusWords
[no-highlight[

Automatically make keywords in an ad group non-intersecting — Yes/No (see Removing keyword duplication). The predefined value is No.

Required

No

]no-highlight]
input parameter.
Added the AgeLabel
[no-highlight[

Age category.

For ads related to the baby_food group (the corresponding value is returned in the AdWarnings array), the age of the child in months: ‘0months‘, ‘1months‘, ‘2months‘, ..., ‘12months‘.

For all other ads, it is the age that the informational product is appropriate for. Possible values: ‘0+‘, ‘6+‘, ‘12+‘, ‘16+‘, ‘18+‘.

If an ad does not have an age category, this parameter is not returned in responses and is ignored during attempts to set it.

Restriction. 

The API can only be used to change the value of the age category, if the ad has one. In order to change whether an ad has or doesn‘t have an age category, contact the Support service for Yandex.Direct.

Required

No

]no-highlight]
input parameter.
Added the Currency
[no-highlight[

The currency that bids are shown in.

Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. The value must match the campaign‘s currency.

If this parameter is omitted or NULL, Yandex units are used. In this case, if the campaign is run using real currency, the bids passed by the application are converted to the actual currency before saving (see the section Real currencies instead of Yandex units).

If the value is something other than NULL but it does not match the currency of the campaign or one of the campaigns, an error is returned with code 245.

Required

No

]no-highlight]
input parameter (see the section Real currencies instead of Yandex units).
Added the input parameters AdGroupID
[no-highlight[

ID of the ad group.

For creating an ad group, the parameter is omitted or set to 0.

For creating an ad in an existing group, the group ID must be specified.

For changing the parameters of an ad or group, this parameter is optional (see the section Editing ad group parameters).

Required

No

]no-highlight]
and AdGroupName
[no-highlight[

The name of the ad group (up to 255 characters). If omitted, the ad group is automatically assigned a name in the format “AdGroup №<group ID>”.

If the string is longer than 255 characters, it will be truncated.

Required

No

]no-highlight]
.
Added the AdGroupMobileBidAdjustment
[no-highlight[

Coefficient for setting bids on mobile devices.

Used for ad groups and set as a percent of the desktop bid. A range of values from 50 to 1300. For more information about the coefficient, see Bid adjustments in the Help for Yandex.Direct.

Note. If the coefficient is not set for a group, calculations for bid prices on mobile devices use the coefficient for the campaign (the MobileBidAdjustment parameter), if available.

Required

No

]no-highlight]
input parameter.
Added the Type
[no-highlight[

Type of ad: Desktop or Mobile.

This parameter is specified only when creating an ad. If the value is not defined, “Desktop“ is assumed.

If you attempt to change the parameter value for an existing ad, an error is returned with the code 71.

Required

No

]no-highlight]
input parameter.

Input data

The input data structure in JSON is shown below.

{
   "method": "CreateOrUpdateBanners",
   "param": [
      {  /* BannerInfo */
         "BannerID
[no-highlight[

The ad ID. To create an ad, set 0; to change the parameters of an ad, set its ID.

Required

Yes

]no-highlight]
": (long), "CampaignID
[no-highlight[

The campaign ID.

Required

Yes

]no-highlight]
": (int), "AdGroupID
[no-highlight[

ID of the ad group.

For creating an ad group, the parameter is omitted or set to 0.

For creating an ad in an existing group, the group ID must be specified.

For changing the parameters of an ad or group, this parameter is optional (see the section Editing ad group parameters).

Required

No

]no-highlight]
": (long), "AdGroupName
[no-highlight[

The name of the ad group (up to 255 characters). If omitted, the ad group is automatically assigned a name in the format “AdGroup №<group ID>”.

If the string is longer than 255 characters, it will be truncated.

Required

No

]no-highlight]
": (string), "Type
[no-highlight[

Type of ad: Desktop or Mobile.

This parameter is specified only when creating an ad. If the value is not defined, “Desktop“ is assumed.

If you attempt to change the parameter value for an existing ad, an error is returned with the code 71.

Required

No

]no-highlight]
": (string), "Title
[no-highlight[

Title of the ad (up to 33 characters, including spaces and punctuation).

Required

Yes

]no-highlight]
": (string), "Text
[no-highlight[

Text of the ad (up to 75 characters, including spaces and punctuation).

Required

Yes

]no-highlight]
": (string), "Href
[no-highlight[

Link to the advertiser‘s website. May contain substitution variables (see the section Site links).

Required

One of the parameters, Href or ContactInfo

]no-highlight]
": (string), "Geo
[no-highlight[

IDs of regions where ad impressions are enabled or disabled. The ID 0 or an empty string indicates impressions in all regions.

To disable impressions in a region, prepend a minus sign to the region ID; for example, “1, -219” means to show ads for Moscow and the surrounding area, except Chernogolovka. Regions with a minus sign cannot be used if the zero region is set. Likewise, the parameter cannot consist entirely of minus regions.

To get the full list of regions, use the GetRegions method.

The parameter can be omitted if the value of AdGroupID is something other othan 0 and none of the parameters AdGroupName, Phrases, MinusKeywords, or AutoMinusWords is set.

Required

No

]no-highlight]
": (string), "ContactInfo
[no-highlight[

The ContactInfo object with the advertiser‘s contact information (business card).

Required

One of the parameters, Href or ContactInfo

]no-highlight]
": { /* ContactInfo */ "ContactPerson
[no-highlight[

Contact person. A maximum of 155 characters.

Required

No

]no-highlight]
": (string), "Country
[no-highlight[

Country. A maximum of 50 characters.

Required

Yes

]no-highlight]
": (string), "CountryCode
[no-highlight[

The country code for the phone number.

The value must start with the “+” sign, such as “+7” for Russia. Exception: if the CityCode field is set to “800”, the CountryCode field may be set to “8”.

Required

Yes

]no-highlight]
": (string), "City
[no-highlight[

The city. A maximum of 50 characters.

Required

Yes

]no-highlight]
": (string), "Street
[no-highlight[

Street. A maximum of 55 characters.

Required

No

]no-highlight]
": (string), "House
[no-highlight[

House number. A maximum of 30 characters.

Required

No

]no-highlight]
": (string), "Build
[no-highlight[

The building or unit number. A maximum of 10 characters.

Required

No

]no-highlight]
": (string), "Apart
[no-highlight[

The apartment or office number. Maximum of 255 characters.

Required

No

]no-highlight]
": (string), "CityCode
[no-highlight[

The area code or city code for the phone number.

Required

Yes

]no-highlight]
": (string), "Phone
[no-highlight[

The contact phone number.

Required

Yes

]no-highlight]
": (string), "PhoneExt
[no-highlight[

The phone extension, if an office PBX system is used.

Required

No

]no-highlight]
": (string), "CompanyName
[no-highlight[

Name of the organization. Maximum of 255 characters.

Required

Yes

]no-highlight]
": (string), "IMClient
[no-highlight[

The type of instant messaging network — icq, jabber, skype or mail_agent.

Required

No

]no-highlight]
": (string), "IMLogin
[no-highlight[

The user name for the instant messaging network.

Required

No

]no-highlight]
": (string), "ExtraMessage
[no-highlight[

Additional information on the advertised product or service. Maximum of 200 characters.

Required

No

]no-highlight]
": (string), "ContactEmail
[no-highlight[

Email address. Maximum of 255 characters.

Required

No

]no-highlight]
": (string), "WorkTime
[no-highlight[

The operating hours or client service hours of the business. Set as a string that specifies the range of days of the week, work hours, and minutes.

Days of the week are defined by the numbers from 0 to 6, where 0 is Monday and 6 is Sunday.

Minutes are set as a multiple of 15: 0, 15, 30 or 45.

String format:

“day_from;day_to;hour_from;minute_from;hour_to;minute_to“

For example, the string “0;4;10;0;18;0“ sets the following schedule:

0;4 — Monday to Friday

10;0 — from 10:00 am

18;0 — to 6:00 pm

The schedule may consist of several strings in this format, for example: “0;4;10;0;18;0;5;6;11;0;16;0“. Here, in addition to the previous example, the schedule also includes:

5;6 — Saturday and Sunday

11;0 — from 11:00 am

16;0 — to 4:00 pm

A 24-hour schedule is set using the string “0;6;00;00;00;00“.

Required

Yes

]no-highlight]
": (string), "OGRN
[no-highlight[

The OGRN code for a business registered in Russia.

Required

No

]no-highlight]
": (string), "PointOnMap
[no-highlight[

The MapPoint object, which provides the coordinates of the client‘s location. These coordinates are used to mark the map. If not set, the map is marked at the address that was specified for the client.

Required

No

]no-highlight]
": { /* MapPoint */ "x
[no-highlight[

Longitude of the point. From -180 to 180.

Required

Yes

]no-highlight]
": (float), "y
[no-highlight[

Latitude of the point. From -90 to 90.

Required

Yes

]no-highlight]
": (float), "x1
[no-highlight[

Longitude of the lower-left corner of the region on the map. From -180 to 180.

Required

Yes

]no-highlight]
": (float), "y1
[no-highlight[

Latitude of the lower-left corner of the region on the map. From -90 to 90.

Required

Yes

]no-highlight]
": (float), "x2
[no-highlight[

Longitude of the upper-right corner of the region on the map. From -180 to 180.

Required

Yes

]no-highlight]
": (float), "y2
[no-highlight[

Latitude of the upper-right corner of the region on the map. From -90 to 90.

Required

Yes

]no-highlight]
": (float) } }, "Phrases
[no-highlight[

Array of BannerPhraseInfo objects containing information on ad keywords. For an ad group, at least one keyword or retargeting condition must be set. The maximum number of keywords per group is 200.

The keywords can be omitted if the value of AdGroupID is something other than 0 and none of the parameters Geo, MinusKeywords, or AutоMinusWords is set, or in cases when the group has at least one retargeting condition.

Required

No

]no-highlight]
": [ { /* BannerPhraseInfo */ "PhraseID
[no-highlight[

The keyword ID. To create a keyword, set 0; to change the parameters of a keyword, specify its ID.

Required

No

]no-highlight]
": (long), "Phrase
[no-highlight[

Keywords.

It can contain negative keywords, which are specified with the minus sign before the word, such as [lightning -thunder -rain]. Negative keywords that are shared between several keywords should preferably be set in the MinusKeywords parameter for the ad group.

The maximum length of a keyword is 4096 characters. The “!” operator before a negative keyword is not counted in the keyword length (the sequence “-!” is considered one character).

Maximum of 7 words per keyword, not counting stop words and negative keywords. Each word and negative keyword can be up to 35 characters, not counting the minus sign before a negative keyword.

Required

Yes

]no-highlight]
": (string), "IsRubric
[no-highlight[

Whether the keyword is a Yandex.Catalog category — Yes/No. The predefined value is No. When the value is Yes, the passed keyword is ignored.

Required

No

]no-highlight]
": (string), "Price
[no-highlight[

Bid on Yandex search (in the currency specified in the Currency parameter). Used only if a strategy with manual bid management is selected for the campaign.

The maximum and minimum values are provided in the Currency parameters and restrictions table.

If the value is converted from Yandex units to the campaign currency before saving, it is rounded up to the nearest bid increment in this currency (see the section Real currencies instead of Yandex units). If converting the value to the campaign‘s currency results in a value that is less than the minimum bid or more than the maximum bid for this currency, it is set to equal the minimum or maximum bid, respectively.

Required

For manual strategies

]no-highlight]
": (float), "ContextPrice
[no-highlight[

Bid in the Yandex Advertising Network (in the currency specified in the Currency parameter).

The parameter is available for editing in the following cases:

  1. When the MaximumCoverage strategy is selected for the Yandex Advertising Network.

  2. When the Default strategy is selected for the Yandex Advertising Network and the keyword is disabled on the search due to a low CTR.

    For new keywords this condition is irrelevant, since keywords are no longer disabled for a low CTR.

The maximum and minimum values are provided in the Currency parameters and restrictions table.

If the value is converted from Yandex units to the campaign currency before saving, it is rounded up to the nearest bid increment in this currency (see the section Real currencies instead of Yandex units). If converting the value to the campaign‘s currency results in a value that is less than the minimum bid or more than the maximum bid for this currency, it is set to equal the minimum or maximum bid, respectively.

Required

For the MaximumCoverage strategy

]no-highlight]
": (float), "AutoBroker
[no-highlight[

Enable/disable AutoBroker. This parameter is not used, and the passed value is ignored.

Required

No

]no-highlight]
": (string), "AutoBudgetPriority
[no-highlight[

Priority of the keyword when using automatic strategies. Possible values:

  • Low — Low priority.
  • Medium — Average priority.
  • High — High priority.

Required

For the WeeklyBudget strategy

]no-highlight]
": (string), "UserParams
[no-highlight[

PhraseUserParams object. Contains values of substitution variables for the website links (see the section Site links).

Required

No

]no-highlight]
": { /* PhraseUserParams */ "Param1
[no-highlight[

Value of the {param1} substitution variable. No more than 255 bytes.

Required

When using substitution variables in Href

]no-highlight]
": (string), "Param2
[no-highlight[

Value of the {param2} substitution variable. No more than 255 bytes.

Required

When using substitution variables in Href

]no-highlight]
": (string) }, "Currency
[no-highlight[

The currency that bids are shown in.

Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. The value must match the campaign‘s currency.

If this parameter is omitted or NULL, Yandex units are used. In this case, if the campaign is run using real currency, the bids passed by the application are converted to the actual currency before saving (see the section Real currencies instead of Yandex units).

If the value is something other than NULL but it does not match the currency of the campaign or one of the campaigns, an error is returned with code 245.

Required

No

]no-highlight]
": (string) } ... ], "Sitelinks
[no-highlight[

Array of Sitelink objects with sitelinks. The array must contain from 1 to 4 Sitelink objects, or be omitted.

Required

No

]no-highlight]
": [ { /* Sitelink */ "Title
[no-highlight[

Text of a sitelink (maximum 30 characters).

The maximum total length of texts for all the sitelinks is 66 characters.

Required

Yes

]no-highlight]
": (string), "Href
[no-highlight[

Sitelink address. May contain substitution variables (see the section Site links).

Attention! The values of the {campaign_id}, {ad_id}, {banner_id}, and {phrase_id} variables will be substituted in the sitelinks only if the same variables are present in the main link for the ad.

Required

Yes

]no-highlight]
": (string) } ... ], "MinusKeywords
[no-highlight[

Array of negative keywords that are shared by all the keywords of an ad group.

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 4096 characters. The “!” or “+” operator before a word is not included in the total length.

Note. Negative keywords that are shared for all a campaign‘s ad groups should preferably be set in the campaign parameter of the same name.

Required

No

]no-highlight]
": [ (string) ... ], "AutoMinusWords
[no-highlight[

Automatically make keywords in an ad group non-intersecting — Yes/No (see Removing keyword duplication). The predefined value is No.

Required

No

]no-highlight]
": (string), "AgeLabel
[no-highlight[

Age category.

For ads related to the baby_food group (the corresponding value is returned in the AdWarnings array), the age of the child in months: ‘0months‘, ‘1months‘, ‘2months‘, ..., ‘12months‘.

For all other ads, it is the age that the informational product is appropriate for. Possible values: ‘0+‘, ‘6+‘, ‘12+‘, ‘16+‘, ‘18+‘.

If an ad does not have an age category, this parameter is not returned in responses and is ignored during attempts to set it.

Restriction. 

The API can only be used to change the value of the age category, if the ad has one. In order to change whether an ad has or doesn‘t have an age category, contact the Support service for Yandex.Direct.

Required

No

]no-highlight]
": (string), "AdGroupMobileBidAdjustment
[no-highlight[

Coefficient for setting bids on mobile devices.

Used for ad groups and set as a percent of the desktop bid. A range of values from 50 to 1300. For more information about the coefficient, see Bid adjustments in the Help for Yandex.Direct.

Note. If the coefficient is not set for a group, calculations for bid prices on mobile devices use the coefficient for the campaign (the MobileBidAdjustment parameter), if available.

Required

No

]no-highlight]
": (int) } ... ] }

Parameters are described below.

Parameter Description Required
BannerInfo object
BannerID

The ad ID. To create an ad, set 0; to change the parameters of an ad, set its ID.

Yes
CampaignID The campaign ID.Yes
AdGroupID

ID of the ad group.

For creating an ad group, the parameter is omitted or set to 0.

For creating an ad in an existing group, the group ID must be specified.

For changing the parameters of an ad or group, this parameter is optional (see the section Editing ad group parameters).

No
AdGroupName

The name of the ad group (up to 255 characters). If omitted, the ad group is automatically assigned a name in the format “AdGroup №<group ID>”.

If the string is longer than 255 characters, it will be truncated.

No
Type

Type of ad: Desktop or Mobile.

This parameter is specified only when creating an ad. If the value is not defined, "Desktop" is assumed.

If you attempt to change the parameter value for an existing ad, an error is returned with the code 71.

No
Title Title of the ad (up to 33 characters, including spaces and punctuation).Yes
Text Text of the ad (up to 75 characters, including spaces and punctuation).Yes
Href

Link to the advertiser's website. May contain substitution variables (see the section Site links).

One of the parameters, Href or ContactInfo
ContactInfo

The ContactInfo object with the advertiser's contact information (business card).

Geo

IDs of regions where ad impressions are enabled or disabled. The ID 0 or an empty string indicates impressions in all regions.

To disable impressions in a region, prepend a minus sign to the region ID; for example, “1, -219” means to show ads for Moscow and the surrounding area, except Chernogolovka. Regions with a minus sign cannot be used if the zero region is set. Likewise, the parameter cannot consist entirely of minus regions.

To get the full list of regions, use the GetRegions
[no-highlight[

Returns a list of regions registered in Yandex.Direct.

More GetRegions

]no-highlight]
method.

The parameter can be omitted if the value of AdGroupID is something other othan 0 and none of the parameters AdGroupName, Phrases, MinusKeywords, or AutoMinusWords is set.

No
Phrases

Array of BannerPhraseInfo objects containing information on ad keywords. For an ad group, at least one keyword or retargeting condition must be set. The maximum number of keywords per group is 200.

The keywords can be omitted if the value of AdGroupID is something other than 0 and none of the parameters Geo, MinusKeywords, or AutоMinusWords is set, or in cases when the group has at least one retargeting condition.

No
Sitelinks

Array of Sitelink objects with sitelinks. The array must contain from 1 to 4 Sitelink objects, or be omitted.

No
MinusKeywords

Array of negative keywords that are shared by all the keywords of an ad group.

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 4096 characters. The “!” or “+” operator before a word is not included in the total length.

Note. Negative keywords that are shared for all a campaign's ad groups should preferably be set in the campaign parameter of the same name.
No
AutoMinusWords

Automatically make keywords in an ad group non-intersecting — Yes/No (see Removing keyword duplication). The predefined value is No.

No
AgeLabel

Age category.

For ads related to the baby_food group (the corresponding value is returned in the AdWarnings array), the age of the child in months: '0months', '1months', '2months', ..., '12months'.

For all other ads, it is the age that the informational product is appropriate for. Possible values: '0+', '6+', '12+', '16+', '18+'.

If an ad does not have an age category, this parameter is not returned in responses and is ignored during attempts to set it.

Restriction. 

The API can only be used to change the value of the age category, if the ad has one. In order to change whether an ad has or doesn't have an age category, contact the Support service for Yandex.Direct.

No
AdGroupMobileBidAdjustment

Coefficient for setting bids on mobile devices.

Used for ad groups and set as a percent of the desktop bid. A range of values from 50 to 1300. For more information about the coefficient, see Bid adjustments in the Help for Yandex.Direct.

Note. If the coefficient is not set for a group, calculations for bid prices on mobile devices use the coefficient for the campaign (the MobileBidAdjustment
[no-highlight[

Coefficient for setting bids on mobile devices.

Used for campaigns and set as a percent of the desktop bid. A range of values from 50 to 1300. The default value is 100. With this value, the bid on mobile devices is the same as the bid on desktops. For more information about the coefficient, see Bid adjustment in the Help for Yandex.Direct.

Required

No

]no-highlight]
parameter), if available.
No
ContactInfo object
CompanyName

Name of the organization. Maximum of 255 characters.

Yes
ContactPerson

Contact person. A maximum of 155 characters.

No
Country

Country. A maximum of 50 characters.

Yes
CountryCode The country code for the phone number.

The value must start with the “+” sign, such as “+7” for Russia. Exception: if the CityCode field is set to “800”, the CountryCode field may be set to “8”.

Yes
City

The city. A maximum of 50 characters.

Yes
Street

Street. A maximum of 55 characters.

No
House

House number. A maximum of 30 characters.

No
Build

The building or unit number. A maximum of 10 characters.

No
Apart

The apartment or office number. Maximum of 255 characters.

No
CityCode

The area code or city code for the phone number.

Yes
Phone

The contact phone number.

Yes
PhoneExt

The phone extension, if an office PBX system is used.

No
IMClient

The type of instant messaging network — icq, jabber, skype or mail_agent.

No
IMLogin

The user name for the instant messaging network.

No
ExtraMessage

Additional information on the advertised product or service. Maximum of 200 characters.

No
ContactEmail

Email address. Maximum of 255 characters.

No
WorkTime

The operating hours or client service hours of the business. Set as a string that specifies the range of days of the week, work hours, and minutes.

Days of the week are defined by the numbers from 0 to 6, where 0 is Monday and 6 is Sunday.

Minutes are set as a multiple of 15: 0, 15, 30 or 45.

String format:

"day_from;day_to;hour_from;minute_from;hour_to;minute_to"

For example, the string "0;4;10;0;18;0" sets the following schedule:

0;4 — Monday to Friday

10;0 — from 10:00 am

18;0 — to 6:00 pm

The schedule may consist of several strings in this format, for example: "0;4;10;0;18;0;5;6;11;0;16;0". Here, in addition to the previous example, the schedule also includes:

5;6 — Saturday and Sunday

11;0 — from 11:00 am

16;0 — to 4:00 pm

A 24-hour schedule is set using the string "0;6;00;00;00;00".

Yes
OGRN

The OGRN code for a business registered in Russia.

No
PointOnMap

The MapPoint object, which provides the coordinates of the client's location. These coordinates are used to mark the map. If not set, the map is marked at the address that was specified for the client.

No
MapPoint object
x

Longitude of the point. From -180 to 180.

Yes
y

Latitude of the point. From -90 to 90.

Yes
x1

Longitude of the lower-left corner of the region on the map. From -180 to 180.

Yes
y1

Latitude of the lower-left corner of the region on the map. From -90 to 90.

Yes
x2

Longitude of the upper-right corner of the region on the map. From -180 to 180.

Yes
y2

Latitude of the upper-right corner of the region on the map. From -90 to 90.

Yes
BannerPhraseInfo object
PhraseID The keyword ID. To create a keyword, set 0; to change the parameters of a keyword, specify its ID.No
Phrase

Keywords.

It can contain negative keywords, which are specified with the minus sign before the word, such as [lightning -thunder -rain]. Negative keywords that are shared between several keywords should preferably be set in the MinusKeywords parameter for the ad group.

The maximum length of a keyword is 4096 characters. The “!” operator before a negative keyword is not counted in the keyword length (the sequence “-!” is considered one character).

Maximum of 7 words per keyword, not counting stop words and negative keywords. Each word and negative keyword can be up to 35 characters, not counting the minus sign before a negative keyword.

Yes
IsRubric Whether the keyword is a Yandex.Catalog category — Yes/No. The predefined value is No. When the value is Yes, the passed keyword is ignored.No
Price
Bid on Yandex search (in the currency specified in the Currency parameter). Used only if a strategy
[no-highlight[

Strategy on search. Acceptable values are listed below.

  • ShowsDisabled — Disable impressions on search. This is required when using an automatic strategy in the Yandex Advertising Network. Showing ads in the search cannot be disabled if the Default strategy is applied to the Yandex Advertising Network.

Strategies with manual bid management on search:

  • HighestPosition — “Highest available position” strategy.
  • LowestCost — “Cheapest position in ad block” strategy.
  • LowestCostPremium — “Cheapest position in ad block” strategy, but ads are displayed only in Premium Placement.
  • LowestCostGuarantee — “Impressions below search results” strategy (in the lower block at lowest cost).
  • RightBlockHighest — The “Impressions below search results” strategy (in the lower block at the highest position available for the specified bid).

Automatic strategies on search:

  • WeeklyBudget — The “Weekly budget: maximum clicks” strategy (mandatory parameter WeeklySumLimit; optional parameter MaxPrice).
  • CPAOptimizer — The “Weekly budget: maximum conversion rate” strategy (mandatory parameters WeeklySumLimit and GoalID; optional parameter MaxPrice). See the conditions for using this strategy in the Help for Yandex.Direct.
  • AverageClickPrice — The “Average CPC” strategy (mandatory parameter: AveragePrice; optional parameter: WeeklySumLimit).
  • WeeklyPacketOfClicks — The “Weekly click package” strategy (mandatory parameter: ClicksPerWeek; optional parameters: MaxPrice or AveragePrice).
  • AverageCPAOptimization — The “Average CPA” strategy (mandatory parameters AverageCPA and GoalID; optional parameters WeeklySumLimit and MaxPrice). See the conditions for using this strategy in the Help for Yandex.Direct.
  • ROIOptimization — The “Average ROI” strategy (mandatory parameters ReserveReturn, ROICoef, GoalID; optional parameters Profitability, WeeklySumLimit and MaxPrice). See conditions for using this strategy in the Help for Yandex.Direct.

Required

Yes

]no-highlight]
with manual bid management is selected for the campaign.

The maximum and minimum values are provided in the Currency parameters and restrictions table.

If the value is converted from Yandex units to the campaign currency before saving, it is rounded up to the nearest bid increment in this currency (see the section Real currencies instead of Yandex units). If converting the value to the campaign's currency results in a value that is less than the minimum bid or more than the maximum bid for this currency, it is set to equal the minimum or maximum bid, respectively.

For manual strategies
ContextPrice

Bid in the Yandex Advertising Network (in the currency specified in the Currency parameter).

The parameter is available for editing in the following cases:

  1. When the MaximumCoverage strategy is selected for the Yandex Advertising Network.

  2. When the Default strategy is selected for the Yandex Advertising Network and the keyword is disabled on the search due to a low CTR.

    For new keywords this condition is irrelevant, since keywords are no longer disabled for a low CTR.

The maximum and minimum values are provided in the Currency parameters and restrictions table.

If the value is converted from Yandex units to the campaign currency before saving, it is rounded up to the nearest bid increment in this currency (see the section Real currencies instead of Yandex units). If converting the value to the campaign's currency results in a value that is less than the minimum bid or more than the maximum bid for this currency, it is set to equal the minimum or maximum bid, respectively.

For the MaximumCoverage strategy
AutoBroker Enable/disable AutoBroker. This parameter is not used, and the passed value is ignored.No
AutoBudgetPriority

Priority of the keyword when using automatic strategies. Possible values:

  • Low — Low priority.
  • Medium — Average priority.
  • High — High priority.
For the WeeklyBudget strategy
UserParams

PhraseUserParams object. Contains values of substitution variables for the website links (see the section Site links).

No
Currency

The currency that bids are shown in.

Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. The value must match the campaign's currency.

If this parameter is omitted or NULL, Yandex units are used. In this case, if the campaign is run using real currency, the bids passed by the application are converted to the actual currency before saving (see the section Real currencies instead of Yandex units).

If the value is something other than NULL but it does not match the currency of the campaign or one of the campaigns, an error is returned with code 245.

No
PhraseUserParams object
Param1

Value of the {param1} substitution variable. No more than 255 bytes.

When using substitution variables in Href
Param2

Value of the {param2} substitution variable. No more than 255 bytes.

Sitelink object
Title Text of a sitelink (maximum 30 characters).

The maximum total length of texts for all the sitelinks is 66 characters.

Yes
Href

Sitelink address. May contain substitution variables (see the section Site links).

Attention! The values of the {campaign_id}, {ad_id}, {banner_id}, and {phrase_id} variables will be substituted in the sitelinks only if the same variables are present in the main link for the ad.
Yes

Output data

When executed successfully, the method returns an array containing the IDs of created or updated ads, as shown in the following example.

{
   "data": [33823946,33823947]
}

Examples of input data

[
   # Editing parameters of an ad and a group
   {
      'BannerID': 2571700,
      'CampaignID': 1327837,
      'AdGroupName': u'Name of Group 1',
      'Title': u'Title of Ad 1',
      'Text': u'Text of Ad 1',
      'Href': 'http://www.site.ru/page{param1}?ad={param2}',
      'Geo': '2,183,3',
      'ContactInfo': {
         'ContactPerson': u'Alexander Gromov',
         'Country': u'Russia',
         'CountryCode': '+7',
         'City': 'Moscow',
         'Street': 'Leo Tolstoy',
         'House': '16',
         'Build': '',
         'Apart': '',
         'CityCode': '495',
         'Phone': '739-70-00',
         'PhoneExt': '',
         'CompanyName': 'MyCompany',
         'IMClient': 'jabber',
         'IMLogin': 'email@ya.ru',
         'ExtraMessage': u'all products are certified',
         'ContactEmail': 'direct@yandex.ru',
         'WorkTime': '0;4;10;00;18;00;5;6;13;00;16;00',
         'OGRN': '1077746365113',
         'PointOnMap': {
            'x': 37.587942,
            'y': 55.733783,
            'x1': 37.573500,
            'y1': 55.729389,
            'x2': 37.600772,
            'y2': 55.740249
         }
      },
      'Phrases': [
         {
            'PhraseID': 37512102,
            'Phrase': 'refrigerator',
            'ContextPrice': 1.6,
            'Price': 2.1,
            'AutoBudgetPriority': 'Medium',
            'UserParams': {
               'Param1': '17',
               'Param2': '177'
            }
         }
      ],
      'Sitelinks': [
         {
            'Title': u'Add'l link 1',
            'Href': 'http://www.site.ru/?q=qu&amp;action=1'
         },
         {
            'Title': u'Add'l link 2',
            'Href': 'http://www.site.ru/?q=qu&amp;action=2'
         },
         {
            'Title': u'Add'l link 3',
            'Href': 'http://www.site.ru/?q=qu&amp;action=3'
         }
      ],
      'MinusKeywords': ['ice','cream'],
      'AutoMinusWords': 'Yes'
   },
   # Editing ad parameters without editing group parameters
   {
      'BannerID': 2571707,
      'CampaignID': 1327837,
      'AdGroupID': 7542138,
      'Title': 'Title of Ad 2',
      'Text': 'Text of Ad 2',
      'Href': 'http://www.site.ru/page{param1}?utm_content={phrase_id}'
   },
   # Adding ads to a group
   {
      'BannerID': 0,
      'CampaignID': 1327837,
      'AdGroupID': 4571251,
      'Title': 'Title of Ad 3',
      'Text': 'Text of Ad 3',
      'Href': 'http://www.site.ru/page{param2}?utm_content={phrase_id}'
   }
]
array(
   # Editing parameters for an ad and a group
   array(
      'BannerID' => 2571700,
      'CampaignID' => 1327837,
      'Title' => 'Title of ad 1',
      'Text' => 'Text of ad 1',
      'Href' => 'http://www.site.ru/page{param1}?ad={param2}',
      'Geo' => '2,183,3',
      'ContactInfo' => array(
         'ContactPerson' => 'Alexander Gromov',
         'Country' => 'Russia',
         'CountryCode' => '+7',
         'City' => 'Moscow',
         'Street' => 'Leo Tolstoy',
         'House' => '16',
         'Build' => '',
         'Apart' => '',
         'CityCode' => '495',
         'Phone' => '739-70-00',
         'PhoneExt' => '',
         'CompanyName' => 'MyCompany',
         'IMClient' => 'jabber',
         'IMLogin' => 'email@ya.ru',
         'ExtraMessage' => 'all products are certified',
         'ContactEmail' => 'direct@yandex.ru',
         'WorkTime' => '0;4;10;00;18;00;5;6;13;00;16;00',
         'OGRN' => '1077746365113',
         'PointOnMap' => array(
            'x' => 37.587942,
            'y' => 55.733783,
            'x1' => 37.573500,
            'y1' => 55.729389,
            'x2' => 37.600772,
            'y2' => 55.740249
         )
      ),
      'Phrases' => array(
         array(
            'PhraseID' => 37512102,
            'Phrase' => 'refrigerator',
            'ContextPrice' => 1.6,
            'Price' => 2.1,
            'AutoBudgetPriority' => 'Medium',
            'UserParams' => array(
               'Param1' => '17',
               'Param2' => '177'
            )
         )
      ),
      'Sitelinks' => array(
         array(
            'Title' => 'Add'l link 1',
            'Href' => 'http://www.site.ru/?q=qu&amp;action=1'
         ),
         array(
            'Title' => 'Add'l link 2',
            'Href' => 'http://www.site.ru/?q=qu&amp;action=2'
         ),
         array(
            'Title' => 'Add'l link 3',
            'Href' => 'http://www.site.ru/?q=qu&amp;action=3'
         )
      ),
      'MinusKeywords' => array('ice','cream'),
      'AutoMinusWords' => 'Yes'
   ),
   # Editing ad parameters without editing group parameters
   array(
      'BannerID' => 2571707,
      'CampaignID' => 1327837,
      'AdGroupID' => 7542138,
      'Title' => 'Title of ad 2',
      'Text' => 'Text of ad 2',
      'Href' => 'http://www.site.ru/page{param1}?utm_content={phrase_id}'
   ),
   # Adding an ad to a group
   array(
      'BannerID' => 0,
      'CampaignID' => 1327837,
      'AdGroupID' => 4571251,
      'Title' => 'Title of ad 3',
      'Text' => 'Text of ad 3',
      'Href' => 'http://www.site.ru/page{param2}?utm_content={phrase_id}'
   )
)
[
   # Editing parameters of an ad and a group
   {
      'BannerID' => 2571700,
      'CampaignID' => 1327837,
      'Title' => 'Title of Ad 1',
      'Text' => 'Text of Ad 1',
      'Href' => 'http://www.site.ru/page{param1}?ad={param2}',
      'Geo' => '2,183,3',
      'ContactInfo' => {
         'ContactPerson' => 'Alexander Gromov',
         'Country' => 'Russia',
         'CountryCode' => '+7',
         'City' => 'Moscow',
         'Street' => 'Leo Tolstoy',
         'House' => '16',
         'Build' => '',
         'Apart' => '',
         'CityCode' => '495',
         'Phone' => '739-70-00',
         'PhoneExt' => '',
         'CompanyName' => 'MyCompany',
         'IMClient' => 'jabber',
         'IMLogin' => 'email@ya.ru',
         'ExtraMessage' => 'all products are certified',
         'ContactEmail' => 'direct@yandex.ru',
         'WorkTime' => '0;4;10;00;18;00;5;6;13;00;16;00',
         'OGRN' => '1077746365113',
         'PointOnMap' => {
            'x' => 37.587942,
            'y' => 55.733783,
            'x1' => 37.573500,
            'y1' => 55.729389,
            'x2' => 37.600772,
            'y2' => 55.740249
         }
      },
      'Phrases' => [
         {
            'PhraseID' => 37512102,
            'Phrase' => 'refrigerator',
            'ContextPrice' => 1.6,
            'Price' => 2.1,
            'AutoBudgetPriority' => 'Medium',
            'UserParams' => {
               'Param1' => '17',
               'Param2' => '177'
            }
         }
      ],
      'Sitelinks' => [
         {
            'Title' => 'Add'l link 1',
            'Href' => 'http://www.site.ru/?q=qu&amp;action=1'
         },
         {
            'Title' => 'Add'l link 2',
            'Href' => 'http://www.site.ru/?q=qu&amp;action=2'
         },
         {
            'Title' => 'Add'l link 3',
            'Href' => 'http://www.site.ru/?q=qu&amp;action=3'
         }
      ],
      'MinusKeywords' => ['ice','cream'],
      'AutoMinusWords' => 'Yes'
   },
   # Editing ad parameters without editing group parameters
   {
      'BannerID' => 2571707,
      'CampaignID' => 1327837,
      'AdGroupID' => 7542138,
      'Title' => 'Title of Ad 2',
      'Text' => 'Text of Ad 2',
      'Href' => 'http://www.site.ru/page{param1}?utm_content={phrase_id}'
   },
   # Adding ads to a group
   {
      'BannerID' => 0,
      'CampaignID' => 1327837,
      'AdGroupID' => 4571251,
      'Title' => 'Title of Ad 3',
      'Text' => 'Text of Ad 3',
      'Href' => 'http://www.site.ru/page{param2}?utm_content={phrase_id}'
   }
]