update

Restrictions

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 */ 
        }  
      },
      "MobileAppAd": {  /* MobileAppAdUpdate */
         "Title": (string),
         "Text": (string),
         "TrackingUrl": (string), /* nillable */ 
         "Features": [{  /* MobileAppAdFeatureItem */
           "Feature": ( "PRICE" | "ICON" | "CUSTOMER_RATING" | "RATINGS" ), /* required */
           "Enabled": ( "YES" | "NO" ) /* required */
         }, ... ],             
         "Action": ( "DOWNLOAD" | "GET" | "INSTALL" | "MORE" | "OPEN" | 
"UPDATE" | "PLAY" | "BUY_AUTODETECT" ),
         "AgeLabel": ( "AGE_0" | ... | "AGE_18" ),
         "AdImageHash": (string) /* nillable */
      }, 
      "DynamicTextAd": {  /* DynamicTextAdUpdate */
        "Text": (string),             
        "VCardId": (long), /* nillable */ 
        "AdImageHash": (string), /* nillable */ 
        "SitelinkSetId": (long), /* nillable */ 
        "CalloutSetting": {  /* AdExtensionSetting */
          "AdExtensions": [{  /* AdExtensionSettingItem */
            "AdExtensionId": (long), /* required */
            "Operation": ( "ADD" | "REMOVE" | "SET" ) /* required */
          }, ... ] /* required */
        } /* nillable */
      },
      "TextImageAd": {  /* TextImageAdUpdate */
        "Href": (string),
        "AdImageHash": (string)
      },
      "MobileAppImageAd": {  /* MobileAppImageAdUpdate */
        "TrackingUrl": (string), /* nillable */
        "AdImageHash": (string)
      },
      "TextAdBuilderAd": {  /* TextAdBuilderAdUpdate */
        "Creative": { /* AdBuilderAdUpdateItem */
          "CreativeId": (long) /* required */
        }, 
        "Href": (string)
      },
      "MobileAppAdBuilderAd": {  /* MobileAppAdBuilderAdUpdate */
        "Creative": { /* AdBuilderAdUpdateItem */
          "CreativeId": (long) /* required */
        }, 
        "TrackingUrl": (string) /* nillable */
      },
      "CpcVideoAdBuilderAd" {  /* CpcVideoAdBuilderAdUpdate */
        "Creative": { /* AdBuilderAdUpdateItem */
          "CreativeId": (long) /* required */
        }, 
        "Href": (string)
      },
      "CpmBannerAdBuilderAd": {  /* CpmBannerAdBuilderAdUpdate */
        "Creative": { /* AdBuilderAdUpdateItem */
          "CreativeId": (long) /* required */
        }, 
        "Href": (string), 
        "TrackingPixels": { /* ArrayOfString */
          "Items": [(string), ... ] /* required */
        } /* nillable */
      }
    }, ... ] /* required */
  } 
}
ParameterTypeDescriptionRequired
Params structure (for JSON) / UpdateRequest structure (for SOAP)
Adsarray of AdUpdateItemAds to change parameters for.Yes
AdUpdateItem structure
IdlongThe ID of the ad to change parameters for.Yes
TextAdTextAdUpdateParameters 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
MobileAppAdMobileAppAdUpdateParameters of a mobile app ad.
DynamicTextAdDynamicTextAdUpdateParameters of a dynamic ad.
TextImageAdTextImageAdUpdateParameters of an image ad that was created from an image (in a group of text and image ads).
MobileAppImageAdMobileAppImageAdUpdateParameters of an image ad that was created from an image (in a group of mobile app ads).
TextAdBuilderAdTextAdBuilderAdUpdateParameters of an image ad that was created from a creative (in a group of text and image ads).
MobileAppAdBuilderAdMobileAppAdBuilderAdUpdateParameters of an image ad that was created from a creative (in a group of mobile app ads).
CpcVideoAdBuilderAdCpcVideoAdBuilderAdUpdateVideo ad parameters.
CpmBannerAdBuilderAdCpmBannerAdBuilderAdUpdateDisplay ad parameters.
TextAdUpdate 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.

