add
Creates keywords and autotargetings.
Manual bid management will be disabled for the Yandex Advertising Network. Learn more.
- Starting April 22, 2024, you will no longer be able to create new campaigns with a manual strategy. The "Network.BiddingStrategyType" parameter in the "add" and "update" methods will no longer support the MAXIMUM_COVERAGE strategy for TextCampaign and MobileAppCampaign campaigns. These campaigns will also cease to support the "resume" method. Attempting to use it will result in a validation error.
- Starting May 20, 2024, you will no longer be able to edit bids in active campaigns: the "set" method will no longer support the "Bids.ContextBid (KeywordBids.NetworkBid)" parameter. Attempting to use it will result in a validation error.
- In June, 2024, active campaigns will be stopped. Attempting to use the "resume" method for campaigns with the MAXIMUM_COVERAGE strategy specified in the "Network.BiddingStrategyType" parameter will return a validation error unless you switch to an available strategy. In the future, the strategy for these stopped and archived campaigns will be changed to "WB_MAXIMUM_CLICKS" (the campaigns themselves won't be re-launched or unarchived).
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 use the StrategyPriority parameter: keywords with higher priority are allocated more traffic when possible, and they are the last ones to be stopped when budget funds are 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 for ContextBid: A bid calculated from bids for keywords in the ad group (if the group has no keywords, the minimum bid is used).
For autotargeting for Bid: An automatic bid. If automatic bid is disabled: A bid calculated based on bids for keywords in the ad group (a manual bid is always calculated, but it's only used when automatic bid is disabled). If there are no keywords in the ad group, 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.
Bids and prices are passed via the Yandex Direct API as integer numbers. The value passed is a bid or price multiplied by 1,000,000.
All bids and prices are shown in the advertiser's currency.
All targeting categories are enabled by default.
Categories for which neither “YES” nor “NO” is explicitly specified are considered enabled.
Restrictions
Maximum of 1000 objects per method call.
Maximum of 1 autotargeting per ad group.
You cannot add keywords to an ad group that has the CPM_BANNER_AD_GROUP type and USER_PROFILE subtype, or to a DYNAMIC_TEXT_AD_GROUP type of ad group.
You cannot add autotargetings to an ad group with the DYNAMIC_TEXT_AD_GROUP or CPM_BANNER_AD_GROUP type.
To get the limit on the number of keywords per ad group for an advertiser, use the Clients.get or AgencyClients.get method (see the KEYWORDS_TOTAL_PER_ADGROUP element in the Restrictions array).
For restrictions on the number of words and characters in a keyword, see the section Quantitative restrictions in the Help for Yandex.Direct.
Request
Request structure in JSON format:
{
"method": "add",
"params": { /* params */
"Keywords": [{ /* KeywordAddItem */
"Keyword": (string), /* required */
"AdGroupId": (long), /* required */
"Bid": (long),
"AutotargetingSearchBidIsAuto" : ("YES" | "NO"),
"ContextBid": (long),
"StrategyPriority": ( "LOW" | "NORMAL" | "HIGH" ),
"UserParam1": (string),
"UserParam2": (string),
"AutotargetingCategories" : [{ /* AutotargetingCategoriesAddItem */
"Category" : ("EXACT"|"ALTERNATIVE"|"COMPETITOR"|"BROADER"|"ACCESSORY") /* required */,
"Value" : ("YES"|"NO") /* required */
}, ...],
"AutotargetingSettings" : {
"Categories" : {
"Exact" : ("YES"|"NO"),
"Narrow" : ("YES"|"NO"),
"Alternative" : ("YES"|"NO"),
"Accessory" : ("YES"|"NO"),
"Broader" : ("YES"|"NO")
},
"BrandOptions" : {
"WithoutBrands" : ("YES"|"NO"),
"WithAdvertiserBrand" : ("YES"|"NO"),
"WithCompetitorsBrand" : ("YES"|"NO")
}
}
}, ... ] /* required */
}
}| Parameter | Type | Description | Required | ||||||||||||||||||||
| Params structure (for JSON) / AddRequest structure (for SOAP) | |||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Keywords | array of KeywordAddItem | Keywords and autotargetings to add. | Yes | ||||||||||||||||||||
| KeywordAddItem structure | |||||||||||||||||||||||
AdGroupId | long | ID 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 “-!” counts as a single character). Maximum of 7 words per keyword, not counting stop words and negative keywords. Each word can have 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 | Yes | ||||||||||||||||||||
Bid | long | The bid on search, multiplied by 1,000,000. Integer. Only for manual strategies. Specified in the advertiser's currency. Constraints are listed in the currencies dictionary. To get it, use the Dictionaries.get method and specify the Currencies dictionary name in the request. | No | ||||||||||||||||||||
AutotargetingSearchBidIsAuto | YesNoEnum | A flag indicating whether automatic bid is enabled. You can specify both a manual bid (Bid) and enable automatic bid (AutotargetingSearchBidIsAuto). In that case, automatic bid will be used, and manual bid will be applied if automatic bid is disabled. If a manual bid (Bid) is specified: the automatic bid value (AutotargetingSearchBidIsAuto) is set to NO unless a different automatic bid value is delivered explicitly. If no manual bid (Bid) is specified: the automatic bid value (AutotargetingSearchBidIsAuto) is set to YES unless a different automatic bid value is delivered explicitly. | 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. Constraints are listed in the currencies dictionary. To get it, use the Dictionaries.get method and specify the Currencies dictionary name in the request. 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 | PriorityEnum | Priority of the keyword or autotargeting: LOW, NORMAL or HIGH. Only for automatic strategies. | No | ||||||||||||||||||||
UserParam1 | string | The value of the {param1} substitution variable. Maximum of 255 characters. | No | ||||||||||||||||||||
UserParam2 | string | The value of the {param2} substitution variable. Maximum of 255 characters. | No | ||||||||||||||||||||
AutotargetingCategories | array of AutotargetingCategoriesAddItem | Targeting categories to be added. Attention. This structure is deprecated and will soon cease to be supported. You can't pass both | No | ||||||||||||||||||||
AutotargetingSettings | AutotargetingSettingsAddItem | Targeting settings to add. | No | ||||||||||||||||||||
| AutotargetingCategoriesAddItem structure | |||||||||||||||||||||||
Category | AutotargetingCategoriesEnum | Targeting category:
Attention. This field is deprecated and will soon cease to be supported. The settings specified using the API are converted for the web interface as follows:
| Yes | ||||||||||||||||||||
Value | YesNoEnum | The flag indicating that the specified targeting category is enabled. All targeting categories are enabled by default. | Yes | ||||||||||||||||||||
| AutotargetingSettingsAddItem structure | |||||||||||||||||||||||
Categories | AutotargetingSettingsCategoriesFieldNames | Targeting categories. Available options:
| No | ||||||||||||||||||||
BrandOptions | AutotargetingSettingsBrandOptionsFieldNames | Brand mention settings. Available options:
| No | ||||||||||||||||||||
| Parameter | Type | Description | Required | ||||||||||||||||||||
| Params structure (for JSON) / AddRequest structure (for SOAP) | |||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Keywords | array of KeywordAddItem | Keywords and autotargetings to add. | Yes | ||||||||||||||||||||
| KeywordAddItem structure | |||||||||||||||||||||||
AdGroupId | long | ID 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 “-!” counts as a single character). Maximum of 7 words per keyword, not counting stop words and negative keywords. Each word can have 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 | Yes | ||||||||||||||||||||
Bid | long | The bid on search, multiplied by 1,000,000. Integer. Only for manual strategies. Specified in the advertiser's currency. Constraints are listed in the currencies dictionary. To get it, use the Dictionaries.get method and specify the Currencies dictionary name in the request. | No | ||||||||||||||||||||
AutotargetingSearchBidIsAuto | YesNoEnum | A flag indicating whether automatic bid is enabled. You can specify both a manual bid (Bid) and enable automatic bid (AutotargetingSearchBidIsAuto). In that case, automatic bid will be used, and manual bid will be applied if automatic bid is disabled. If a manual bid (Bid) is specified: the automatic bid value (AutotargetingSearchBidIsAuto) is set to NO unless a different automatic bid value is delivered explicitly. If no manual bid (Bid) is specified: the automatic bid value (AutotargetingSearchBidIsAuto) is set to YES unless a different automatic bid value is delivered explicitly. | 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. Constraints are listed in the currencies dictionary. To get it, use the Dictionaries.get method and specify the Currencies dictionary name in the request. 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 | PriorityEnum | Priority of the keyword or autotargeting: LOW, NORMAL or HIGH. Only for automatic strategies. | No | ||||||||||||||||||||
UserParam1 | string | The value of the {param1} substitution variable. Maximum of 255 characters. | No | ||||||||||||||||||||
UserParam2 | string | The value of the {param2} substitution variable. Maximum of 255 characters. | No | ||||||||||||||||||||
AutotargetingCategories | array of AutotargetingCategoriesAddItem | Targeting categories to be added. Attention. This structure is deprecated and will soon cease to be supported. You can't pass both | No | ||||||||||||||||||||
AutotargetingSettings | AutotargetingSettingsAddItem | Targeting settings to add. | No | ||||||||||||||||||||
| AutotargetingCategoriesAddItem structure | |||||||||||||||||||||||
Category | AutotargetingCategoriesEnum | Targeting category:
Attention. This field is deprecated and will soon cease to be supported. The settings specified using the API are converted for the web interface as follows:
| Yes | ||||||||||||||||||||
Value | YesNoEnum | The flag indicating that the specified targeting category is enabled. All targeting categories are enabled by default. | Yes | ||||||||||||||||||||
| AutotargetingSettingsAddItem structure | |||||||||||||||||||||||
Categories | AutotargetingSettingsCategoriesFieldNames | Targeting categories. Available options:
| No | ||||||||||||||||||||
BrandOptions | AutotargetingSettingsBrandOptionsFieldNames | Brand mention settings. Available options:
| No | ||||||||||||||||||||
Response
Response structure in JSON format:
{
"result": { /* result */
"AddResults": [{ /* ActionResult */
"Id": (long),
"Warnings": [{ /* ExceptionNotification */
"Code": (int), /* required */
"Message": (string), /* required */
"Details": (string)
}, ... ],
"Errors": [{ /* ExceptionNotification */
"Code": (int), /* required */
"Message": (string), /* required */
"Details": (string)
}, ... ]
}, ... ] /* required */
}
}| Parameter | Type | Description |
| Result structure (for JSON) / AddResponse structure (for SOAP) | ||
|---|---|---|
AddResults | array of ActionResult | Results of adding keywords or autotargetings. |
| ActionResult structure | ||
Id | long | ID of the created keyword or autotargeting. Returned if there are no errors, see Operations on object arrays. |
Warnings | array of ExceptionNotification | Warnings that occurred during the operation. |
Errors | array of ExceptionNotification | Errors that occurred during the operation. |
| Parameter | Type | Description |
| Result structure (for JSON) / AddResponse structure (for SOAP) | ||
|---|---|---|
AddResults | array of ActionResult | Results of adding keywords or autotargetings. |
| ActionResult structure | ||
Id | long | ID of the created keyword or autotargeting. Returned if there are no errors, see Operations on object arrays. |
Warnings | array of ExceptionNotification | Warnings that occurred during the operation. |
Errors | array of ExceptionNotification | Errors that occurred during the operation. |