Documentation

add

Creates keywords and autotargetings.
Attention! The method does not save duplicates of keywords. See Duplicate keywords.

The bid or priority can be assigned according to which strategy is selected in the campaign:

  • If the campaign has an automatic strategy set up, you can specify the StrategyPriority parameter. Keywords with a higher priority are moved to better positions when possible, and they are the last ones turned off when the budget is low.

  • If the campaign has a manual strategy set up, you can specify the Bid parameter. If the strategy lets you manage bids for ad networks separately, you can specify Bid and ContextBid.

If an item in the input array contains parameters that aren't appropriate to the strategy (for example, priority for a manual strategy), the values of these parameters are saved, and a warning is issued.

  • If an automatic strategy is set up in a campaign, but the Bid and/or ContextBid parameters were set when creating keywords, these bid values will not be applied. When the automatic strategy is switched to a manual one, an automatic algorithm selects the bids to set.

  • If a manual strategy is set up in the campaign, but the StrategyPriority parameter is set when creating keywords, the set value will be applied later when the strategy is switched to an automatic one.

  • If the campaign has a manual strategy without independent bid management in ad networks, but the ContextBid parameter is set when creating keywords, this bid value will be applied later when the strategy is switched to a manual strategy with independent bid management.

If the strategy allows for setting bids but the bid is not specified, the default setting is:

  • For a keyword – The minimum bid.

  • For autotargeting – A bid calculated from bids for keywords in the ad group (if the group doesn't have any keywords, the minimum bid is used).

If the strategy allows for setting priority but the priority is not specified, the average priority is set by default.

Attention! 
  • Bids and prices are passed via the Yandex.Direct API as integer numbers. The value that is passed represents the bid or price multiplied by 1,000,000.

  • All bids and prices are shown in the advertiser's currency.

Restrictions

Maximum of 200 keywords per ad group.

Maximum of 1 autotargeting per ad group.

Maximum of 1000 objects per method call.

Maximum of 4096 characters per keyword, including negative keywords.

Maximum of 7 words in a keyword (not including stop words and negative keywords).

Request

Request structure in JSON format:

{
  "method": "add",
  "params": {  
    "Keywords
[no-highlight[

Keywords and autotargetings to add.

Required

Yes

]no-highlight]
": [ { /* KeywordAddItem */ "Keyword
[no-highlight[

Keywords.

It can contain negative keywords, which are specified with the minus sign before the word, such as lightning -thunder -rain.

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.

Note. If you have negative keywords that apply to all of an ad group‘s keywords, set them in the NegativeKeywords parameter for the ad group.

If the value is set to ---autotargeting, an autotargeting object is created.

Required

Yes

]no-highlight]
": (string), /* required */ "AdGroupId
[no-highlight[

ID of the group to add the keyword or autotargeting to.

Required

Yes

]no-highlight]
": (long), /* required */ "Bid
[no-highlight[

The bid for displays in search results, multiplied by 1,000,000. Integer. Only for manual strategies.

Specified in the advertiser‘s currency. For restrictions, see the page Minimum and maximum CPC.

Required

No

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

The bid in ad networks, multiplied by 1,000,000. Integer. Only for manual strategies with independent bid management in the Yandex Advertising Network.

Specified in the advertiser‘s currency. For restrictions, see the page Minimum and maximum CPC.

Attention! An image ad can be displayed only if the bid is at least as high as the minimum bid for an ad with an image.

Required

No

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

Priority of the keyword or autotargeting: LOW, NORMAL or HIGH. Only for automatic strategies.

Required

No

]no-highlight]
": ( "LOW" | "NORMAL" | "HIGH" ), "UserParam1
[no-highlight[

Value of the {param1}substitution variable. Maximum of 255 characters.

Required

No

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

Value of the {param2}substitution variable. Maximum of 255 characters.

Required

No

]no-highlight]
": (string) } ] /* required */ } }
Parameter Type Description Required
params structure (for JSON) / AddRequest structure (for SOAP)
Keywords array of KeywordAddItemKeywords and autotargetings to add.Yes
KeywordAddItem structure
AdGroupId longID of the group to add the keyword or autotargeting to.Yes
Keyword string

Keywords.

It can contain negative keywords, which are specified with the minus sign before the word, such as lightning -thunder -rain.

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.

Note. If you have negative keywords that apply to all of an ad group's keywords, set them in the NegativeKeywords
[no-highlight[

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

A negative 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. Spaces, dashes, and operators are not counted as part of 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]
parameter for the ad group.

If the value is set to ---autotargeting, an autotargeting object is created.

Yes
Bid long

The bid for displays in search results, multiplied by 1,000,000. Integer. Only for manual strategies.

Specified in the advertiser's currency. For restrictions, see the page Minimum and maximum CPC.

No
ContextBid long

The bid in ad networks, multiplied by 1,000,000. Integer. Only for manual strategies with independent bid management in the Yandex Advertising Network.

Specified in the advertiser's currency. For restrictions, see the page Minimum and maximum CPC.

Attention! An image ad can be displayed only if the bid is at least as high as the minimum bid for an ad with an image.
No
StrategyPriority PriorityEnumPriority of the keyword or autotargeting: LOW, NORMAL or HIGH. Only for automatic strategies.No
UserParam1 stringValue of the {param1} substitution variable. Maximum of 255 characters.No
UserParam2 stringValue of the {param2} substitution variable. Maximum of 255 characters.No

Response

Response structure in JSON format:

{
  "result": {  
    "AddResults
[no-highlight[

Results of adding keywords or autotargetings.

]no-highlight]
": [{ /* ActionResult */ "Id
[no-highlight[

ID of the created keyword or autotargeting. Returned if there are no errors; see the section Operations on object arrays.

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

Warnings that occurred during the operation.

]no-highlight]
": [{ /* ExceptionNotification */ "Code": (int), /* required */ "Message": (string), /* required */ "Details": (string) }, ... ], "Errors
[no-highlight[

Errors that occurred during the operation.

]no-highlight]
": [{ /* ExceptionNotification */ "Code": (int), /* required */ "Message": (string), /* required */ "Details": (string) }, ... ] }, ... ] /* required */ } }
Parameter Type Description
result structure (for JSON) / AddResponse structure (for SOAP)
AddResults array of ActionResultResults of adding keywords or autotargetings.
ActionResult structure
Id longID of the created keyword or autotargeting. Returned if there are no errors; see the section Operations on object arrays.
Warnings array of ExceptionNotification

Warnings that occurred during the operation.

Errors array of ExceptionNotification

Errors that occurred during the operation.