add

Creates bid adjustments.

  1. Restrictions
  2. Request
  3. Response
  4. Examples

Restrictions

Maximum of 1 mobile adjustment per campaign or ad group.

Maximum of 1 video adjustment per campaign or ad group.

Maximum of 12 gender and age adjustments per campaign or ad group.

Maximum of 100 website user adjustments per campaign or ad group.

Mobile adjustments can't be created for campaigns and ad groups for mobile app advertising.

You can only create video adjustments for campaigns and groups of text and image ads.

Regional bid adjustments can only be set on the campaign level.

In display campaigns, adjustments can only be set on the group level and only for groups with the KEYWORDS subtype.

Request

Request structure in JSON format:

{
  "method": "add",
  "params": { /* params */
    "BidModifiers": [{  /* BidModifierAddItem */
      "MobileAdjustment": {  /* MobileAdjustmentAdd */
        "BidModifier": (int) /* required */
      },
      "DemographicsAdjustments": [{  /* DemographicsAdjustmentAdd */
        "Gender": ( "GENDER_MALE" | "GENDER_FEMALE" ),
        "Age": ( "AGE_0_17" | "AGE_18_24" | "AGE_25_34" | "AGE_35_44" | "AGE_45" | "AGE_45_54" | "AGE_55" ),
        "BidModifier": (int) /* required */
      }, ... ],
      "RetargetingAdjustments": [{  /* RetargetingAdjustmentAdd */
        "RetargetingConditionId": (long), /* required */
        "BidModifier": (int) /* required */
      }, ... ],
      "RegionalAdjustments": [{    /* RegionalAdjustmentAdd */
        "RegionId": (long), /* required */
        "BidModifier": (int) /* required */
      }, ... ],
      "VideoAdjustment": [{ /* VideoAdjustmentAdd */
        "BidModifier": (int) /* required */
      }, ... ],
      "CampaignId": (long),
      "AdGroupId": (long)
    }, ... ] /* required */
  }
}
Parameter Type Description Required
Params structure (for JSON) / AddRequest structure (for SOAP)
BidModifiers array of BidModifierAddItem

Adjustments to add. Maximum of 1000 items in the array.

Yes
BidModifierAddItem structure
CampaignId long The campaign ID. Specified when creating bid adjustments at the campaign level. Either CampaignId or AdGroupId
AdGroupId long ID of the ad group. Specified when creating bid adjustments at the group level.
MobileAdjustment MobileAdjustmentAdd Adjustment on mobile phones. Either MobileAdjustment, or VideoAdjustment, or DemographicsAdjustments, or RetargetingAdjustments, or RegionalAdjustments
DemographicsAdjustments array of DemographicsAdjustmentAdd Adjustments for gender and age. Maximum of 12 items in the array.
RetargetingAdjustments array of RetargetingAdjustmentAdd Adjustments for website users. Maximum of 100 items in the array.
RegionalAdjustments array of RegionalAdjustmentAdd Regional bid adjustments.
VideoAdjustment VideoAdjustmentAdd Bid adjustment for videos.
MobileAdjustmentAdd structure
BidModifier int

Value of the bid coefficient for displaying ads on mobile phones.

Indicated as a percentage from 50 to 1300. The bid is multiplied by the value of BidModifier/100.

Yes
DemographicsAdjustmentAdd structure
Gender GenderEnum

The user's gender: GENDER_MALE or GENDER_FEMALE.

If this parameter is omitted, any gender is assumed (in this case, the Age parameter must be specified).

At least one of the Gender or Age parameters.
Age AgeRangeEnum

The user's age group: one of the values AGE_0_17, AGE_18_24, AGE_25_34, AGE_35_44, AGE_45_54 or AGE_55.

The value AGE_45 has been deprecated. We recommend creating separate adjustments for AGE_45_54 and AGE_55.

If this parameter is omitted, any age is assumed (in this case, the Gender parameter must be specified).

Attention. The audience segments that have bid adjustments set for them must not coincide with each other or overlap. For example, you can't set simultaneous adjustments for the AGE_25_34 and the GENDER_MALE+AGE_25_34 groups.
BidModifier int

