Documentation

add

Creates audience targets and sets bids and priorities for the created targets.
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.

How bids and priorities are applied

The bid or priority is used depending on which display strategy is selected in the campaign:

  • If a manual strategy is set up in the campaign, the ContextBid parameter is used.

  • If the campaign has an automatic strategy set up, the StrategyPriority parameter is used: ads with higher priority according to targeting conditions are moved to the best positions when possible, and they are the last ones to be stopped when budget funds are low.

If there isn't a parameter appropriate to the strategy, the default value is preserved.

  • If the strategy is manual but the bid isn't specified, the minimum bid is set by default (it depends on the advertiser's currency).

  • If the strategy is automatic but the priority isn't specified, the average priority is set by default.

If a parameter is specified that isn't appropriate for the strategy, its value is saved.

  • If the strategy is manual but the priority is specified, this priority value will be applied later when the strategy is switched to an automatic one.

  • If the strategy is automatic but a bid is specified, this bid value will not be applied: if the strategy switches from automatic to manual, the bid will be set according to an automatic algorithm.

Restrictions

Audience targets with a retargeting list are allowed only for the TEXT_AD_GROUP or MOBILE_APP_AD_GROUP types of ad groups.

Audience targets with mobile app categories are allowed only for the MOBILE_APP_AD_GROUP type of ad group.

Maximum of 50 audience targets per ad group.

Maximum of 1000 audience targets per method call.

Request

Request structure in JSON format:

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

Audience targets to add.

Required

Yes

]no-highlight]
": [{ /* AudienceTargetAddItem */ "AdGroupId
[no-highlight[

ID of the group to add the audience target to.

Required

Yes

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

ID of the retargeting list. Retargeting lists must have the scope FOR_TARGETS_AND_ADJUSTMENTS.

The ID must be unique within the ad group (you can‘t have two audience targets with identical retargeting list IDs).

Required

Either RetargetingListId or InterestId

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

ID of an app category interest.

To get the list of app categories, use the Dictionaries.get method and specify the dictionary name Interests in the request. You can only use interests that have the IsTargetable parameter set to YES in the reference list.

This parameter can only be used with the MOBILE_APP_AD_GROUP type of ad group. The ID must be unique within the ad group (you can‘t have two audience targets with identical interest IDs).

Required

Either RetargetingListId or InterestId

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

The bid in ad networks, multiplied by 1,000,000. Integer. Only used for a manual strategy.

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

The default value is the minimum bid.

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[

The priority of the audience target: LOW, NORMAL or HIGH. Only used for an automatic strategy.

The default value is NORMAL.

Required

No

]no-highlight]
": ( "LOW" | "NORMAL" | "HIGH" ) }, ... ] /* required */ } }
Parameter Type Description Required
params structure (for JSON) / AddRequest structure (for SOAP)
AudienceTargets array of AudienceTargetAddItemAudience targets to add.Yes
AudienceTargetAddItem structure
AdGroupId longID of the group to add the audience target to.Yes
RetargetingListId long

ID of the retargeting list. Retargeting lists must have the scope FOR_TARGETS_AND_ADJUSTMENTS.

The ID must be unique within the ad group (you can't have two audience targets with identical retargeting list IDs).

Either RetargetingListId or InterestId
InterestId long

ID of an app category interest.

To get the list of app categories, use the Dictionaries
[no-highlight[

This service is for getting reference data: regions, time zones, currency exchange rates, metro stations, restrictions on parameter values, and other information.

More Dictionaries

]no-highlight]
.get
[no-highlight[

Returns reference data: regions, time zones, currency exchange rates, metro stations, restrictions on parameter values, ad exchanges (SSPs), and other information.

More get

]no-highlight]
method and specify the dictionary name Interests in the request. You can only use interests that have the IsTargetable parameter set to YES in the reference list.

This parameter can only be used with the MOBILE_APP_AD_GROUP type of ad group. The ID must be unique within the ad group (you can't have two audience targets with identical interest IDs).

ContextBid long

The bid in ad networks, multiplied by 1,000,000. Integer. Only used for a manual strategy.

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

The default value is the minimum bid.

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

The priority of the audience target: LOW, NORMAL or HIGH. Only used for an automatic strategy.

The default value is NORMAL.

No

Response

Response structure in JSON format:

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

Results of adding audience targets.

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

The ID of a created audience target. 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) }, ... ] }, ... ] } }
Parameter Type Description
result structure (for JSON) / AddResponse structure (for SOAP)
AddResults array of ActionResultResults of adding audience targets.
ActionResult structure
Id long

The ID of a created audience target. 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.