add

Restrictions

You can't add groups to an archived campaign.

Maximum of 1000 groups per method call.

To get the limit on the number of ad groups in a campaign for an advertiser, use the method Clients.get or AgencyClients.get (see the ADGROUPS_TOTAL_PER_CAMPAIGN element in the Restrictions array).

Request

Request structure in JSON format:

{
  "method": "add",
  "params": { /* params */
    "AdGroups": [{  /* AdGroupAddItem */
      "Name": (string), /* required */
      "CampaignId": (long), /* required */
      "RegionIds": [(long), ... ], /* required */
      "NegativeKeywords": {  /* ArrayOfString */
        "Items": [(string), ... ] /* required */
      },
      "TrackingParams": (string),
      "MobileAppAdGroup": {  /* MobileAppAdGroupAdd */
        "StoreUrl": (string), /* required */
        "TargetDeviceType": [( "DEVICE_TYPE_MOBILE" | "DEVICE_TYPE_TABLET" ), ... ], /* required */
        "TargetCarrier": ( "WI_FI_ONLY" | "WI_FI_AND_CELLULAR" ), /* required */
        "TargetOperatingSystemVersion": (string) /* required */
      },
      "DynamicTextAdGroup": {  /* DynamicTextAdGroupAdd */
        "DomainUrl": (string) /* required */
      },
      "CpmBannerKeywordsAdGroup": {  /* ns:CpmBannerKeywordsAdGroupAdd */
      },
      "CpmBannerUserProfileAdGroup": {  /* ns:ns:CpmBannerUserProfileAdGroupAdd */
      }
    }, ... ] /* required */
  }
}
ParameterTypeDescriptionMandatory
Params structure (for JSON) / AddRequest structure (for SOAP)
AdGroupsarray of AdGroupAddItemThe groups to add.Yes
AdGroupAddItem structure
NamestringThe name of the ad group (from 1 to 255 characters).Yes
CampaignIdlongID of the campaign that the group is being added to.Yes
RegionIdsarray of long

Array of IDs of regions where ad impressions are enabled or disabled. The array must contain at least one item.

The ID 0 specifies to display ads in all regions.

A minus sign before a region ID disables impressions in this region. For example, [1,-219] indicates to display for Moscow and the entire Moscow area, except Chernogolovka. Minus regions can't be used if 0 is set. The array must not consist of only minus regions.

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

Array of negative keywords that are shared by all the keywords of an ad group.

Restriction. Negative keywords are not allowed in a group of display ads with targeting criteria based on a user profile.

A keyword should be specified without the minus sign before the first word.

Maximum of 7 words per keyword. The maximum length of each word is 35 characters. The maximum combined length of negative keywords in the array is 4096 characters. Spaces, dashes, and operators are not counted as part of the total length.

Note. Negative keywords that are shared for all a campaign's ad groups should preferably be set in the campaign parameter of the same name.
No
TrackingParamsstring

GET parameters for tracking traffic sources that are added to the link of all ads in the group (maximum of 1024 characters). May contain substitution variables.

For example: from=direct&ad={ad_id}

The parameter can be specified for any type of group, but it is currently only used for groups of dynamic ads. For other types of groups, the specified GET parameters aren't added to links.

No
MobileAppAdGroupMobileAppAdGroupAddParameters of ad groups for mobile app ads.No
DynamicTextAdGroupDynamicTextAdGroupAddParameters of a group of dynamic ads.No
CpmBannerKeywordsAdGroupCpmBannerKeywordsAdGroupAddParameters for a group of display ads with keywords. To create such a group, specify an empty CpmBannerKeywordsAdGroup structure.No
CpmBannerUserProfileAdGroupCpmBannerUserProfileAdGroupAddParameters for a group of display ads with targeting criteria based on a user profile. To create such a group, specify an empty CpmBannerUserProfileAdGroup structure.No
MobileAppAdGroupAdd structure
StoreUrlstring

Link to the app in AppStore or Google Play (maximum of 1024 characters). The link must contain the protocol. Not editable.

See Link to App in Store in the Help for Yandex.Direct.

Restriction. All ad groups in the same campaign must have the same app link.

If groups with different app links were previously created in the campaign, then you are allowed to specify the app link that is shown in your campaign settings in the Yandex.Direct web interface.

Yes
TargetDeviceTypearray of DeviceTypeEnumWhich devices to show ads on:
  • DEVICE_TYPE_MOBILE — smartphones

  • DEVICE_TYPE_TABLET — tablets

Yes
TargetCarrierCarrierEnumWhich types of internet connections to show ads on:
  • WI_FI_ONLY — only Wi-Fi
  • WI_FI_AND_CELLULAR — cellular internet and Wi-Fi
Yes
TargetOperatingSystemVersionstringThe minimum OS version to display the ad on. For example, 2.3.
Note. If the minimum OS version in the app store is higher than the one set in this parameter, ads are displayed only for OS versions equal to or higher than the one in the app store.
Yes
DynamicTextAdGroupAdd structure
DomainUrlstringThe domain name of the site to generate dynamic ads for (a maximum of 100 characters). The protocol can be omitted.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)
      }, ... ] 
    }, ... ]
  }
}
ParameterTypeDescription
Result structure (for JSON) / AddResponse structure (for SOAP)
AddResultsarray of ActionResultResults of adding groups.
ActionResult structure
IdlongID of the created group. Returned if there aren't any errors. See the section Operations on object arrays.
Warningsarray of ExceptionNotification

Warnings that occurred during the operation.

Errorsarray of ExceptionNotification

Errors that occurred during the operation.

Examples

Request example
{
  "method" : "add",
  "params" : {
    "AdGroups" : [
      {
        "RegionIds" : [
          0
        ],
        "CampaignId" : 7273721,
        "NegativeKeywords" : {
          "Items" : [
            "buy"
          ]
        },
        "Name" : "AdGroup #1"
      },
      {
        "RegionIds" : [
          225
        ],
        "CampaignId" : 4193065,
        "NegativeKeywords" : {
          "Items" : [
            "sell"
          ]
        },
        "Name" : "AdGroup #2"
      }
    ]
  }
}
Response example
{
  "result" : {
    "AddResults" : [
      {
        "Id" : 636056397
      },
      {
        "Id" : 636056402
      }
    ]
  }
}
Response with error
{
  "result" : {
    "AddResults" : [
      {
        "Errors" : [
          {
            "Code" : 8800,
            "Details" : "Campaign not found",
            "Message" : "Object not found"
          }
        ]
      },
      {
        "Errors" : [
          {
            "Code" : 5120,
            "Details" : "221 invalid or non-existent region",
            "Message" : "Geo-targeting not set up properly"
          }
        ]
      }
    ]
  }
}