The value of the bid coefficient for displaying ads to users of the specified gender and/or age group.

Indicated as a percentage from 0 to 1300. The bid is multiplied by the value of BidModifier/100.

Yes
RetargetingAdjustmentAdd structure
RetargetingConditionId long ID of the retargeting list. See the section Retargeting list (RetargetingList). Yes
BidModifier int

The value of the bid coefficient for displaying ads to users who match the retargeting list.

Indicated as a percentage from 0 to 1300. The bid is multiplied by the value of BidModifier/100.

Yes
RegionalAdjustmentAdd structure
RegionId long

ID of the region from the reference list of regions.

To get the list of regions, use the Dictionaries.get method.

Yes
BidModifier int

Value of the bid coefficient for displaying ads in the specified region.

Indicated as a percentage from 10 to 1300. The bid is multiplied by the value of BidModifier/100.

Yes
VideoAdjustmentAdd structure
BidModifier int

Value of the bid coefficient for displaying ads with video extensions.

Indicated as a percentage from 50 to 1300. The bid is multiplied by the value of BidModifier/100.

Yes

Response

Attention.
  • Adding adjustments for gender and age for the same campaign or ad group is considered a single operation. If one of the coefficients has an error, none of them are created.

  • Adding adjustments for website users for the same campaign or ad group is considered a single operation. If one of the coefficients has an error, none of them are created.

  • Adding regional bid adjustments for the same campaign is considered a single operation. If one of the coefficients has an error, none of them are created.

Response structure in JSON format:

{
  "result": { /* result */
    "AddResults": [{  /* MultiIdsActionResult */
      "Ids": [(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 MultiIdsActionResult Results of adding bid adjustments.
MultiIdsActionResult structure
Ids array of long IDs of the created adjustments. Returned if there aren't any errors. See the section Operations on object arrays. Returned in the same order as the adjustments were listed in the request.
Warnings array of ExceptionNotification

Warnings that occurred during the operation.

Errors array of ExceptionNotification

Errors that occurred during the operation.

Examples

Request example
{  "method": "add",  "params": {    "BidModifiers": [      { // 1. Two bid adjustments, for gender and age        "CampaignId": 10001,        "DemographicsAdjustments": [          {            "Gender": "GENDER_MALE",            "Age": "AGE_25_34",            "BidModifier": 101          },          {            "Age": "AGE_45_54",            "BidModifier": 140          }        ]      },      { // 2. Bid adjustments with overlapping audience segments           "CampaignId": 10002,        "DemographicsAdjustments": [          {            "Gender": "GENDER_MALE",            "Age": "AGE_25_34",            "BidModifier": 120          },          {            "Age": "AGE_25_34",            "BidModifier": 170          }        ]      },       { // 3. Invalid coefficient value        "CampaignId": 10003,        "DemographicsAdjustments": [          {            "Gender": "GENDER_MALE",            "Age": "AGE_25_34",            "BidModifier": 120          },          {            "Gender": "GENDER_FEMALE",            "Age": "AGE_35_44",            "BidModifier": 10000          }        ]      },      { // 4. Bid adjustment for website users on the ad group level        "AdGroupId": 500001,        "RetargetingAdjustments": [          {            "RetargetingConditionId": 2004,            "BidModifier": 201          }        ]      }    ]  }}
Response example
{  "result" : {    "AddResults" : [      { // 1. Created two adjustments for gender and age        "Ids": [ 1003, 1004 ]      },      { // 2. Overlapping segments - no adjustments were created        "Errors": [          {            "Code": 6000,            "Message": "Inconsistent object state",            "Details": "Adjustment criteria overlap in selection"          }        ]      },      { // 3. Invalid value - no adjustments were created        "Errors": [          {            "Code": 5005,            "Message": "Field set incorrectly",            "Details": "Coefficient can't be more than 1300"          }        ]      },      { // 4. Created bid adjustment for website users on the ad group level        "Ids": [ 1005 ]      }    ]  }}