add

Creates ads.

Learn more

Restrictions

To manage product ads, use this URL: https://api.direct.yandex.com/v501/.

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 check the limit on the number of ads per group for a user, call the Clients.get or AgencyClients.get method (look for the ADS_TOTAL_PER_ADGROUP element in the Restrictions array).

Request

Request structure in JSON format:

{
  "method": "add",
  "params": { /* params */
    "Ads": [{  /* AdAddItem */
      "AdGroupId": (long), /* required */
      "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)
        },
        "PriceExtension": {  /* PriceExtensionAddItem */
          "Price": (long), /* required */
          "OldPrice": (long),
          "PriceQualifier": ( "FROM" | "UP_TO" | "NONE" ), /* required */
          "PriceCurrency": ( "RUB" | "BYN" | "CHF" | "EUR" | "KZT" | "TRY" | "UAH" | "USD" | "UZS" ) /* required */
        },
        "TurboPageId": (long),
        "BusinessId": (long),
        "PreferVCardOverBusiness": ( "YES" | "NO" ),
        "ErirAdDescription" : (string)
      },
      "TextImageAd": {  /* TextImageAdAdd */
        "AdImageHash": (string), /* required */
        "ErirAdDescription" : (string),
        "Href": (string),
        "TurboPageId": (long)
      },
      "TextAdBuilderAd": {  /* TextAdBuilderAdAdd */
        "Creative": { /* AdBuilderAdAddItem */
          "CreativeId": (long) /* required */
        }, /* required */
        "ErirAdDescription" : (string),
        "Href": (string),
        "TurboPageId": (long)
      },
      "CpmBannerAdBuilderAd": {  /* CpmBannerAdBuilderAdAdd */
        "Creative": { /* AdBuilderAdAddItem */
          "CreativeId": (long) /* required */
        }, /* required */
        "ErirAdDescription" : (string),
        "Href": (string),
        "TrackingPixels": { /* ArrayOfString */
          "Items": [(string), ... ] /* required */
        },
        "TurboPageId": (long)
      },
      "CpmVideoAdBuilderAd": {  /* CpmVideoAdBuilderAdAdd */
        "Creative": { /* AdBuilderAdAddItem */
          "CreativeId": (long) /* required */
        }, /* required */
        "ErirAdDescription" : (string),
        "Href": (string),
        "TrackingPixels": { /* ArrayOfString */
          "Items": [(string), ... ] /* required */
        },
        "TurboPageId": (long)
      },
      "ShoppingAd" : {
        "SitelinkSetId" : (long),
        "AdExtensionIds" : [ (long) ],
        "BusinessId" : (long),
        "FeedId" : (long) /* required */,
        "FeedFilterConditions" : [ {
          "Operand" : (string) /* required */,
          "Operator" : ("CONTAINS_ANY"|"EQUALS_ANY"|"EXISTS"|"GREATER_THAN"|"IN_RANGE"|"LESS_THAN"|"NOT_CONTAINS_ALL") /* required */,
          "Arguments" : [ (string) ] /* required */
        }, ... ],
        "TitleSources" : [ (string) ],
        "TextSources" : [ (string) ],
        "DefaultTexts" : [ (string) ] /* required */
      },
      "ListingAd" : {
        "SitelinkSetId" : (long),
        "AdExtensionIds" : [ (long) ],
        "BusinessId" : (long),
        "FeedId" : (long) /* required */,
        "FeedFilterConditions" : [ {
          "Operand" : (string) /* required */,
          "Operator" : ("CONTAINS_ANY"|"EQUALS_ANY"|"EXISTS"|"GREATER_THAN"|"IN_RANGE"|"LESS_THAN"|"NOT_CONTAINS_ALL") /* required */,
          "Arguments" : [ (string) ] /* required */
        }, ... ],
        "TitleSources" : [ (string) ],
        "TextSources" : [ (string) ],
        "DefaultTexts" : [ (string) ] /* required */
      }
    }, ... ] /* required */
  }
}

