---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://yandex.com/dev/direct/doc/en/keywords/add.md
  - https://yandex.com/dev/direct/doc/ru/keywords/add.md
  - href: en/keywords/add.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    type: text/markdown
    title: llms.txt
sourcePath: en/ref-v5/keywords/add.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/direct/doc/en/llms.txt

# add

Creates keywords and autotargetings.

{% note alert %}

The method doesn't save duplicates of keywords. See [Duplicate keywords](https://yandex.com/dev/direct/doc/objects/keyword.html).

{% endnote %}

You can set a bid based on your campaign's strategy:

- If your campaign uses a manual strategy, you can specify the `Bid` parameter. If the strategy allows you to manage bids for ad networks separately, you can specify `Bid` and `ContextBid`.

  If an item in the input array contains parameters that are not appropriate for the strategy, the values of these parameters are saved and a warning is issued.

- If you've set up an automatic strategy for your campaign but specified the `Bid` and/or `ContextBid` parameter when creating keywords, these bid values **won't be applied**. When the strategy changes from automatic to manual, the bid will be selected by an automatic algorithm.

- If you've set up a manual strategy for your campaign that allows you to manage bids in ad networks separately, but you've specified the `ContextBid` parameter when creating keywords, this bid value will be applied later when the strategy changes to a manual strategy that allows you to manage bids separately.

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.

All targeting categories are enabled by default.

Categories for which neither "YES" nor "NO" is explicitly specified are considered enabled.

## Learn more

