CreateOrUpdateBanners (Live)

Creates or modifies ad groups, ads and keywords.

If the campaign is active, added and modified ads are automatically submitted for moderation. For campaigns with "Draft" status, ads can be submitted for moderation using the ModerateBanners method.

Restrictions

Alert

The method only supports “Text & Image Ads”. To work with ads of all types, use the Ads service in API version 5. Learn more about ad types...

No more than 1000 ads can be passed in a single method call.

The method can be called no more than 1000 times per day for one campaign. Calling the method consumes points. If there are not enough points, error message 152 is returned.

To update only click prices, it is recommended to use the UpdatePrices (Live) method, which does not consume points when called.

A campaign can contain no more than 1000 ad groups. The number of ads in a group — no more than 50. The number of keywords in a group — no more than 200.

What's new in Live version 4

The AutoMinusWords input parameter has been added.

The AgeLabel input parameter has been added.

The Currency input parameter has been added.

The AdGroupID and AdGroupName input parameters have been added.

The AdGroupMobileBidAdjustment input parameter has been added.

The Type input parameter has been added.

Input data

The structure of input data in JSON format 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)
      }
      ...
   ]
}

The parameters are described below.

Parameter	Description	Required
BannerInfo object
`BannerID`	Ad ID. To create an ad, set to 0; to change ad parameters, specify its ID.	Yes
`CampaignID`	Campaign ID.	Yes
`AdGroupID`	Ad group ID. To create an ad group, do not specify the parameter or set the value to 0. To add an ad to an existing group, specify the ID of that group. To change ad or group parameters, specifying the parameter is optional.	No
`AdGroupName`	Ad group name (up to 255 characters). If not specified, the group is automatically assigned a name like "AdGroup №". If the string length exceeds 255 characters, extra characters will be discarded.	No
`Type`	Ad type: Desktop or Mobile. The parameter is specified only when creating an ad. If the value is not specified, Desktop is assumed. Attempting to change the parameter value for an existing ad returns an error with code 71.	No
`Title`	Ad title (up to 33 characters, including spaces and punctuation).	Yes
`Text`	Ad text (up to 75 characters, including spaces and punctuation).	Yes
`Href`	Link to the advertiser's website. May contain substitution variables.	One of the parameters — `Href` or `ContactInfo`
`ContactInfo`	`ContactInfo` object with advertiser contact data (business card).
`Geo`	IDs of regions for which display is enabled or disabled. ID 0 or empty string — display in all regions. To disable display in a region, put a minus sign before the region ID, for example "1,-219" — display for Moscow and Moscow Oblast, except Chernogolovka. Regions with a minus cannot be used if region zero is specified. Also, the parameter must not consist only of minus-regions. The complete list of regions can be obtained using the GetRegions method. Specifying the parameter is optional if the `AdGroupID` value is not 0 and none of the parameters `AdGroupName`, `Phrases`, `MinusKeywords`, `AutoMinusWords` are specified.	No
`Phrases`	Array of `BannerPhraseInfo` objects containing keyword information. At least one keyword or retargeting condition must be specified for the ad group. The number of keywords in a group — no more than 200. Specifying keywords is optional if the `AdGroupID` value is not 0 and none of the parameters `Geo`, `MinusKeywords`, `AutoMinusWords` are specified, and also if at least one retargeting condition is specified for the group.	No
`Sitelinks`	Array of `Sitelink` objects with . The array must contain from 1 to 4 `Sitelink` objects or be absent.	No
`MinusKeywords`	Array of negative keywords common to all keywords in the ad group. A negative keyword should be specified without a minus before the first word. No more than 7 words in a negative keyword. Length of each word — no more than 35 characters. Total length of negative keywords in the array — no more than 4096 characters. The "!" or "+" operator before a word is not counted in the total length. Note Negative keywords common to all groups in a campaign should preferably be specified in the campaign's parameter of the same name.	No
`AutoMinusWords`	Automatically make keywords in the ad group non-overlapping — Yes/No. Default value — No.	No
`AgeLabel`	Age category. For ads belonging to the baby_food group (corresponding value returned in the `AdWarnings` array) — child's age in months: '0months', '1months', '2months', ..., '12months'. For other ads — age for which the information product is intended. Possible values: '0+', '6+', '12+', '16+', '18+'. If the ad does not have an age category, the parameter is not returned in responses and is ignored when attempting to set it. Alert Through the API, you can only change the age category value if the ad has one. To change the presence/absence of an age category, please contact .	No
`AdGroupMobileBidAdjustment`	Bid adjustment coefficient for mobile devices. Used for ad groups and specified as a percentage of the desktop bid. Value range from 50 to 1300. Learn more about the coefficient in the section of Direct help. Note If the coefficient is not specified for the group, then the campaign coefficient (MobileBidAdjustment parameter) is used in calculations for setting mobile device bid prices, if available.	No
ContactInfo object
`CompanyName`	Organization name. No more than 255 characters.	Yes
`ContactPerson`	Contact person. No more than 155 characters.	No
`Country`	Country. No more than 50 characters.	Yes
`CountryCode`	Country phone code. The value must start with a "+" sign, for example "+7" for Russia. Exception: if the `CityCode` field contains the value "800", then the `CountryCode` field may contain the value "8".	Yes
`City`	City. No more than 50 characters.	Yes
`Street`	Street. No more than 55 characters.	No
`House`	House number. No more than 30 characters.	No
`Build`	Building or block number. No more than 10 characters.	No
`Apart`	Apartment or office number. No more than 255 characters.	No
`CityCode`	City phone code.	Yes
`Phone`	Contact phone number.	Yes
`PhoneExt`	Extension phone number for connection through office PBX.	No
`IMClient`	Type of instant messaging network — icq, jabber, skype, mail_agent.	No
`IMLogin`	Login in instant messaging network.	No
`ExtraMessage`	Additional information about the advertised product or service. No more than 200 characters.	No
`ContactEmail`	Email address. No more than 255 characters.	No
`WorkTime`	Organization's working hours or customer service hours. Specified as a string indicating the range of weekdays, working hours, and minutes. Weekdays are designated by numbers from 0 to 6, where 0 is Monday, 6 is Sunday. Minutes are specified in multiples of 15: 0, 15, 30, or 45. String format: `"day_from;day_to;hour_from;minutes_from;hour_to;min_to"` For example, the string `"0;4;10;0;18;0"` specifies the following schedule: `0;4` — Monday through Friday; `10;0` — from 10:00; `18;0` — until 18:00. The schedule can consist of several strings of the specified format, for example: "`0;4;10;0;18;0;5;6;11;0;16;0`". Here, in addition to the previous example, the following schedule is specified: `5;6` — Saturday through Sunday; `11;0` — from 11:00; `16;0` — until 16:00. 24-hour operation is specified by the string `"0;6;00;00;00;00"`.	Yes
`OGRN`	OGRN code for legal entities.	No
`PointOnMap`	`MapPoint` object specifying the coordinates of the client's location. A marker is placed on the map at these coordinates. If not specified, the marker is placed at the specified client address.	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 map area. From -180 to 180.	Yes
`y1`	Latitude of the lower left corner of the map area. From -90 to 90.	Yes
`x2`	Longitude of the upper right corner of the map area. From -180 to 180.	Yes
`y2`	Latitude of the upper right corner of the map area. From -90 to 90.	Yes
BannerPhraseInfo object
`PhraseID`	Keyword ID. To add a keyword, set to 0; to change keyword parameters, specify its ID.	No
`Phrase`	Keyword. May contain negative words, which are specified with a minus sign before the word, for example [lightning -thunder -rain]. Negative words common to several keywords should preferably be specified in the ad group's `MinusKeywords` parameter. Keyword length — no more than 4096 characters. The "!" operator before a negative word is not counted in the keyword length (the sequence "-!" is counted as one character). No more than 7 words in a keyword, excluding stop words and negative words. Each word and negative word — no more than 35 characters, excluding the minus before the negative word.	Yes
`IsRubric`	Indicator that the keyword is a Yandex Catalog category — Yes/No. Default value — No. With the value Yes, the passed keyword is ignored.	No
`Price`	Bid on Yandex search (in the currency specified in the `Currency` parameter). Used only if a manual bid management strategy is selected for the campaign. The maximum and minimum values are provided in the 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. 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 modification in the following cases: The MaximumCoverage strategy is selected for Yandex Advertising Network (YAN). The Default strategy is selected for YAN and the keyword is disabled on search due to a low click-through rate (CTR). This condition does not apply to new keywords, since keywords are no longer disabled for low CTR. The maximum and minimum values are provided in the 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. 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 MaximumCoverage strategy
`AutoBroker`	Enable/disable auto-broker. The parameter is not used, the passed value is ignored.	No
`AutoBudgetPriority`	Keyword priority when using automatic strategies. Possible values: Low — low priority; Medium — medium priority; High — high priority.	For WeeklyBudget strategy
`UserParams`	`PhraseUserParams` object. Contains values of substitution variables for forming the website link.	No
`Currency`	Currency in which bids are specified. Possible values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. The value must match the campaign currency. If the parameter is absent or equal to NULL, Yandex units are assumed. In this case, if the campaign is conducted in real currency, the bids passed by the application are converted to real currency before saving. If the value is not NULL and does not match the campaign currency (one of the campaigns), an error with code 245 is returned.	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`	Sitelink text (no more than 30 characters). Total length of texts of all sitelinks — no more than 66 characters.	Yes
`Href`	Sitelink address. May contain substitution variables.	Yes

Output data

Upon successful execution, the method returns an array containing the IDs of created/updated banners, as shown in the following example.

{
   "data": [33823946,33823947]
}

Input data examples

Python

[
   # Editing ad and group parameters
   {
      'BannerID': 2571700,
      'CampaignID': 1327837,
      'AdGroupName': u'Название группы 1',
      'Title': u'Заголовок объявления 1',
      'Text': u'Текст объявления 1',
      'Href': 'http://www.site.ru/page{param1}?ad={param2}',
      'Geo': '2,183,3',
      'ContactInfo': {
         'ContactPerson': u'Александр Громов',
         'Country': u'Россия',
         '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'все товары сертифицированы',
         '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'Доп. ссылка 1',
            'Href': 'http://www.site.ru/?q=qu&action=1'
         },
         {
            'Title': u'Доп. ссылка 2',
            'Href': 'http://www.site.ru/?q=qu&action=2'
         },
         {
            'Title': u'Доп. ссылка 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': 'Заголовок объявления 2',
      'Text': 'Текст объявления 2',
      'Href': 'http://www.site.ru/page{param1}?utm_content={phrase_id}'
   },
   # Adding an ad to a group
   {
      'BannerID': 0,
      'CampaignID': 1327837,
      'AdGroupID': 4571251,
      'Title': 'Заголовок объявления 3',
      'Text': 'Текст объявления 3',
      'Href': 'http://www.site.ru/page{param2}?utm_content={phrase_id}'
   }
]

PHP

array(
   # Editing ad and group parameters
   array(
      'BannerID' => 2571700,
      'CampaignID' => 1327837,
      'Title' => 'Заголовок объявления 1',
      'Text' => 'Текст объявления 1',
      'Href' => 'http://www.site.ru/page{param1}?ad={param2}',
      'Geo' => '2,183,3',
      'ContactInfo' => array(
         'ContactPerson' => 'Александр Громов',
         'Country' => 'Россия',
         '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' => 'все товары сертифицированы',
         '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' => 'Доп. ссылка 1',
            'Href' =>'http://www.site.ru/?q=qu&amp;action=1'
         ),
         array(
            'Title' => 'Доп. ссылка 2',
            'Href' =>'http://www.site.ru/?q=qu&amp;action=2'
         ),
         array(
            'Title' => 'Доп. ссылка 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' => 'Заголовок объявления 2',
      'Text' => 'Текст объявления 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' => 'Заголовок объявления 3',
      'Text' => 'Текст объявления 3',
      'Href' =>'http://www.site.ru/page{param2}?utm_content={phrase_id}'
   )
)

Perl

[
   # Editing ad and group parameters
   {
      'BannerID' => 2571700,
      'CampaignID' => 1327837,
      'Title' => 'Заголовок объявления 1',
      'Text' => 'Текст объявления 1',
      'Href' => 'http://www.site.ru/page{param1}?ad={param2}',
      'Geo' => '2,183,3',
      'ContactInfo' =>{
         'ContactPerson' => 'Александр Громов',
         'Country' => 'Россия',
         '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' => 'все товары сертифицированы',
         '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' => 'Доп. ссылка 1',
            'Href' =>'http://www.site.ru/?q=qu&amp;action=1'
         },
         {
            'Title' => 'Доп. ссылка 2',
            'Href' =>'http://www.site.ru/?q=qu&amp;action=2'
         },
         {
            'Title' => 'Доп. ссылка 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' => 'Заголовок объявления 2',
      'Text' => 'Текст объявления 2',
      'Href' =>'http://www.site.ru/page{param1}?utm_content={phrase_id}'
   },
   # Adding an ad to a group
   {
      'BannerID' => 0,
      'CampaignID' => 1327837,
      'AdGroupID' => 4571251,
      'Title' => 'Заголовок объявления 3',
      'Text' => 'Текст объявления 3',
      'Href' =>'http://www.site.ru/page{param2}?utm_content={phrase_id}'
   }
]

Was the article helpful?

CreateOrUpdateBanners

DeleteBanners