update
Changes ad parameters.
Restrictions
To manage product ads, use the URL: https://api.direct.yandex.com/v501/
.
Maximum of 1000 ads per method call.
You can't edit ads with the ARCHIVED status. See Ad status and state.
Request
Request structure in JSON format:
{
"method": "update",
"params": { /* params */
"Ads": [{ /* AdUpdateItem */
"Id": (long), /* required */
"TextAd": { /* TextAdUpdate */
"Title": (string),
"Title2": (string), /* nillable */
"Text": (string),
"Href": (string), /* nillable */
"AgeLabel": ( "AGE_0" | ... | "MONTHS_12" ),
"DisplayUrlPath": (string), /* nillable */
"VCardId": (long), /* nillable */
"AdImageHash": (string), /* nillable */
"SitelinkSetId": (long), /* nillable */
"CalloutSetting": { /* AdExtensionSetting */
"AdExtensions": [{ /* AdExtensionSettingItem */
"AdExtensionId": (long), /* required */
"Operation": ( "ADD" | "REMOVE" | "SET" ) /* required */
}, ... ] /* required */
}, /* nillable */
"VideoExtension": { /* VideoExtensionUpdateItem */
"CreativeId": (long) /* nillable */
},
"PriceExtension": { /* PriceExtensionUpdateItem */
"Price": (long),
"OldPrice": (long), /* nillable */
"PriceQualifier": ( "FROM" | "UP_TO" | "NONE" ),
"PriceCurrency": ( "RUB" | "BYN" | "CHF" | "EUR" | "KZT" | "TRY" | "UAH" | "USD" | "UZS" )
}, /* nillable */
"TurboPageId": (long), /* nillable */
"BusinessId": (long), /* nillable */
"PreferVCardOverBusiness": ( "YES" | "NO" ),
"ErirAdDescription" : (string) /* nillable */
},
"DynamicTextAd": { /* DynamicTextAdUpdate */
"VCardId": (long), /* nillable */
"AdImageHash": (string), /* nillable */
"SitelinkSetId": (long), /* nillable */
"CalloutSetting": { /* AdExtensionSetting */
"AdExtensions": [{ /* AdExtensionSettingItem */
"AdExtensionId": (long), /* required */
"Operation": ( "ADD" | "REMOVE" | "SET" ) /* required */
}, ... ] /* required */
}, /* nillable */
"Text": (string)
},
"MobileAppAd": { /* MobileAppAdUpdate */
"Title": (string),
"Text": (string),
"TrackingUrl": (string), /* nillable */
"Action": ( "DOWNLOAD" | "GET" | "INSTALL" | "MORE" | "OPEN" | "UPDATE" | "PLAY" | "BUY_AUTODETECT" ),
"AdImageHash": (string), /* nillable */
"Features": [{ /* MobileAppAdFeatureItem */
"Feature": ( "PRICE" | "ICON" | "CUSTOMER_RATING" | "RATINGS" ), /* required */
"Enabled": ( "YES" | "NO" ) /* required */
}, ... ],
"AgeLabel": ( "AGE_0" | ... | "AGE_18" ),
"VideoExtension": { /* VideoExtensionUpdateItem */
"CreativeId": (long) /* nillable */
},
"ErirAdDescription" : (string) /* nillable */
},
"TextImageAd": { /* TextImageAdUpdate */
"AdImageHash": (string),
"Href": (string), /* nillable */
"TurboPageId": (long), /* nillable */
"ErirAdDescription" : (string) /* nillable */
},
"MobileAppImageAd": { /* MobileAppImageAdUpdate */
"AdImageHash": (string),
"TrackingUrl": (string), /* nillable */
"ErirAdDescription" : (string) /* nillable */
},
"MobileAppCpcVideoAdBuilderAd" : { /* MobileAppCpcVideoAdBuilderAdUpdate */
"Creative" : { /* AdBuilderAdUpdateItem */
"CreativeId" : (long) /* required */
},
"TrackingUrl" : (string), /* nillable */
"ErirAdDescription" : (string) /* nillable */
},
"TextAdBuilderAd": { /* TextAdBuilderAdUpdate */
"Creative": { /* AdBuilderAdUpdateItem */
"CreativeId": (long) /* required */
},
"Href": (string), /* nillable */
"TurboPageId": (long), /* nillable */
"ErirAdDescription" : (string) /* nillable */
},
"MobileAppAdBuilderAd": { /* MobileAppAdBuilderAdUpdate */
"Creative": { /* AdBuilderAdUpdateItem */
"CreativeId": (long) /* required */
},
"TrackingUrl": (string), /* nillable */
"ErirAdDescription" : (string) /* nillable */
},
"CpcVideoAdBuilderAd": { /* CpcVideoAdBuilderAdUpdate */
"Creative": { /* AdBuilderAdUpdateItem */
"CreativeId": (long) /* required */
},
"Href": (string), /* nillable */
"TurboPageId": (long), /* nillable */
"ErirAdDescription" : (string) /* nillable */
},
"CpmBannerAdBuilderAd": { /* CpmBannerAdBuilderAdUpdate */
"Creative": { /* AdBuilderAdUpdateItem */
"CreativeId": (long) /* required */
},
"Href": (string), /* nillable */
"TrackingPixels": { /* ArrayOfString */
"Items": [(string), ... ] /* required */
}, /* nillable */
"TurboPageId": (long), /* nillable */
"ErirAdDescription" : (string) /* nillable */
},
"CpmVideoAdBuilderAd": { /* CpmVideoAdBuilderAdUpdate */
"Creative": { /* AdBuilderAdUpdateItem */
"CreativeId": (long) /* required */
},
"Href": (string), /* nillable */
"TrackingPixels": { /* ArrayOfString */
"Items": [(string), ... ] /* required */
}, /* nillable */
"TurboPageId": (long),
"ErirAdDescription" : (string) /* nillable */
},
"SmartAdBuilderAd": { /* SmartAdBuilderAdUpdate */
"Creative": { /* AdBuilderAdUpdateItem */
"CreativeId": (long) /* required */
},
"ErirAdDescription" : (string)
},
"ShoppingAd" : {
"SitelinkSetId" : (long) /* nillable */,
"CalloutSetting" : { /* nillable */
"AdExtensions" : [{ /* required */
"AdExtensionId" : (long) /* required */,
"Operation" : ("ADD"|"REMOVE"|"SET") /* required */
}, ... ]
},
"BusinessId" : (long) /* nillable */,
"FeedFilterConditions" : { /* nillable */
"Items" : [{ /* required */
"Operand" : (string) /* required */,
"Operator" : ("CONTAINS_ANY"|"EQUALS_ANY"|"EXISTS"|"GREATER_THAN"|"IN_RANGE"|"LESS_THAN"|"NOT_CONTAINS_ALL") /* required */,
"Arguments" : [ (string) ] /* required */
}, ... ]
},
"TitleSources" : { /* nillable */
"Items" : [ (string) ] /* required */
},
"TextSources" : { /* nillable */
"Items" : [ (string) ] /* required */
},
"DefaultTexts" : [ (string) ]
},
"ListingAd" : {
"SitelinkSetId" : (long) /* nillable */,
"CalloutSetting" : { /* nillable */
"AdExtensions" : [{ /* required */
"AdExtensionId" : (long) /* required */,
"Operation" : ("ADD"|"REMOVE"|"SET") /* required */
}, ... ]
},
"BusinessId" : (long) /* nillable */,
"FeedFilterConditions" : { /* nillable */
"Items" : [{ /* required */
"Operand" : (string) /* required */,
"Operator" : ("CONTAINS_ANY"|"EQUALS_ANY"|"EXISTS"|"GREATER_THAN"|"IN_RANGE"|"LESS_THAN"|"NOT_CONTAINS_ALL") /* required */,
"Arguments" : [ (string) ] /* required */
}, ... ]
},
"TitleSources" : { /* nillable */
"Items" : [ (string) ] /* required */
},
"TextSources" : { /* nillable */
"Items" : [ (string) ] /* required */
},
"DefaultTexts" : [ (string) ]
}
}, ... ] /* required */
}
}
Parameter | Type | Description | Required |
Params structure (for JSON) / UpdateRequest structure (for SOAP) | |||
---|---|---|---|
Ads | array of AdUpdateItem | Ads to change parameters for. | Yes |
AdUpdateItem structure | |||
Id | long | The ID of the ad to change parameters for. | Yes |
TextAd | TextAdUpdate | Parameters of a text and image ad. See Ad typewhen calling finance methods. | Either TextAd, or MobileAppAd, or DynamicTextAd, or TextImageAd, or MobileAppImageAd, or MobileAppCpcVideoAdBuilderAd, or TextAdBuilderAd, or MobileAppAdBuilderAd, or CpcVideoAdBuilderAd, or CpmBannerAdBuilderAd, or CpmVideoAdBuilderAd, or SmartAdBuilderAd |
DynamicTextAd | DynamicTextAdUpdate | Parameters of a dynamic ad. | |
MobileAppAd | MobileAppAdUpdate | Parameters of a mobile app ad. | |
TextImageAd | TextImageAdUpdate | Parameters of an image ad that was created from an image (in a group of text and image ads). | |
MobileAppImageAd | MobileAppImageAdUpdate | Parameters of an image ad that was created from an image (in a group of mobile app ads). | |
MobileAppCpcVideoAdBuilderAd | MobileAppCpcVideoAdBuilderAdUpdate | Parameters of a video ad that was created from an image (in a group of ads for mobile apps). | |
TextAdBuilderAd | TextAdBuilderAdUpdate | Parameters of an image ad that was created from a creative (in a group of text and image ads). | |
MobileAppAdBuilderAd | MobileAppAdBuilderAdUpdate | Parameters of an image ad that was created from a creative (in a group of mobile app ads). | |
CpcVideoAdBuilderAd | CpcVideoAdBuilderAdUpdate | Video ad parameters (in “Text & Image ads” campaigns). | |
CpmBannerAdBuilderAd | CpmBannerAdBuilderAdUpdate | Display ad parameters. | |
CpmVideoAdBuilderAd | CpmVideoAdBuilderAdUpdate | Parameters of a display video ad (in a “Display campaign”). | |
SmartAdBuilderAd | SmartAdBuilderAdUpdate | Smart banner parameters. | |
ShoppingAd | ShoppingAdUpdate | Product ad parameters. | |
ListingAd | ListingAdUpdate | Parameters of an ad for catalog pages. | |
TextAdUpdate structure | |||
Title | string | Title 1. Maximum of 56 characters, counting "narrow" characters. Maximum of 22 characters per word. If using a template, the # symbol isn't counted in the length. | No |
Title2 | string, nillable | 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 # symbol isn't counted in 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. If using a template, the # symbol isn't counted in the length. | No |
Href | string, nillable | Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # symbol isn't counted in the length. It must include the protocol and domain name. May contain substitution variables. | No |
AgeLabel | AgeLabelEnum | Age category. If an ad does not have an age label, this parameter can't be set (the value is ignored). | No |
DisplayUrlPath | string, nillable | Display link. Allowed only with the Href parameter. Maximum of 20 characters. If using a template, the # symbol isn't counted in the length. It may contain letters, numbers, and the symbols -, №, /, %, #. Spaces, underscores (_), and double characters -- and // are not allowed. See Display link in the Help for Yandex Direct. | No |
VCardId | long, nillable | ID of the vCard. The vCard must belong to the same campaign as the ad. | No |
AdImageHash | string, nillable | Hash of the image. For Text & Image ads, only images with the REGULAR or WIDE type are acceptable. See Type of image. | No |
SitelinkSetId | long, nillable | ID of a set of sitelinks. Allowed only with the Href or TurboPageId parameter. | No |
CalloutSetting | AdExtensionSetting, nillable | Callouts for an ad:
| No |
VideoExtension | VideoExtensionUpdateItem | Video extension. See See Video extensions in the Help for Yandex Direct. | No |
PriceExtension | PriceExtensionUpdateItem, nillable | Price in the ad. | No |
TurboPageId | long, nillable | ID of the Turbo page. | No |
BusinessId | long, nillable | 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/<id_profile> . | No |
PreferVCardOverBusiness | YesNoEnum | Indicates which data source takes priority when displaying an ad: YES — vCard, NO — business profile. Restriction. This parameter is used if the VCardID and BusinessId values are filled in. If one of these values is deleted, you must set the PreferVCardOverBusiness parameter to NO. | No |
ErirAdDescription | string | Ad object description. | No |
AdExtensionSetting structure | |||
AdExtensions | array of AdExtensionSettingItem | Extensions to assign to the ad or unassign from the ad. | Yes |
AdExtensionSettingItem structure | |||
AdExtensionId | long | Extension ID. | Yes |
Operation | AdExtensionTypeEnum | Type of action with the set of extensions:
See Exampleswhen calling finance methods. | Yes |
VideoExtensionUpdateItem structure | |||
CreativeId | long, nillable | ID of the creative. | Yes |
PriceExtensionUpdateItem 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. | No |
OldPrice | long, nillable | 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:
| No |
PriceCurrency | PriceCurrencyEnum | The currency that the price is shown in. | No |
DynamicTextAdUpdate structure | |||
VCardId | long, nillable | ID of the vCard. The vCard must belong to the same campaign as the ad. | No |
AdImageHash | string, nillable | Hash of the image. For dynamic ads, only images with the REGULAR or WIDE type are acceptable. See Type of image. | No |
SitelinkSetId | long, nillable | ID of a set of sitelinks. | No |
CalloutSetting | AdExtensionSetting, nillable | Callouts for an ad:
| 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. If using a template, the # symbol isn't counted in the length. | No |
MobileAppAdUpdate structure | |||
Title | string | Title. Maximum of 56 characters, counting “narrow” characters. Maximum of 22 characters per word. If using a template, the # symbol isn't counted in the length. | No |
Text | string | Ad text. Maximum of 75 characters, counting “narrow” characters. Maximum of 23 characters per word. If using a template, the # symbol isn't counted in the length. | No |
TrackingUrl | string, nillable | Tracking link for tracking app installations. Maximum of 1024 characters. It must include the protocol and domain name. | No |
Action | MobileAppAdActionEnum | The button label:
| No |
AdImageHash | string, nillable | Hash of the image. For mobile app ads, only images with the WIDE type are acceptable. See Type of image. | No |
Features | array of MobileAppAdFeatureItem | Add-ons that need to be automatically downloaded from the app store and displayed in the ad. | No |
AgeLabel | MobAppAgeLabelEnum | Age restriction. | No |
VideoExtension | VideoExtensionUpdateItem | Video extension. See See Video extensions in the Help for Yandex Direct. | No |
ErirAdDescription | string | Ad object description. | No |
MobileAppAdFeatureItem structure | |||
Feature | MobileAppFeatureEnum | Type of extension:
If the add-on type is omitted from the Features array, the add-on is not shown. | Yes |
Enabled | YesNoEnum | Whether to display an add-on in the ad. Note.
| Yes |
TextImageAdUpdate structure | |||
AdImageHash | string | Hash of the image. For image ads, only images with the FIXED_IMAGE type are acceptable. See Type of image. | No |
Href | string, nillable | Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # symbol isn't counted in the length. It must include the protocol and domain name. May contain substitution variables. | No |
TurboPageId | long, nillable | ID of the Turbo page. | No |
ErirAdDescription | string | Ad object description. | No |
MobileAppImageAdUpdate structure | |||
AdImageHash | string | Hash of the image. For image ads, only images with the FIXED_IMAGE type are acceptable. See Type of image. | No |
TrackingUrl | string, nillable | Tracking link for tracking app installations. Maximum of 1024 characters. It must include the protocol and domain name. | No |
ErirAdDescription | string | Ad object description. | No |
MobileAppCpcVideoAdBuilderAdUpdate structure | |||
Creative | AdBuilderAdUpdateItem | A creative that was created in the Ad Builder. See See Ad Builder for video ads in the Help for Yandex Direct. | No |
TrackingUrl | string, nillable | Tracking link for tracking app installations. Maximum of 1024 characters. It must include the protocol and domain name. | No |
ErirAdDescription | string | Ad object description. | No |
TextAdBuilderAdUpdate structure | |||
Creative | AdBuilderAdUpdateItem | A creative that was created in the Ad Builder. See Ad Builder for image ads in the Help for Yandex Direct. | No |
Href | string, nillable | Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # symbol isn't counted in the length. It must include the protocol and domain name. May contain substitution variables. | No |
TurboPageId | long, nillable | ID of the Turbo page. | No |
ErirAdDescription | string | Ad object description. | No |
MobileAppAdBuilderAdUpdate structure | |||
Creative | AdBuilderAdUpdateItem | A creative that was created in the Ad Builder. See Ad Builder for image ads in the Help for Yandex Direct. | No |
TrackingUrl | string, nillable | Tracking link for tracking app installations. Maximum of 1024 characters. It must include the protocol and domain name. | No |
ErirAdDescription | string | Ad object description. | No |
CpcVideoAdBuilderAdUpdate structure | |||
Creative | AdBuilderAdUpdateItem | A creative that was created in the Ad Builder. See Video ads / Ad Builder in the Help for Yandex Direct. | No |
Href | string, nillable | Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # symbol isn't counted in the length. It must include the protocol and domain name. May contain substitution variables. | No |
TurboPageId | long, nillable | ID of the Turbo page. | No |
ErirAdDescription | string | Ad object description. | No |
CpmBannerAdBuilderAdUpdate structure | |||
Creative | AdBuilderAdUpdateItem | A creative that was uploaded in the web interface or created in the Ad Builder. See How to launch a display campaign in the Help for Yandex Direct. | No |
Href | string, nillable | Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # symbol isn't counted in the length. It must include the protocol and domain name. May contain substitution variables. | No |
TrackingPixels | ArrayOfString, nillable | Can contain a maximum of two strings:
The maximum length of each string is 1024 characters. | No |
TurboPageId | long, nillable | ID of the Turbo page. | No |
ErirAdDescription | string | Ad object description. | No |
CpmVideoAdBuilderAdUpdate structure | |||
Creative | AdBuilderAdUpdateItem | A creative that was created in the Ad Builder. See Video advertising / How to launch in the Help for Yandex Direct. | No |
Href | string, nillable | Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # symbol isn't counted in the length. It must include the protocol and domain name. May contain substitution variables. | No |
TurboPageId | long, nillable | ID of the Turbo page. | No |
TrackingPixels | ArrayOfString, nillable | An ADFOX tracking tag. The tag must have the %random% or %aw_random% macro. Maximum of 1024 characters. | No |
ErirAdDescription | string | Ad object description. | No |
SmartAdBuilderAdUpdate structure | |||
Creative | AdBuilderAdUpdateItem | A creative that was created in the Ad Builder. See Ad Builder for smart banners in the Help for Yandex Direct. | No |
ErirAdDescription | string | Ad object description. | No |
AdBuilderAdUpdateItem structure | |||
CreativeId | long | ID of the creative. | Yes |
ShoppingAdUpdate structure | |||
SitelinkSetId | long | ID of a set of sitelinks. | No |
CalloutSetting | CalloutSetting | CalloutSetting | 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/<id_profile> . | No |
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 get the acceptable field names in the TitleAndTextSources field of the feeds.get method. | No |
TextSources | array of string | Names of feed fields used to generate ad texts. You can get the acceptable field names in the TitleAndTextSources field of the feeds.get method. | No |
DefaultTexts | array of string | Default texts. You can specify only one value. | Yes |
ListingAdUpdate structure | |||
SitelinkSetId | long | ID of a set of sitelinks. | No |
CalloutSetting | CalloutSetting | CalloutSetting | 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/<id_profile> . | No |
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 get the acceptable field names in the TitleAndTextSources field of the feeds.get method. | No |
TextSources | array of string | Names of feed fields used to generate ad texts. You can get the acceptable field names in the TitleAndTextSources field of the feeds.get method. | No |
DefaultTexts | array of string | Default texts. You can specify only one value. | Yes |
CalloutSetting structure | |||
AdExtensions | AdExtensions | Extensions for an ad. | Yes |
AdExtensions structure | |||
AdExtensionId | long | Extension ID. | Yes |
Operation | string | Action. Possible values:
| Yes |
FeedFilterConditionsItem structure | |||
Operand | string | Feed parameter. For a description of fields for each type of feed, see Configuring filters in the Help for Yandex Direct. | 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 |
Parameter | Type | Description | Required |
Params structure (for JSON) / UpdateRequest structure (for SOAP) | |||
---|---|---|---|
Ads | array of AdUpdateItem | Ads to change parameters for. | Yes |
AdUpdateItem structure | |||
Id | long | The ID of the ad to change parameters for. | Yes |
TextAd | TextAdUpdate | Parameters of a text and image ad. See Ad typewhen calling finance methods. | Either TextAd, or MobileAppAd, or DynamicTextAd, or TextImageAd, or MobileAppImageAd, or MobileAppCpcVideoAdBuilderAd, or TextAdBuilderAd, or MobileAppAdBuilderAd, or CpcVideoAdBuilderAd, or CpmBannerAdBuilderAd, or CpmVideoAdBuilderAd, or SmartAdBuilderAd |
DynamicTextAd | DynamicTextAdUpdate | Parameters of a dynamic ad. | |
MobileAppAd | MobileAppAdUpdate | Parameters of a mobile app ad. | |
TextImageAd | TextImageAdUpdate | Parameters of an image ad that was created from an image (in a group of text and image ads). | |
MobileAppImageAd | MobileAppImageAdUpdate | Parameters of an image ad that was created from an image (in a group of mobile app ads). | |
MobileAppCpcVideoAdBuilderAd | MobileAppCpcVideoAdBuilderAdUpdate | Parameters of a video ad that was created from an image (in a group of ads for mobile apps). | |
TextAdBuilderAd | TextAdBuilderAdUpdate | Parameters of an image ad that was created from a creative (in a group of text and image ads). | |
MobileAppAdBuilderAd | MobileAppAdBuilderAdUpdate | Parameters of an image ad that was created from a creative (in a group of mobile app ads). | |
CpcVideoAdBuilderAd | CpcVideoAdBuilderAdUpdate | Video ad parameters (in “Text & Image ads” campaigns). | |
CpmBannerAdBuilderAd | CpmBannerAdBuilderAdUpdate | Display ad parameters. | |
CpmVideoAdBuilderAd | CpmVideoAdBuilderAdUpdate | Parameters of a display video ad (in a “Display campaign”). | |
SmartAdBuilderAd | SmartAdBuilderAdUpdate | Smart banner parameters. | |
ShoppingAd | ShoppingAdUpdate | Product ad parameters. | |
ListingAd | ListingAdUpdate | Parameters of an ad for catalog pages. | |
TextAdUpdate structure | |||
Title | string | Title 1. Maximum of 56 characters, counting "narrow" characters. Maximum of 22 characters per word. If using a template, the # symbol isn't counted in the length. | No |
Title2 | string, nillable | 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 # symbol isn't counted in 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. If using a template, the # symbol isn't counted in the length. | No |
Href | string, nillable | Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # symbol isn't counted in the length. It must include the protocol and domain name. May contain substitution variables. | No |
AgeLabel | AgeLabelEnum | Age category. If an ad does not have an age label, this parameter can't be set (the value is ignored). | No |
DisplayUrlPath | string, nillable | Display link. Allowed only with the Href parameter. Maximum of 20 characters. If using a template, the # symbol isn't counted in the length. It may contain letters, numbers, and the symbols -, №, /, %, #. Spaces, underscores (_), and double characters -- and // are not allowed. See Display link in the Help for Yandex Direct. | No |
VCardId | long, nillable | ID of the vCard. The vCard must belong to the same campaign as the ad. | No |
AdImageHash | string, nillable | Hash of the image. For Text & Image ads, only images with the REGULAR or WIDE type are acceptable. See Type of image. | No |
SitelinkSetId | long, nillable | ID of a set of sitelinks. Allowed only with the Href or TurboPageId parameter. | No |
CalloutSetting | AdExtensionSetting, nillable | Callouts for an ad:
| No |
VideoExtension | VideoExtensionUpdateItem | Video extension. See See Video extensions in the Help for Yandex Direct. | No |
PriceExtension | PriceExtensionUpdateItem, nillable | Price in the ad. | No |
TurboPageId | long, nillable | ID of the Turbo page. | No |
BusinessId | long, nillable | 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/<id_profile> . | No |
PreferVCardOverBusiness | YesNoEnum | Indicates which data source takes priority when displaying an ad: YES — vCard, NO — business profile. Restriction. This parameter is used if the VCardID and BusinessId values are filled in. If one of these values is deleted, you must set the PreferVCardOverBusiness parameter to NO. | No |
ErirAdDescription | string | Ad object description. | No |
AdExtensionSetting structure | |||
AdExtensions | array of AdExtensionSettingItem | Extensions to assign to the ad or unassign from the ad. | Yes |
AdExtensionSettingItem structure | |||
AdExtensionId | long | Extension ID. | Yes |
Operation | AdExtensionTypeEnum | Type of action with the set of extensions:
See Exampleswhen calling finance methods. | Yes |
VideoExtensionUpdateItem structure | |||
CreativeId | long, nillable | ID of the creative. | Yes |
PriceExtensionUpdateItem 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. | No |
OldPrice | long, nillable | 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:
| No |
PriceCurrency | PriceCurrencyEnum | The currency that the price is shown in. | No |
DynamicTextAdUpdate structure | |||
VCardId | long, nillable | ID of the vCard. The vCard must belong to the same campaign as the ad. | No |
AdImageHash | string, nillable | Hash of the image. For dynamic ads, only images with the REGULAR or WIDE type are acceptable. See Type of image. | No |
SitelinkSetId | long, nillable | ID of a set of sitelinks. | No |
CalloutSetting | AdExtensionSetting, nillable | Callouts for an ad:
| 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. If using a template, the # symbol isn't counted in the length. | No |
MobileAppAdUpdate structure | |||
Title | string | Title. Maximum of 56 characters, counting “narrow” characters. Maximum of 22 characters per word. If using a template, the # symbol isn't counted in the length. | No |
Text | string | Ad text. Maximum of 75 characters, counting “narrow” characters. Maximum of 23 characters per word. If using a template, the # symbol isn't counted in the length. | No |
TrackingUrl | string, nillable | Tracking link for tracking app installations. Maximum of 1024 characters. It must include the protocol and domain name. | No |
Action | MobileAppAdActionEnum | The button label:
| No |
AdImageHash | string, nillable | Hash of the image. For mobile app ads, only images with the WIDE type are acceptable. See Type of image. | No |
Features | array of MobileAppAdFeatureItem | Add-ons that need to be automatically downloaded from the app store and displayed in the ad. | No |
AgeLabel | MobAppAgeLabelEnum | Age restriction. | No |
VideoExtension | VideoExtensionUpdateItem | Video extension. See See Video extensions in the Help for Yandex Direct. | No |
ErirAdDescription | string | Ad object description. | No |
MobileAppAdFeatureItem structure | |||
Feature | MobileAppFeatureEnum | Type of extension:
If the add-on type is omitted from the Features array, the add-on is not shown. | Yes |
Enabled | YesNoEnum | Whether to display an add-on in the ad. Note.
| Yes |
TextImageAdUpdate structure | |||
AdImageHash | string | Hash of the image. For image ads, only images with the FIXED_IMAGE type are acceptable. See Type of image. | No |
Href | string, nillable | Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # symbol isn't counted in the length. It must include the protocol and domain name. May contain substitution variables. | No |
TurboPageId | long, nillable | ID of the Turbo page. | No |
ErirAdDescription | string | Ad object description. | No |
MobileAppImageAdUpdate structure | |||
AdImageHash | string | Hash of the image. For image ads, only images with the FIXED_IMAGE type are acceptable. See Type of image. | No |
TrackingUrl | string, nillable | Tracking link for tracking app installations. Maximum of 1024 characters. It must include the protocol and domain name. | No |
ErirAdDescription | string | Ad object description. | No |
MobileAppCpcVideoAdBuilderAdUpdate structure | |||
Creative | AdBuilderAdUpdateItem | A creative that was created in the Ad Builder. See See Ad Builder for video ads in the Help for Yandex Direct. | No |
TrackingUrl | string, nillable | Tracking link for tracking app installations. Maximum of 1024 characters. It must include the protocol and domain name. | No |
ErirAdDescription | string | Ad object description. | No |
TextAdBuilderAdUpdate structure | |||
Creative | AdBuilderAdUpdateItem | A creative that was created in the Ad Builder. See Ad Builder for image ads in the Help for Yandex Direct. | No |
Href | string, nillable | Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # symbol isn't counted in the length. It must include the protocol and domain name. May contain substitution variables. | No |
TurboPageId | long, nillable | ID of the Turbo page. | No |
ErirAdDescription | string | Ad object description. | No |
MobileAppAdBuilderAdUpdate structure | |||
Creative | AdBuilderAdUpdateItem | A creative that was created in the Ad Builder. See Ad Builder for image ads in the Help for Yandex Direct. | No |
TrackingUrl | string, nillable | Tracking link for tracking app installations. Maximum of 1024 characters. It must include the protocol and domain name. | No |
ErirAdDescription | string | Ad object description. | No |
CpcVideoAdBuilderAdUpdate structure | |||
Creative | AdBuilderAdUpdateItem | A creative that was created in the Ad Builder. See Video ads / Ad Builder in the Help for Yandex Direct. | No |
Href | string, nillable | Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # symbol isn't counted in the length. It must include the protocol and domain name. May contain substitution variables. | No |
TurboPageId | long, nillable | ID of the Turbo page. | No |
ErirAdDescription | string | Ad object description. | No |
CpmBannerAdBuilderAdUpdate structure | |||
Creative | AdBuilderAdUpdateItem | A creative that was uploaded in the web interface or created in the Ad Builder. See How to launch a display campaign in the Help for Yandex Direct. | No |
Href | string, nillable | Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # symbol isn't counted in the length. It must include the protocol and domain name. May contain substitution variables. | No |
TrackingPixels | ArrayOfString, nillable | Can contain a maximum of two strings:
The maximum length of each string is 1024 characters. | No |
TurboPageId | long, nillable | ID of the Turbo page. | No |
ErirAdDescription | string | Ad object description. | No |
CpmVideoAdBuilderAdUpdate structure | |||
Creative | AdBuilderAdUpdateItem | A creative that was created in the Ad Builder. See Video advertising / How to launch in the Help for Yandex Direct. | No |
Href | string, nillable | Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # symbol isn't counted in the length. It must include the protocol and domain name. May contain substitution variables. | No |
TurboPageId | long, nillable | ID of the Turbo page. | No |
TrackingPixels | ArrayOfString, nillable | An ADFOX tracking tag. The tag must have the %random% or %aw_random% macro. Maximum of 1024 characters. | No |
ErirAdDescription | string | Ad object description. | No |
SmartAdBuilderAdUpdate structure | |||
Creative | AdBuilderAdUpdateItem | A creative that was created in the Ad Builder. See Ad Builder for smart banners in the Help for Yandex Direct. | No |
ErirAdDescription | string | Ad object description. | No |
AdBuilderAdUpdateItem structure | |||
CreativeId | long | ID of the creative. | Yes |
ShoppingAdUpdate structure | |||
SitelinkSetId | long | ID of a set of sitelinks. | No |
CalloutSetting | CalloutSetting | CalloutSetting | 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/<id_profile> . | No |
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 get the acceptable field names in the TitleAndTextSources field of the feeds.get method. | No |
TextSources | array of string | Names of feed fields used to generate ad texts. You can get the acceptable field names in the TitleAndTextSources field of the feeds.get method. | No |
DefaultTexts | array of string | Default texts. You can specify only one value. | Yes |
ListingAdUpdate structure | |||
SitelinkSetId | long | ID of a set of sitelinks. | No |
CalloutSetting | CalloutSetting | CalloutSetting | 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/<id_profile> . | No |
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 get the acceptable field names in the TitleAndTextSources field of the feeds.get method. | No |
TextSources | array of string | Names of feed fields used to generate ad texts. You can get the acceptable field names in the TitleAndTextSources field of the feeds.get method. | No |
DefaultTexts | array of string | Default texts. You can specify only one value. | Yes |
CalloutSetting structure | |||
AdExtensions | AdExtensions | Extensions for an ad. | Yes |
AdExtensions structure | |||
AdExtensionId | long | Extension ID. | Yes |
Operation | string | Action. Possible values:
| Yes |
FeedFilterConditionsItem structure | |||
Operand | string | Feed parameter. For a description of fields for each type of feed, see Configuring filters in the Help for Yandex Direct. | 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 |
Response
Response structure in JSON format:
{
"result": { /* result */
"UpdateResults": [{ /* ActionResult */
"Id": (long),
"Warnings": [{ /* ExceptionNotification */
"Code": (int), /* required */
"Message": (string), /* required */
"Details": (string)
}, ...
],
"Errors": [{ /* ExceptionNotification */
"Code": (int), /* required */
"Message": (string), /* required */
"Details": (string)
}, ...
]
}, ... ] /* required */
}
}
Parameter | Type | Description |
Result structure (for JSON) / UpdateResponse structure (for SOAP) | ||
---|---|---|
UpdateResults | array of ActionResult | Results of updating ad parameters. |
ActionResult structure | ||
Id | long | The ad ID. Returned if there are no errors, see Operations on object arrays. |
Warnings | array of ExceptionNotification | Warnings that occurred during the operation. |
Errors | array of ExceptionNotification | Errors that occurred during the operation. |
Parameter | Type | Description |
Result structure (for JSON) / UpdateResponse structure (for SOAP) | ||
---|---|---|
UpdateResults | array of ActionResult | Results of updating ad parameters. |
ActionResult structure | ||
Id | long | The ad ID. Returned if there are no errors, see Operations on object arrays. |
Warnings | array of ExceptionNotification | Warnings that occurred during the operation. |
Errors | array of ExceptionNotification | Errors that occurred during the operation. |
Examples
- Making changes to the set of ad extensions
-
The callouts with the IDs 111, 112, and 113 were assigned to the ad.
Executing the request will assign the callouts with the IDs 111, 112, 114, and 115 to the ad.
{ "method": "update", "params": { "Ads": [{ "Id": 7654321, "TextAd": { "CalloutSetting": { "AdExtensions": [{ "AdExtensionId": 114, "Operation": "ADD" }, { "AdExtensionId": 115, "Operation": "ADD" }, { "AdExtensionId": 113, "Operation": "REMOVE" }] } } }] } }
- Replacing the set of extensions
-
The callouts with the IDs 111, 112, and 113 were assigned to the ad.
Executing the request will assign the callouts with the IDs 113 and 114 to the ad.
{ "method": "update", "params": { "Ads": [{ "Id": 7654321, "TextAd": { "CalloutSetting": { "AdExtensions": [{ "AdExtensionId": 113, "Operation": "SET" }, { "AdExtensionId": 114, "Operation": "SET" }] } } }] } }