params structure (for JSON) / AddRequest structure (for SOAP)
Parameter	Type	Description	Required
`Ads`	array of AdAddItem	Ads to add.	Yes
AdAddItem structure
`AdGroupId`	long	ID of the group that the ad is being created in.	Yes
`TextAd`	TextAdAdd	Parameters of a Text & Image ad. See Ad type.	Use either `TextAd` or `MobileAppAd` or `DynamicTextAd` or `TextImageAd` or `MobileAppImageAd` or `TextAdBuilderAd` or `MobileAppAdBuilderAd` or `MobileAppCpcVideoAdBuilderAd` or `CpcVideoAdBuilderAd` or `CpmBannerAdBuilderAd` or `CpmVideoAdBuilderAd` or `SmartAdBuilderAd`.
`TextImageAd`	TextImageAdAdd	Parameters of an image ad to create from an image (when adding it to a group of Text & Image ads).
`TextAdBuilderAd`	TextAdBuilderAdAdd	Parameters of an image ad to create from a creative (when adding it to a group of Text & Image ads).
`CpmBannerAdBuilderAd`	CpmBannerAdBuilderAdAdd	Display ad parameters.
`CpmVideoAdBuilderAd`	CpmVideoAdBuilderAdAdd	Parameters of a display video ad in a display campaign.
`ShoppingAd`	ShoppingAdAdd	Product ad parameters.
`ListingAd`	ListingAdAdd	Parameters of ads for catalog pages.
TextAdAdd structure
`Title`	string	Title 1. Maximum of 56 characters, counting "narrow" characters. Maximum of 22 characters per word. When using a template, the # character doesn't count towards the length.	Yes
`Title2`	string	Title 2. A maximum of 30 characters not counting “narrow” characters, plus up to 15 “narrow” characters. Maximum of 22 characters per word. When using a template, the # character doesn't count towards the length.	No
`Text`	string	Ad text. Maximum of 81 characters not counting "narrow" characters, plus up to 15 "narrow" characters. Maximum of 23 characters per word. When using a template, the # character doesn't count towards the length.	Yes
`Mobile`	YesNoEnum	Indicates whether this is a mobile ad: YES or NO. See Mobile ads in Yandex Direct Help. Alert This parameter is deprecated. Regardless of the value passed, it will default to `NO`.	Yes
`Href`	string	The page URL where the ad will direct users. Maximum of 1024 characters. When using a template, the # character doesn't count towards the length. It must include the protocol and domain name. May contain substitution variables.	At least one of the parameters `Href`, `TurboPageId`, `VCardId` or `BusinessId` (or all may be present)
`TurboPageId`	long	ID of the Turbo page. Alert This parameter is deprecated. The passed value won't be saved.
`VCardId`	long	ID of the vCard. The vCard must belong to the same campaign as the ad. Alert This parameter is deprecated. The passed value won't be saved.
`BusinessId`	long	ID of the business profile on Yandex. To get data from business profiles, use the Businesses.get method. A business profile can be linked to an ad only if the YES value is returned for the `IsPublished` parameter. Note The business profile is available at `https://yandex.ru/profile/<profile_id>`
`PreferVCardOverBusiness`	YesNoEnum	Indicates which data source takes priority when displaying an ad: YES — vCard, NO — business profile. Alert This parameter is deprecated. Regardless of the value passed, it will default to `NO`.	No
`ErirAdDescription`	string	Description of a promoted object.	No
`AdImageHash`	string	Hash of the image. For Text & Image ads, only images of the REGULAR or WIDE type are acceptable. See Type of image.	No
`SitelinkSetId`	long	ID of a set of sitelinks. Allowed only with the `Href` or `TurboPageId` parameter.	No
`DisplayUrlPath`	string	Display link. Allowed only with the `Href` parameter. Maximum of 20 characters. When using a template, the # character doesn't count towards the length. It may contain letters, numbers, and the symbols -, №, /, %, #. Spaces, underscores (_), and double characters -- and // are not allowed. See Display link in the Yandex Direct Help.	No
`AdExtensionIds`	array of long	IDs of extensions. Maximum of 50 items in the array.	No
`VideoExtension`	VideoExtensionAddItem	Video extension. If this parameter is omitted and ENABLE_VIDEO_EXTENSION_BY_DEFAULT is set to YES, a video extension is generated automatically. See Video extensions in the Yandex Direct Help.	No
`PriceExtension`	PriceExtensionAddItem	Price in the ad.	No
VideoExtensionAddItem structure
`CreativeId`	long	ID of the creative. To get the ID of a creative, use the Creatives.get method.	Yes
PriceExtensionAddItem structure
`Price`	long	The price of a product or service multiplied by 1,000,000. An integer that is a multiple of 10,000 (the price with two digits after the decimal point). Maximum value: 10,000,000,000,000,000.	Yes
`OldPrice`	long	The previous price of a product or service multiplied by 1,000,000. An integer that is a multiple of 10,000. The old price must be higher than the current price.	No
`PriceQualifier`	PriceQualifierEnum	Text explanation of the price: FROM — "From". UP_TO — "To". NONE — No explanation.	Yes
`PriceCurrency`	PriceCurrencyEnum	The currency that the price is shown in.	Yes
MobileAppAdFeatureItem structure
`Feature`	MobileAppFeatureEnum	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 won't be displayed.	Yes
`Enabled`	YesNoEnum	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
TextImageAdAdd structure
`AdImageHash`	string	Hash of the image. For image ads, only images of the FIXED_IMAGE type are acceptable. See Type of image.	Yes
`ErirAdDescription`	string	Description of a promoted object.	No
`Href`	string	The page URL where the ad will direct users. Maximum of 1024 characters. When using a template, the # character doesn't count towards the length. It must include the protocol and domain name. May contain substitution variables.	One or both of the `Href` and `TurboPageId` parameters
`TurboPageId`	long	ID of the Turbo page.	One or both of the `Href` and `TurboPageId` parameters
TextAdBuilderAdAdd structure
`Creative`	AdBuilderAdAddItem	A creative that was designed in the Ad Builder. See Creative Ad Builder for image ads in the Yandex Direct Help.	Yes
`ErirAdDescription`	string	Description of a promoted object.	No
`Href`	string	The page URL where the ad will direct users. Maximum of 1024 characters. When using a template, the # character doesn't count towards the length. It must include the protocol and domain name. May contain substitution variables.	One or both of the `Href` and `TurboPageId` parameters
`TurboPageId`	long	ID of the Turbo page.	One or both of the `Href` and `TurboPageId` parameters
CpmBannerAdBuilderAdAdd structure
`Creative`	AdBuilderAdAddItem	A creative that was uploaded in the web interface or created in the Ad Builder. See Creating a display campaign in the Yandex Direct Help.	Yes
`ErirAdDescription`	string	Description of a promoted object.	No
`Href`	string	The page URL where the ad will direct users. Maximum of 1024 characters. When using a template, the # character doesn't count towards the length. It must include the protocol and domain name. May contain substitution variables.	One or both of the `Href` and `TurboPageId` parameters
`TurboPageId`	long	ID of the Turbo page.	One or both of the `Href` and `TurboPageId` parameters
`TrackingPixels`	ArrayOfString	Can contain a maximum of two strings: A Yandex Audience pixel (see Pixel in the Yandex Audience Help). An ADFOX tracking tag. The tag must have the `%random%` or `%aw_random%` macro. The maximum length of each string is 1024 characters.	No
CpmVideoAdBuilderAdAdd structure
`Creative`	AdBuilderAdAddItem	A creative that was designed in the Ad Builder. See Video advertising / How to launch in Yandex Direct Help.	Yes
`ErirAdDescription`	string	Description of a promoted object.	No
`Href`	string	The page URL where the ad will direct users. Maximum of 1024 characters. When using a template, the # character doesn't count towards the length. It must include the protocol and domain name. May contain substitution variables.	One or both of the `Href` and `TurboPageId` parameters.
`TurboPageId`	long	ID of the Turbo page.	One or both of the `Href` and `TurboPageId` parameters.
`TrackingPixels`	ArrayOfString	An ADFOX tracking tag. The tag must have the `%random%` or `%aw_random%` macro. Maximum of 1024 characters.	No
AdBuilderAdAddItem structure
`CreativeId`	long	ID of the creative. To get the ID of a creative, use the Creatives.get method.	Yes
ShoppingAdAdd structure
`SitelinkSetId`	long	ID of a set of sitelinks.	No
`AdExtensionIds`	array of long	IDs of extensions. Maximum of 50 items in the array.	No
`BusinessId`	long	ID of the business profile on Yandex. To get data from business profiles, use the Businesses.get method. A business profile can be linked to an ad only if the YES value is returned for the `IsPublished` parameter. Note The business profile is available at `https://yandex.ru/profile/<profile_id>`	No
`FeedId`	long	ID of the feed to generate ads from.	Yes
`FeedFilterConditions`	FeedFilterConditionsItem	Rules for selecting product offers. No more than 30 filters in the array. The total length of the selection rules is a maximum of 65 KB (in JSON). A product offer is selected for ad generation if it meets all the selection rules at the same time. If this parameter is omitted, all product offers from the feed are used for ad generation.	No
`TitleSources`	array of string	Names of feed fields used to generate ad titles. You can retrieve the acceptable field names through the `TitleAndTextSources` field of the feeds.get method.	No
`TextSources`	array of string	Names of feed fields used to generate ad texts. You can retrieve the acceptable field names through the `TitleAndTextSources` field of the feeds.get method.	No
`DefaultTexts`	array of string	Default texts. You can specify only one value.	Yes
ListingAdAdd structure
`SitelinkSetId`	long	ID of a set of sitelinks.	No
`AdExtensionIds`	array of long	IDs of extensions. Maximum of 50 items in the array.	No
`BusinessId`	long	ID of the business profile on Yandex. To get data from business profiles, use the Businesses.get method. A business profile can be linked to an ad only if the YES value is returned for the `IsPublished` parameter. Note The business profile is available at `https://yandex.ru/profile/<profile_id>`	No
`FeedId`	long	ID of the feed to generate ads from.	Yes
`FeedFilterConditions`	FeedFilterConditionsItem	Rules for selecting product offers. No more than 30 filters in the array. The total length of the selection rules is a maximum of 65 KB (in JSON). A product offer is selected for ad generation if it meets all the selection rules at the same time. If this parameter is omitted, all product offers from the feed are used for ad generation.	No
`TitleSources`	array of string	Names of feed fields used to generate ad titles. You can retrieve the acceptable field names through the `TitleAndTextSources` field of the feeds.get method.	No
`TextSources`	array of string	Names of feed fields used to generate ad texts. You can retrieve the acceptable field names through the `TitleAndTextSources` field of the feeds.get method.	No
`DefaultTexts`	array of string	Default texts. You can specify only one value.	Yes
FeedFilterConditionsItem structure
`Operand`	string	Feed parameter.	Yes
`Operator`	StringConditionOperatorEnum	Comparison operator. For information on the compatibility of feed fields and operators, as well as restrictions on values, see Rules for selecting product ads.	Yes
`Arguments`	array of string	An array of strings to compare the operand to.	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)
      }, ... ]
    }, ... ]
  }
}

Parameter	Type	Description
result structure (for JSON) / AddResponse structure (for SOAP)
`AddResults`	array of ActionResult	Results of adding ads.
ActionResult structure
`Id`	long	ID of the ad that was created. Returned if there aren't any 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.

Was the article helpful?

Ads: operations with ads