add

Restrictions

The ad type must match the ad group type. See the table in Ad type.

You can't add ads to an archived campaign.

Maximum of 1000 ads per method call.

To get the limit on the number of ads per group for an advertiser, use the method Clients.get or AgencyClients.get (see the ADS_TOTAL_PER_ADGROUP element in the Restrictions array).

Request

Request structure in JSON format:

{
  "method": "add",
  "params": { /* params */
    "Ads": [{  /* AdAddItem */
      "TextAd": {  /* TextAdAdd */
        "Title": (string), /* required */
        "Title2": (string),
        "Text": (string), /* required */
        "Href": (string),
        "Mobile": ( "YES" | "NO" ), /* required */
        "DisplayUrlPath": (string),
        "VCardId": (long),
        "AdImageHash": (string),
        "SitelinkSetId": (long),
        "AdExtensionIds": [(long), ... ],
        "VideoExtension": {  /* VideoExtensionAddItem */
          "CreativeId": (long)
        }  
      },
      "DynamicTextAd": {  /* DynamicTextAdAdd */
        "Text": (string), /* required */
        "VCardId": (long),
        "AdImageHash": (string),
        "SitelinkSetId": (long),
        "AdExtensionIds": [(long), ... ]
      },
      "MobileAppAd": {  /* MobileAppAdAdd */
        "Title": (string), /* required */
        "Text": (string), /* required */
        "TrackingUrl": (string),
        "Features": [{  /* MobileAppAdFeatureItem */
          "Feature": ( "PRICE" | "ICON" | "CUSTOMER_RATING" | "RATINGS" ), /* required */
          "Enabled": ( "YES" | "NO" ) /* required */
        }, ... ],
        "Action": ( "DOWNLOAD" | "GET" | "INSTALL" | "MORE" | "OPEN" | "UPDATE" | "PLAY" | "BUY_AUTODETECT" ), /* required */
        "AgeLabel": ( "AGE_0" | ... | "AGE_18" ),
        "AdImageHash": (string)
      },
      "TextImageAd": {  /* TextImageAdAdd */
        "Href": (string), /* required */
        "AdImageHash": (string) /* required */
      },
      "MobileAppImageAd": {  /* MobileAppImageAdAdd */
        "TrackingUrl": (string),
        "AdImageHash": (string) /* required */
      },
      "TextAdBuilderAd": {  /* TextAdBuilderAdAdd */
        "Creative": { /* AdBuilderAdAddItem */
          "CreativeId": (long) /* required */
        }, /* required */
        "Href": (string) /* required */
      },
      "MobileAppAdBuilderAd": {  /* MobileAppAdBuilderAdAdd */
        "Creative": { /* AdBuilderAdAddItem */
          "CreativeId": (long) /* required */
        }, /* required */
        "TrackingUrl": (string)
      },
      "CpcVideoAdBuilderAd": {  /* CpcVideoAdBuilderAdAdd */
        "Creative": { /* AdBuilderAdAddItem */
          "CreativeId": (long) /* required */
        }, /* required */
        "Href": (string) /* required */
      },
      "CpmBannerAdBuilderAd": {  /* CpmBannerAdBuilderAdAdd */
        "Creative": { /* AdBuilderAdAddItem */
          "CreativeId": (long) /* required */
        }, /* required */      
        "Href": (string), /* required */
        "TrackingPixels": { /* ArrayOfString */
          "Items": [(string), ... ] /* required */
        }
      },
      "AdGroupId": (long) /* required */ 
    }, ... ] /* required */
  } 
}
ParameterTypeDescriptionRequired
Params structure (for JSON) / AddRequest structure (for SOAP)
Adsarray of AdAddItem

Ads to add.

