Documentation

add

Creates retargeting lists.

Restrictions

Maximum of 2000 retargeting lists per advertiser.

Maximum of 1000 retargeting lists per method call.

Maximum of 50 retargeting rules per list, and 250 goals or segments per rule.

Request

Request structure in JSON format:

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

Retargeting lists to add.

Required

Yes

]no-highlight]
": [{ /* RetargetingListAddItem */ "Name
[no-highlight[

Name of the retargeting list (maximum of 250 characters).

Required

Yes

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

Text note for the retargeting list (maximum of 4096 characters).

Required

No

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

Rules for selecting site users. Maximum of 50 items in the array. In order for the retargeting list to apply, the user must meet all the rules at once.

Required

Yes

]no-highlight]
": [{ /* RetargetingListRuleItem */ "Arguments
[no-highlight[

Yandex.Metrica goals and segments, or Yandex.Audience segments. Maximum of 250 items in the array.

To get a list of available goals and segments, use the GetRetargetingGoals (Live) method in the Live 4 version of the API.

Required

Yes

]no-highlight]
": [{ /* RetargetingListRuleArgumentItem */ "MembershipLifeSpan
[no-highlight[

Number of days (from 1 to 90) for checking whether goals are completed or segments are matched.

Required

For Yandex.Metrica goals and segments

]no-highlight]
": (int), "ExternalId
[no-highlight[

ID of the goal or segment.

To get a list of goals and segments available to the advertiser, use the GetRetargetingGoals (Live) method in the Live 4 version of the API.

Required

Yes

]no-highlight]
": (long) /* required */ }, ... ], /* required */ "Operator
[no-highlight[

Logical operator for the retargeting list:

  • ALL — The rule is met if the user completed all the goals and is included in all the segments.

  • ANY — The rule is met if the user completed at least one of the goals or the user‘s session is included in at least one of the segments.

  • NONE — The rule is met if the user didn‘t complete any of the goals and the user‘s session isn‘t included in any of the segments.

A retargeting list that uses segments from Yandex.Metrica or Yandex.Audience must contain at leat one rule and the logical operator ALL or ANY. A retargeting list that consists exclusively of rules with the NONE operator can only contain Yandex.Metrica goals.

Required

Yes

]no-highlight]
": ( "ALL" | "ANY" | "NONE" ) /* required */ }, ... ] /* required */ }, ... ] } }
Parameter Type Description Required
params structure (for JSON) / AddRequest structure (for SOAP)
RetargetingLists array of RetargetingListAddItemRetargeting lists to add.Yes
RetargetingListAddItem structure
Name stringName of the retargeting list (maximum of 250 characters).Yes
Description stringText note for the retargeting list (maximum of 4096 characters).No
Rules array of RetargetingListRuleItemRules for selecting site users. Maximum of 50 items in the array. In order for the retargeting list to apply, the user must meet all the rules at once.Yes
RetargetingListRuleItem structure
Arguments array of RetargetingListRuleArgumentItem

Yandex.Metrica goals and segments, or Yandex.Audience segments. Maximum of 250 items in the array.

To get a list of available goals and segments, use the GetRetargetingGoals (Live) method in the Live 4 version of the API.

Yes
Operator RetargetingListRuleOperatorEnum

Logical operator for the retargeting list:

  • ALL — The rule is met if the user completed all the goals and is included in all the segments.

  • ANY — The rule is met if the user completed at least one of the goals or the user's session is included in at least one of the segments.

  • NONE — The rule is met if the user didn't complete any of the goals and the user's session isn't included in any of the segments.

A retargeting list that uses segments from Yandex.Metrica or Yandex.Audience must contain at leat one rule and the logical operator ALL or ANY. A retargeting list that consists exclusively of rules with the NONE operator can only contain Yandex.Metrica goals.

Yes
RetargetingListRuleArgumentItem structure
MembershipLifeSpan intNumber of days (from 1 to 90) for checking whether goals are completed or segments are matched.For Yandex.Metrica goals and segments
ExternalId long

ID of the goal or segment.

To get a list of goals and segments available to the advertiser, use the GetRetargetingGoals (Live) method in the Live 4 version of the API.

Yes

Response

Response structure in JSON format:

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

Results of adding retargeting lists.

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

ID of the created retargeting list. 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 retargeting lists.
ActionResult structure
Id longID of the created retargeting list. 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.