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 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) method, which does not deduct 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 input parameter.

Added the AgeLabel input parameter.

Added the Currency input parameter (see the section Real currencies instead of Yandex units).

Added the input parameters AdGroupID and AdGroupName.

Added the AdGroupMobileBidAdjustment input parameter.

Added the Type input parameter.

Input data

The input data structure in JSON is shown below.

{
   "method": "CreateOrUpdateBanners",
   "param": [
      {  /* BannerInfo */
         "BannerID": (long),
         "CampaignID": (int),
         "AdGroupID": (long),
         "AdGroupName": (string),
         "Type": (string),
         "Title": (string),
         "Text": (string),
         "Href": (string),
         "Geo": (string),
         "ContactInfo": {
            /* ContactInfo */
            "ContactPerson": (string),
            "Country": (string),
            "CountryCode": (string),
            "City": (string),
            "Street": (string),
            "House": (string),
            "Build": (string),
            "Apart": (string),
            "CityCode": (string),
            "Phone": (string),
            "PhoneExt": (string),
            "CompanyName": (string),
            "IMClient": (string),
            "IMLogin": (string),
            "ExtraMessage": (string),
            "ContactEmail": (string),
            "WorkTime": (string),
            "OGRN": (string),
            "PointOnMap": {
               /* MapPoint */
               "x": (float),
               "y": (float),
               "x1": (float),
               "y1": (float),
               "x2": (float),
               "y2": (float)
            }
         },
         "Phrases": [
            {  /* BannerPhraseInfo */
               "PhraseID": (long),
               "Phrase": (string),
               "IsRubric": (string),
               "Price": (float),
               "ContextPrice": (float),
               "AutoBroker": (string),
               "AutoBudgetPriority": (string),
               "UserParams": {
                  /* PhraseUserParams */
                  "Param1": (string),
                  "Param2": (string)
               },
               "Currency": (string)
            }
            ...
         ],
         "Sitelinks": [
            {  /* Sitelink */
               "Title": (string),
               "Href": (string)
            }
            ...
         ],
         "MinusKeywords": [
            (string)
            ...
         ],
         "AutoMinusWords": (string),
         "AgeLabel": (string),
         "AdGroupMobileBidAdjustment": (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 the parameter was omitted, the 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. It can contain wildcard variables (see section Links to the site).

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 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
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. Operator “!” 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 Eliminating intersections). 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 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 “-!” counts as a single 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 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.

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

Python

[
   # 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&action=1'
         },
         {
            'Title': u'Add'l link 2',
            'Href': 'http://www.site.ru/?q=qu&action=2'
         },
         {
            'Title': u'Add'l link 3',
            'Href': 'http://www.site.ru/?q=qu&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}'
   }
]

PHP

array(
   # Editing parameters for an ad and a group
   array(
      'BannerID' => 2571700,
      'CampaignID' => 1327837,
      'Title' => 'Title for ad 1',
      'Text' => 'Text for 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&action=1'
         ),
         array(
            'Title' => 'Add'l link 2',
            'Href' => 'http://www.site.ru/?q=qu&action=2'
         ),
         array(
            'Title' => 'Add'l link 3',
            'Href' => 'http://www.site.ru/?q=qu&action=3'
         )
      ),
      'MinusKeywords' => array('ice','cream'),
      'AutoMinusWords' => 'Yes'
   ),
   # Editing ad parameters without editing group parameters
   array(
      'BannerID' => 2571707,
      'CampaignID' => 1327837,
      'AdGroupID' => 7542138,
      'Title' => 'Title for ad 2',
      'Text' => 'Text for ad 2',
      'Href' => 'http://www.site.ru/page{param1}?utm_content={phrase_id}'
   ),
   # Adding ads to a group
   array(
      'BannerID' => 0,
      'CampaignID' => 1327837,
      'AdGroupID' => 4571251,
      'Title' => 'Title for ad 3',
      'Text' => 'Text for ad 3',
      'Href' => 'http://www.site.ru/page{param2}?utm_content={phrase_id}'
   )
)

Perl

[
   # Editing parameters of an ad and a group
   {
      'BannerID' => 2571700,
      'CampaignID' => 1327837,
      'Title' => 'Title for ad 1',
      'Text' => 'Text for 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&action=1'
         },
         {
            'Title' => 'Add'l link 2',
            'Href' => 'http://www.site.ru/?q=qu&action=2'
         },
         {
            'Title' => 'Add'l link 3',
            'Href' => 'http://www.site.ru/?q=qu&action=3'
         }
      ],
      'MinusKeywords' => ['ice','cream'],
      'AutoMinusWords' => 'Yes'
   },
   # Editing ad parameters without editing group parameters
   {
      'BannerID' => 2571707,
      'CampaignID' => 1327837,
      'AdGroupID' => 7542138,
      'Title' => 'Title for ad 2',
      'Text' => 'Text for 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 for ad 3',
      'Text' => 'Text for ad 3',
      'Href' => 'http://www.site.ru/page{param2}?utm_content={phrase_id}'
   }
]