add

Creates smart banner targeting filters and assigns CPC, CPA, or priority to the created filters.

  1. Restrictions
  2. Request
  3. Response

CPC, CPA, or priority is used depending on which display strategy is selected in the campaign:

  • If the campaign uses the AVERAGE_ROI strategy, the StrategyPriority parameter is used: filters with higher priority get more traffic in search results or audience share in ad networks if possible. If the budget runs low, they are the last ones to be disabled.
  • If the campaign uses the AVERAGE_CPA_PER_CAMP or AVERAGE_CPA_PER_FILTER strategy, the AverageCpc or AverageCpa parameters are used.
  • If the campaign uses the AVERAGE_CPC_PER_CAMP or AVERAGE_CPC_PER_FILTER strategy, the AverageCpc parameter is used.

If a bid or priority is specified that does not match the strategy, it is ignored.

If the strategy involves setting a bid and the bid is omitted, the bid from the strategy settings is used. If the strategy involves setting priority and the priority is omitted, an error is returned.

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

Filters for smart banners can only be added to a SMART_AD_GROUP type of ad group.

Maximum of 50 filters per ad group.

Maximum of 1000 filters per method call.

Request

Request structure in JSON format:

{
  "method": "add",
  "params": { /* params */
    "SmartAdTargets": [{ /* SmartAdTargetAddItem */
      "Name": (string), /* required */
      "AdGroupId": (long), /* required */
      "AverageCpc": (long),
      "AverageCpa": (long),
      "StrategyPriority": ( "LOW" | "NORMAL" | "HIGH" ),
      "Audience": ( "INTERESTED_IN_SIMILAR_PRODUCTS" | "VISITED_PRODUCT_PAGE" | "ALL_SEGMENTS" ), /* required */
      "Conditions": { /* ConditionsArray */ 
        "Items": [{ /* ConditionsItem */ 
          "Operand": (string), /* required */
          "Operator": ( "GREATER_THAN" | "LESS_THAN" | "IN_RANGE" | "EXISTS" | "EQUALS_ANY" | "CONTAINS_ANY" | "NOT_CONTAINS_ALL" ), /* required */
          "Arguments": [(string), ... ] /* required */
        }, ... ] /* required */
      },
      "AvailableItemsOnly": ( "YES" | "NO" )
    }, ... ]
  }
}
Parameter Type Description Required
Params structure (for JSON) / AddRequest structure (for SOAP)
SmartAdTargets array of SmartAdTargetAddItem Filters. Yes
SmartAdTargetAddItem structure
Name string Name of the filter (maximum of 100 characters). Yes
AdGroupId long ID of the group to add the filter to. Yes
AverageCpc long Average CPC multiplied by 1,000,000. Integer.

Specified in the advertiser's currency. Restrictions are listed in the currency reference. To get it, use the Dictionaries.get method and specify the Currencies dictionary name in the request.

No
AverageCpa long Average CPC multiplied by 1,000,000. Integer.

Specified in the advertiser's currency. Restrictions are listed in the currency reference. To get it, use the Dictionaries.get method and specify the Currencies dictionary name in the request.

No
StrategyPriority PriorityEnum Priority: LOW, NORMAL or HIGH. Used only for the AVERAGE_ROI strategy. For the AVERAGE_ROI strategy
Audience AudienceEnum Target audience:
  • INTERESTED_IN_SIMILAR_PRODUCTS —Users who showed interest in similar products online.
  • VISITED_PRODUCT_PAGE — Users who viewed products on the advertiser's site.
  • ALL_SEGMENTS — Both groups.
Yes
Conditions ConditionsArray

Rules for selecting product offers. A product offer is selected for display if it meets all the selection rules at the same time.

If this parameter is omitted, the filter selects all product offers from the feed (ITEMS_ALL selection type).
Restriction. If the type of feed in an ad group is FLIGHTS or RETAIL, selection rules are not used.
No
AvailableItemsOnly YesNoEnum Select only products in stock. The default value is NO.

Use the YES value only if the feed has the available field. Otherwise, the request will not pass validation.

No
ConditionsArray structure
Items array of ConditionsItem Selection rules. Maximum of 10 items in the array. The total length of the selection rules is a maximum of 65 KB (in JSON). Yes
ConditionsItem structure
Operand string

Feed parameter.

For a description of the fields for each type of feed, see Configuring filters in the Help for Yandex.Direct.

Yes
Operator StringConditionOperatorEnum

Comparison operator. For information on the compatibility of feed fields and operators, as well as restrictions on values, see Selection rule.

Yes
Arguments array of string

An array of strings to compare the operand to.

Yes

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)
      }, ... ] 
    }, ... ]
  }
}
Parameter Type Description
Result structure (for JSON) / AddResponse structure (for SOAP)
AddResults array of ActionResult Results of adding filters.
ActionResult structure
Id long The ID of the newly created filter. Returned if there aren't any 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.