Yes
AdAddItem structure
AdGroupIdlongID of the group that the ad is being created in.Yes
TextAdTextAdAddParameters of a text and image ad. See Ad type.Either TextAd, or MobileAppAd, or DynamicTextAd, or TextImageAd, or MobileAppImageAd, or TextAdBuilderAd, or MobileAppAdBuilderAd, or CpcVideoAdBuilderAd, or CpmBannerAdBuilderAd
MobileAppAdMobileAppAdAddParameters of a mobile app ad.
DynamicTextAdDynamicTextAdAddParameters of a dynamic ad.
TextImageAdTextImageAdAddParameters of an image ad to create from an image (when adding it to a group of text and image ads).
MobileAppImageAdMobileAppImageAdAddParameters of an image ad to create from an image (when adding it to a group of mobile app ads).
TextAdBuilderAdTextAdBuilderAdAddParameters of an image ad to create from a creative (when adding it to a group of text and image ads).
MobileAppAdBuilderAdMobileAppAdBuilderAdAddParameters of an image ad to create from a creative (when adding it to a group of mobile app ads).
CpcVideoAdBuilderAdCpcVideoAdBuilderAdAddVideo ad parameters.
CpmBannerAdBuilderAdCpmBannerAdBuilderAdAddDisplay ad parameters.
TextAdAdd structure
Titlestring

Title 1.

Maximum of 35 characters not counting "narrow" characters, plus up to 15 "narrow" characters. Maximum of 22 characters per word. If using a template, the # character isn't counted in the length.

Yes
Title2string

Title 2.

Maximum of 30 characters not counting "narrow" characters, plus up to 15 "narrow" characters. Maximum of 22 characters per word. If using a template, the # character isn't counted in the length.

No
Textstring

Ad text.

Maximum of 81 characters not counting "narrow" characters, plus up to 15 "narrow" characters. Maximum of 23 characters per word. If using a template, the # character isn't counted in the length.

Yes
MobileYesNoEnumIndicates whether this is a mobile ad: YES or NO. See Mobile ads in the Help for Yandex.Direct.Yes
Hrefstring

Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # character isn't counted in the length.

It must include the protocol and domain name. May contain substitution variables.

Href or VCardId (or both)
VCardIdlongID of the vCard. The vCard must belong to the same campaign as the ad.
AdImageHashstring

Hash of the image.

For text and image ads, only images with the REGULAR or WIDE type are acceptable. See Image type.
No
SitelinkSetIdlongID of a set of sitelinks. Allowed only with the Href parameter.No
DisplayUrlPathstring

Display link. Allowed only with the Href parameter. Maximum of 20 characters. If using a template, the # character isn't counted in the length.

It may contain letters, numbers, and the symbols -, №, /, %, #. Spaces, underscores (_), and the double characters -- and // are not allowed.

See Display link in the Help for Yandex.Direct.

No
AdExtensionIdsarray of longIDs of extensions. Maximum of 50 items in the array.No
VideoExtensionVideoExtensionAddItem

Video extension.

See the section Video extensions in the Help for Yandex.Direct.

No
VideoExtensionAddItem structure
CreativeIdlong

ID of the creative.

To get the ID of a creative, use the Creatives.get method.

Yes
MobileAppAdAdd structure
Titlestring

Header.

Maximum of 33 characters, counting “narrow” characters. Maximum of 22 characters per word. If using a template, the # character isn't counted in the length.

Yes
Textstring

Ad text.

Maximum of 75 characters, counting “narrow” characters. Maximum of 23 characters per word. If using a template, the # character isn't counted in the length.

Yes
TrackingUrlstringTracking link for tracking app installations. Maximum of 1024 characters. It must include the protocol and domain name.No
Featuresarray of MobileAppAdFeatureItemAdd-ons that need to be automatically downloaded from the app store and displayed in the ad.No
AgeLabelMobAppAgeLabelEnumAge restriction. The default value is AGE_18.No
ActionMobileAppAdActionEnum

The button label:

  • DOWNLOAD — “Download”

  • GET — “Get”

  • INSTALL — “Install”

  • MORE — “More”

  • OPEN — “Open”

  • UPDATE — “Update”

  • PLAY — “Play”

  • BUY_AUTODETECT — The label depends on the application price: “Buy” if the price is something other than zero, or “Free” if the price is set to zero.