- [How the “add” method works](https://yandex.com/dev/direct/doc/best-practice/modify.html)
- [How to handle errors](https://yandex.com/dev/direct/doc/en/concepts/errors)
- [Autotargeting](https://yandex.com/dev/direct/doc/best-practice/auto-targeting.html)

## Restrictions {#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 check the limit on the number of keywords per ad group for a user, call the [Clients](https://yandex.com/dev/direct/doc/clients/clients.html).[get](https://yandex.com/dev/direct/doc/en/clients/get.md) or [AgencyClients](https://yandex.com/dev/direct/doc/agencyclients/agencyclients.html).[get](https://yandex.com/dev/direct/doc/agencyclients/get.html) method (look for the KEYWORDS_TOTAL_PER_ADGROUP element in the Restrictions array).

For restrictions on the number of words and characters in a keyword, see the [Quantitative restrictions](https://yandex.com/support/direct/en/troubleshooting/interface.html#limitations) section in Yandex Direct Help.

## Request {#input}

Request structure in JSON format:

```javascript translate=no
{
  "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 doesn't count toward the keyword length (the sequence "-!" is considered 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 info %}

If you have negative keywords that apply to all of an ad group's keywords, set them in the [NegativeKeywords](*NegativeKeywords) parameter for the ad group.

{% endnote %}

If the value is set to `---autotargeting`, an autotargeting object is created, and you can specify an automatic bid (`AutotargetingSearchBidIsAuto`).
|
Yes
||
||
`Bid`
|
long
|
The bid for displays in search results, multiplied by 1,000,000. Integer. Only for manual strategies.

Specified in the user's currency. Restrictions are listed in the currency reference. To get it, use the [Dictionaries](https://yandex.com/dev/direct/doc/en/dictionaries/dictionaries.md).[get](https://yandex.com/dev/direct/doc/en/dictionaries/get.md) method and specify the `Currencies` dictionary name in the request.
|
No
||
||
`AutotargetingSearchBidIsAuto`
|
YesNoEnum
|
A flag indicating whether [automatic bid](https://yandex.com/support/direct/en/impression-criteria/autotargeting.html#autotargeting__auto-bids) is enabled.

You can specify a manual bid (`Bid`) and enable automatic bids (`AutotargetingSearchBidIsAuto`) at the same time. In that case, automatic bid will be used, and manual bid will be applied if automatic bid is disabled.

If you've set a manual bid (`Bid`), the automatic bid value (`AutotargetingSearchBidIsAuto`) is set to NO unless you specify a different automatic bid.

If you haven't set a manual bid (`Bid`), the automatic bid value (`AutotargetingSearchBidIsAuto`) is set to YES unless you specify a different automatic bid.
|
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 user's currency. Restrictions are listed in the currency reference. To get it, use the [Dictionaries](https://yandex.com/dev/direct/doc/en/dictionaries/dictionaries.md).[get](https://yandex.com/dev/direct/doc/en/dictionaries/get.md) method and specify the `Currencies` dictionary name in the request.

<!-- source: en/_includes/bids/set/id-input/inage-ad-bid.md -->
{% note alert %}

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.

{% endnote %}
<!-- endsource: en/_includes/bids/set/id-input/inage-ad-bid.md -->
|
No
||
||
`StrategyPriority`
|
PriorityEnum
|
Priority of the keyword or autotargeting: LOW, NORMAL or HIGH. Only for automatic strategies.

<!-- source: en/_includes/strategy-priority-note.md -->
{% note alert %}

This parameter is not used, and the passed value is ignored.

{% endnote %}
<!-- endsource: en/_includes/strategy-priority-note.md -->
|
No
||
||
`UserParam1`
|
string
|
Value of the `{param1}` [substitution variable](https://yandex.com/dev/direct/doc/objects/keyword.html). Maximum of 255 characters.
|
No
||
||
`UserParam2`
|
string
|
Value of the `{param2}` [substitution variable](https://yandex.com/dev/direct/doc/objects/keyword.html). Maximum of 255 characters.
|
No
||
||
`AutotargetingCategories`
|
array of [AutotargetingCategoriesAddItem](#AutotargetingCategoriesAddItem)
|
Targeting categories to be added.


{% note alert %}

This structure is deprecated and will soon cease to be supported. You can't pass both `AutotargetingCategories` and `AutotargetingSettings` at the same time. A validation error will occur if you try to do this.

{% endnote %}

|
No
||
||
`AutotargetingSettings`
|
[AutotargetingSettingsAddItem](#AutotargetingSettingsAddItem)
|
Targeting settings to add.
|
No
||

||
**AutotargetingCategoriesAddItem structure**
||
||
`Category`
|
AutotargetingCategoriesEnum
|
Targeting category:

- EXACT: The targeted queries. The ad is highly relevant to the user's search.
- ALTERNATIVE: Alternative queries. The user is looking for a product that can be replaced by the product you're promoting. The ad might also match the query in this case.
- COMPETITOR: Queries that mention your competitors. The user is looking for the promoted product via competitor brands.
- BROADER: Broad queries. Queries that show interest in a product type your offer belongs to.
- ACCESSORY: Related queries. Queries for products that might interest the user in relation to the advertised product or service.


{% note alert %}

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:

{% endnote %}


#|
||
**API**
|
**Web interface**
||
||
Enabled `EXACT` category.
|
Enabled "Exact" and "Narrow" categories.
||
||
Enabled `COMPETITOR` category (provided it's the only category enabled).
|
Enabled Competitors brand mention option + the other brand mention options are disabled + all categories are enabled.
||
||
Enabled `COMPETITOR` category (provided it isn't the only category enabled).
|
Enabled Competitors brand mention option.
||
||
Disabled `COMPETITOR` category.
|
Disabled Competitors brand mention option.
||
|# 

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

- Exact: Targeted queries. The ad is highly relevant to the user's search.
- Narrow: Narrow queries. The ad is broader than the user's search.
- Alternative: Alternative queries. The user is looking for a product that can be replaced by the product you're promoting. The ad might also meet the query in this case.
- Accessory: Related queries. Queries for products that might interest the user in relation to the advertised product or service.
- Broader: Broad queries. Queries that show interest in a product type your offer belongs to.
|
No
||
||
`BrandOptions`
|
AutotargetingSettingsBrandOptionsFieldNames
|
Brand mention settings. Available options:

- WithoutBrands: Non-branded queries.
- WithAdvertiserBrand: Queries mentioning your brand.
- WithCompetitorsBrand: Queries mentioning competitor brands.
|
No
||
|# 


## Response {#output}

Response structure in JSON format:

```javascript translate=no
{
  "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 aren't any errors. See the section [Operations on object arrays](https://yandex.com/dev/direct/doc/best-practice/modify.html).
||
||
`Warnings`
|
array of [ExceptionNotification](https://yandex.com/dev/direct/doc/best-practice/modify.html)
|
Warnings that occurred during the operation.
||
||
`Errors`
|
array of [ExceptionNotification](https://yandex.com/dev/direct/doc/best-practice/modify.html)
|
Errors that occurred during the operation.
||
|#