CreateOrUpdateBanners

Creates an ad and keywords, or changes an existing ad and keywords.

Attention.

Disabled method. Use version 5 of the API.

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

The CreateOrUpdateBanners (Live) version also exists for this method.

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...

Groups of multiple ads are not supported in version 4. To work with groups like this, use the CreateOrUpdateBanners (Live) method.

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.

Each campaign may have a maximum of 1000 ads. The maximum number of keywords per ad is 200.

To update just the CPC, we recommend using the UpdatePrices method, which does not deduct points.

Input data

The input data structure in JSON is shown below.

{
   "method": "CreateOrUpdateBanners",
   "param": [
      {  /* BannerInfo */
         "BannerID": (long),
         "CampaignID": (int),
         "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)
               }
            }
            ...
         ],
         "Sitelinks": [
            {  /* Sitelink */
               "Title": (string),
               "Href": (string)
            }
            ...
         ],
         "MinusKeywords": [
            (string)
            ...
         ]
      }
      ...
   ]
}

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
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 (default value).

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.

Yes
Phrases Array of BannerPhraseInfo objects containing information on ad keywords. An ad must have at least one keyword. The maximum number of keywords per ad is 200. Yes
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 “!” 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
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

The bid on Yandex search (in Yandex units). The predefined limit is 50 Yandex units. Required only if a strategy with manual bid management is selected for the campaign.

For manual strategies
AutoBudgetPriority

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

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

Bid in the Yandex Advertising Network (in Yandex units). The bid can be set in the following cases:

  1. The IndependentControl strategy is used on search. This strategy can only be selected via the Yandex Direct web interface.
  2. A manual strategy is used on search and the keyword is disabled for a low CTR.

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

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

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

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.

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
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 (default value).

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.

Yes
Phrases Array of BannerPhraseInfo objects containing information on ad keywords. An ad must have at least one keyword. The maximum number of keywords per ad is 200. Yes
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 “!” 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
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

The bid on Yandex search (in Yandex units). The predefined limit is 50 Yandex units. Required only if a strategy with manual bid management is selected for the campaign.

For manual strategies
AutoBudgetPriority

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

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

Bid in the Yandex Advertising Network (in Yandex units). The bid can be set in the following cases:

  1. The IndependentControl strategy is used on search. This strategy can only be selected via the Yandex Direct web interface.
  2. A manual strategy is used on search and the keyword is disabled for a low CTR.

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

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

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

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

[
   {
      'BannerID': 2571700,
      'CampaignID': 1327837,
      'Title': 'Banner title',
      'Text': 'Banner text',
      'Href': 'http://www.client.ru/banner{param1}?page={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': 'market-click2.ya.ru/?q=qu&action=1'
         },
         {
            'Title': u'Add'l link 2',
            'Href': 'market-click2.ya.ru/?q=qu&action=2'
         },
         {
            'Title': u'Add'l link 3',
            'Href': 'market-click2.ya.ru/?q=qu&action=3'
         }
      ],
      'MinusKeywords': ['ice','cream']
   }
]

PHP

array(
   array(
      'BannerID' => 2571700,
      'CampaignID' => 1327837,
      'Title' => 'Banner title',
      'Text' => 'Banner text',
      'Href' => 'http://www.client.ru/bannerarray(param1)?page=array(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' => 'market-click2.ya.ru/?q=qu&action=1'
         ),
         array(
            'Title' => 'Add'l link 2',
            'Href' => 'market-click2.ya.ru/?q=qu&action=2'
         ),
         array(
            'Title' => 'Add'l link 3',
            'Href' => 'market-click2.ya.ru/?q=qu&action=3'
         )
      ),
      'MinusKeywords' => array('ice','cream')
   )
)

Perl

[
   {
      'BannerID' => 2571700,
      'CampaignID' => 1327837,
      'Title' => 'Banner title',
      'Text' => 'Banner text',
      'Href' => 'http://www.client.ru/banner{param1}?page={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' => 'market-click2.ya.ru/?q=qu&action=1'
         },
         {
            'Title' => 'Add'l link 2',
            'Href' => 'market-click2.ya.ru/?q=qu&action=2'
         },
         {
            'Title' => 'Add'l link 3',
            'Href' => 'market-click2.ya.ru/?q=qu&action=3'
         }
      ],
      'MinusKeywords' => ['ice','cream']
   }
]