Yes
AdImageHashstring

Hash of the image.

For mobile app ads, only images with the WIDE type are acceptable. See Image type.

No
MobileAppAdFeatureItem structure
FeatureMobileAppFeatureEnum

Type of extension:

  • PRICE — price
  • ICON — icon
  • CUSTOMER_RATING — rating
  • RATINGS — number of ratings (shown only if the rating is displayed)

If the add-on type is omitted from the Features array, the add-on is not shown.

Yes
EnabledYesNoEnum

Whether to display an add-on in the ad.

Note.
  • If the add-on couldn't be downloaded from the app store, the YES value is available, but this add-on is not shown when displaying the ad.
  • The number of ratings is only shown together with the average rating: if NO is set for the CUSTOMER_RATING type, but YES is set for RATINGS, the number of ratings is not displayed.
Yes
DynamicTextAdAdd structure
Textstring

Ad text.

Maximum of 81 characters not counting "narrow" characters, plus up to 15 "narrow" characters. Maximum of 23 characters per word. If using a template, the # character isn't counted in the length.

Yes
VCardIdlongID of the vCard. The vCard must belong to the same campaign as the ad.No
AdImageHashstring

Hash of the image.

For dynamic ads, only images with the REGULAR or WIDE type are acceptable. See Image type.

No
SitelinkSetIdlongID of a set of sitelinks.No
AdExtensionIdsarray of longIDs of extensions. Maximum of 50 items in the array.No
TextImageAdAdd structure
Hrefstring

Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # character isn't counted in the length.

It must include the protocol and domain name. May contain substitution variables.

Yes
AdImageHashstring

Hash of the image.

For image ads, only images with the FIXED_IMAGE type are acceptable. See Image type.

Yes
MobileAppImageAdAdd structure
TrackingUrlstringTracking link for tracking app installations. Maximum of 1024 characters. It must include the protocol and domain name.No
AdImageHashstring

Hash of the image.

For image ads, only images with the FIXED_IMAGE type are acceptable. See Image type.

Yes
TextAdBuilderAdAdd structure
CreativeAdBuilderAdAddItem

A creative that was created in the Ad Builder.

See the section Creative Ad Builder for image ads in the Help for Yandex.Direct.

Yes
Hrefstring

Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # character isn't counted in the length.

It must include the protocol and domain name. May contain substitution variables.

Yes
MobileAppAdBuilderAdAdd structure
CreativeAdBuilderAdAddItem

A creative that was created in the Ad Builder.

See the section Creative Ad Builder for image ads in the Help for Yandex.Direct.

Yes
TrackingUrlstringTracking link for tracking app installations. Maximum of 1024 characters. It must include the protocol and domain name.No
CpmBannerAdBuilderAdAdd structure
CreativeAdBuilderAdAddItem

A creative that was uploaded in the web interface or created in the Ad Builder.

See Create a display campaign in the Help for Yandex.Direct.

Yes
Hrefstring

Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # character isn't counted in the length.

It must include the protocol and domain name. May contain substitution variables.

Yes
TrackingPixelsArrayOfStringCan contain a maximum of two strings:
  • A Yandex.Audience pixel (see Pixel in the Help for Yandex.Audience).
  • An ADFOX tracking tag. The tag must have the %random% or %aw_random% macro.

The maximum length of each string is 1024 characters.

No
CpcVideoAdBuilderAdAdd structure
CreativeAdBuilderAdAddItem

A creative that was created in the Ad Builder.

See the section Creative Ad Builder for video extensions in the Help for Yandex.Direct.

Yes
Hrefstring

Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # character isn't counted in the length.

It must include the protocol and domain name. May contain substitution variables.

Yes
AdBuilderAdAddItem structure
CreativeIdlong

ID of the creative.

To get the ID of a creative, use the Creatives.get method.

Yes
Note. “Narrow” characters are: !,.;:"

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 ads.
ActionResult structure
IdlongID of the ad that was created. 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.