Documentation

add

Creates bid adjustments.

Restrictions

Maximum of 1 mobile adjustment per campaign or ad group.

Maximum of 10 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 mobile app advertising campaigns and ad groups.

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

Request

Request structure in JSON format:

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

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

Required

Yes

]no-highlight]
": [{ /* BidModifierAddItem */ "MobileAdjustment
[no-highlight[

Adjustment on mobile phones.

Required

Either MobileAdjustment, DemographicsAdjustments, RetargetingAdjustments, or RegionalAdjustments

]no-highlight]
": { /* MobileAdjustmentAdd */ "BidModifier
[no-highlight[

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.

Required

Yes

]no-highlight]
": (int) /* required */ }, "DemographicsAdjustments
[no-highlight[

Adjustments for gender and age. Maximum of 10 items in the array.

Required

Either MobileAdjustment, DemographicsAdjustments, RetargetingAdjustments, or RegionalAdjustments

]no-highlight]
": [{ /* DemographicsAdjustmentAdd */ "Gender
[no-highlight[

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).

Required

At least one of the Gender or Age parameters.

]no-highlight]
": ( "GENDER_MALE" | "GENDER_FEMALE" ), "Age
[no-highlight[

The user‘s age group: one of the values AGE_0_17, AGE_18_24, AGE_25_34, AGE_35_44 or AGE_45.

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.

Required

At least one of the Gender or Age parameters.

]no-highlight]
": ( "AGE_0_17" | "AGE_18_24" | "AGE_25_34" | "AGE_35_44" | "AGE_45" ), "BidModifier
[no-highlight[

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.

Required

Yes

]no-highlight]
": (int) /* required */ }, ... ], "RetargetingAdjustments
[no-highlight[

Adjustments for website users. Maximum of 100 items in the array.

Required

Either MobileAdjustment, DemographicsAdjustments, RetargetingAdjustments, or RegionalAdjustments

]no-highlight]
": [{ /* RetargetingAdjustmentAdd */ "RetargetingConditionId
[no-highlight[

ID of the retargeting list. See the section Retargeting list (RetargetingList).

Required

Yes

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

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.

Required

Yes

]no-highlight]
": (int) /* required */ }, ... ], "RegionalAdjustments
[no-highlight[

Regional bid adjustments.

Required

Either MobileAdjustment, DemographicsAdjustments, RetargetingAdjustments, or RegionalAdjustments

]no-highlight]
": [{ /* RegionalAdjustmentAdd */ "RegionId
[no-highlight[

ID of the region from the reference list of regions.

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

Required

Yes

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

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.

Required

Yes

]no-highlight]
": (int) /* required */ },... "CampaignId
[no-highlight[

The campaign ID. Specified when creating bid adjustments at the campaign level.

Required

Either CampaignId or AdGroupId

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

ID of the ad group. Specified when creating bid adjustments at the group level.

Required

Either CampaignId or AdGroupId

]no-highlight]
": (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 longThe campaign ID. Specified when creating bid adjustments at the campaign level.Either CampaignId or AdGroupId
AdGroupId longID of the ad group. Specified when creating bid adjustments at the group level.
MobileAdjustment MobileAdjustmentAdd Adjustment on mobile phones.Either MobileAdjustment, DemographicsAdjustments, RetargetingAdjustments, or RegionalAdjustments
DemographicsAdjustments array of DemographicsAdjustmentAddAdjustments for gender and age. Maximum of 10 items in the array.
RetargetingAdjustments array of RetargetingAdjustmentAddAdjustments for website users. Maximum of 100 items in the array.
RegionalAdjustments array of RegionalAdjustmentAddRegional bid adjustments.
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 or AGE_45.

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 longID 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
[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.
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

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": { 
    "AddResults
[no-highlight[

Results of adding bid adjustments.

]no-highlight]
": [{ /* MultiIdsActionResult */ "Ids
[no-highlight[

IDs of the created adjustments. Returned if there is no error. See the section Operations on object arrays. Returned in the same order as the adjustments were listed in the request.

]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 MultiIdsActionResultResults of adding bid adjustments.
MultiIdsActionResult structure
Ids array of longIDs of the created adjustments. Returned if there is no error. 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",
            "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 ]
      }
    ]
  }
}