No
Title2string, 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 # 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.

No
Hrefstring, nillable

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.

No
AgeLabelAgeLabelEnumAge category.

If an ad does not have an age label, this parameter can't be set (the value is ignored).

No
DisplayUrlPathstring, nillable

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
VCardIdlong, nillableID of the vCard. The vCard must belong to the same campaign as the ad.No
AdImageHashstring, nillable

Hash of the image.

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

Callouts for an ad:

  • To make changes in an existing set of callouts, use the ADD and REMOVE types of actions (see the description for the Operation parameter).

  • To replace an existing set of callouts with a new set, use the SET action.

  • To unassign all callouts, pass the nil (null) value.
No
VideoExtensionVideoExtensionUpdateItem

Video extension.

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

No
AdExtensionSetting structure
AdExtensionsarray of AdExtensionSettingItemExtensions to assign to the ad or unassign from the ad.Yes
AdExtensionSettingItem structure
AdExtensionIdlongExtension ID.Yes
OperationAdExtensionTypeEnumType of action with the set of extensions:
  • ADD — Assign the extension to the ad.

  • REMOVE — Unassign the extension from the ad.

  • SET — Replace the set of extensions and assign the extension to the ad as part of the new set. The SET type is incompatible with ADD and REMOVE. All the items in the AdExtensions array must have the SET type.

See Examples.

Yes
VideoExtensionUpdateItem structure
CreativeIdlong, nillable

ID of the creative.

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

Yes
MobileAppAdUpdate 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.

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

No
TrackingUrlstring, nillableTracking 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
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
AgeLabelMobAppAgeLabelEnumAge restriction.No
AdImageHashstring, nillable

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

No
VCardIdlong, nillableID of the vCard. The vCard must belong to the same campaign as the ad.No
AdImageHashstring, nillable

Hash of the image.

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

No
SitelinkSetIdlong, nillableID of a set of sitelinks.No
CalloutSettingAdExtensionSetting, nillable

Callouts for an ad:

  • To make changes in an existing set of callouts, use the ADD and REMOVE types of actions (see the description for the Operation parameter).

  • To replace an existing set of callouts with a new set, use the SET action.

  • To unassign all callouts, pass the nil (null) value.
No
TextImageAdUpdate 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.

No
AdImageHashstring

Hash of the image.

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

No
MobileAppImageAdUpdate structure
TrackingUrlstring, nillableTracking 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.

No
TextAdBuilderAdUpdate structure
CreativeAdBuilderAdUpdateItem

A creative that was created in the Ad Builder.

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

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

No
MobileAppAdBuilderAdUpdate structure
CreativeAdBuilderAdUpdateItem

A creative that was created in the Ad Builder.

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

No
TrackingUrlstring, nillableTracking link for tracking app installations. Maximum of 1024 characters. It must include the protocol and domain name.No
CpcVideoAdBuilderAdUpdate structure
CreativeAdBuilderAdUpdateItem

A creative that was created in the Ad Builder.

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

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

No
CpmBannerAdBuilderAdUpdate structure
CreativeAdBuilderAdUpdateItem

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.

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

No
TrackingPixelsArrayOfString, nillableCan contain a maximum of two strings:
  • A Yandex.Audience pixel (see Pixel in the Help for Yandex.Audience).
  • An impression tag for ADFOX, TNS or Gemius. The tag must have the %random% or %aw_random% macro.

The maximum length of each string is 1024 characters.

No
AdBuilderAdUpdateItem structure
CreativeIdlong

ID of the creative.

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

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 */
  }
}
ParameterTypeDescription
Result structure (for JSON) / UpdateResponse structure (for SOAP)
UpdateResultsarray of ActionResultResults of updating ad parameters.
ActionResult structure
IdlongThe ad ID. 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

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"
          }]
        }  
      }
    }]
  }
}