Ad

An ad consists of advertising materials. The set of parameters for an ad depends on its type.

Restrictions

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

Operations with ads are not possible in archived campaigns.

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

For restrictions on ad parameters, see Quantitative restrictions in the Help for Yandex.Direct.

Note.
  • An ad in Ukrainian can only be added to a group that has the display region restricted to Ukraine.
  • An ad in Belarusian can only be added to a group that has the display region restricted to Belarusia.
  • An ad in Kazakh can only be added to a group that has the display region restricted to Kazakhstan.
  • An ad in Turkish can only be added to a group that has the display region restricted to Turkey.

Ad type

The ad type is set when creating an ad and can't be changed.

The following types of ads are currently available:

  • TEXT_AD — A text and image (normal) ad.

    The ad contains a title and ad text, as well as a link to the advertised website. You can also include a display link, an image, a video extension, a set of sitelinks, a vCard, and callouts with an ad. If there is a vCard, the website link is optional. An ad can be automatically assigned an age label. In this case, you can change the label.

    To create or edit a text and image ad, pass its parameters in the TextAd structure of the add or update method.

    To get the ad parameters, list the parameter names in the TextAdFieldNames input parameter for the get method.

  • MOBILE_APP_AD — An ad for advertising mobile apps.

    The ad contains a title, text, and age restriction, as well as a label for the button to download or install. You can also add an image, specify a tracking link to track installs, and include a set of add-ons that need to be downloaded from the app store (icon, rating, and so on). For more information about advertising mobile apps, see Ads for Mobile Apps in the Help for Yandex.Direct.

    To create or edit an ad for mobile app advertising, pass its parameters in the MobileAppAd structure of the add or update method.

    To get the parameters of a mobile ad, list the parameter names in the MobileAppAdFieldNames input parameter of the get method.

  • DYNAMIC_TEXT_AD — A dynamic ad.

    The ad contains text. You can also include an image, a set of sitelinks, a vCard, and callouts with an ad. For more information about dynamic text ads, see Dynamic ads in the Help for Yandex.Direct.

    To create or edit a dynamic ad, pass its parameters in the DynamicTextAd structure of the add or update method.

    To get the ad parameters, list the parameter names in the DynamicTextAdFieldNames input parameter for the get method.

  • IMAGE_AD — An image ad.

    There are four subtypes of image ads:

    • TEXT_IMAGE_AD

      The ad contains an image and a link to the advertised website.

      To create or edit an ad, pass its parameters in the TextImageAd structure for the add or update method.

      To get the ad parameters, list the parameter names in the TextImageAdFieldNames input parameter for the get method.

    • MOBILE_APP_IMAGE_AD

      The ad contains an image. You can also add a tracking link to the ad for tracking installations.

      To create or edit an ad, pass its parameters in the MobileAppImageAd structure for the add or update method.

      To get the ad parameters, list the parameter names in the MobileAppImageAdFieldNames input parameter for the get method.

    • TEXT_AD_BUILDER_AD

      The ad contains a creative that was created in the Ad Builder and a link to the advertised website.

      To create or edit an ad, pass its parameters in the TextImageAd structure for the add or update method.

      To get the ad parameters, list the parameter names in the TextAdBuilderAdFieldNames input parameter for the get method.

    • MOBILE_APP_AD_BUILDER_AD

      The ad contains a creative that was created in the Ad Builder. You can also add a tracking link to the ad for tracking installations.

      To create or edit an ad, pass its parameters in the MobileAppImageAd structure for the add or update method.

      To get the ad parameters, list the parameter names in the MobileAppAdBuilderAdFieldNames input parameter for the get method.

    Attention.

    Image ads are only displayed in ad networks (the Yandex Advertising Network and external networks); they are not displayed in search results.

    Displays of image ads are possible only if the bid on a keyword or audience target meets the minimum CPC for an ad containing an image, which you can find on the Minimum and maximum CPC page.

    For more information about image ads, see Image ads in the Help for Yandex.Direct.

  • CPC_VIDEO_AD — Video ad.

    The ad contains a creative that was created in the Ad Builder and a link to the advertised website.

    To create or edit an ad, pass its parameters in the CpcVideoAdBuilderAd structure for the add or update method.

    To get the ad parameters, list the parameter names in the CpcVideoAdBuilderAdFieldNames input parameter of the get method.

  • CPM_BANNER_AD — A banner ad.

    The ad contains a creative that was loaded in the web interface or created in the Ad Builder and a link to the advertised website. You can also add a Yandex.Audience pixel and the ADFOX, TNS, or Gemius impression tag to ads.

The Type, Subtype, Status, State, StatusClarification, AdCategories, and AgeLabel parameters are common to all types of ads. To get these parameters, list the desired parameter names in the FieldNames input parameter of the get method.

The table below shows how ad types correspond to group types.

Ad group typePossible types of ads
TEXT_AD_GROUP

TEXT_AD

IMAGE_AD with subtypes TEXT_IMAGE_AD and TEXT_AD_BUILDER_AD

CPC_VIDEO_AD

MOBILE_APP_AD_GROUP

MOBILE_APP_AD

IMAGE_AD with subtypes MOBILE_APP_IMAGE_AD and MOBILE_APP_AD_BUILDER_AD

DYNAMIC_TEXT_AD_GROUPDYNAMIC_TEXT_AD
CPM_BANNER_AD_GROUPCPM_BANNER_AD

Ad status and state

The State parameter reflects the current state of the ad.

StateDescription
SUSPENDEDAd displays were stopped by the owner using the suspend method or in the web interface.
OFF_BY_MONITORINGAd displays are automatically stopped by site availability monitoring.
ONThe ad is active, belongs to an active campaign, and can be served (if the campaign has funds, time targeting settings allow displays, and so on).
OFFThe ad is inactive (a draft, pending review, or rejected), or belongs to an inactive or suspended campaign.
ARCHIVEDThe ad has been archived (using the archive method, or in the web interface), or belongs to an archived campaign.

The Status parameter reflects the result of reviewing the ad.

StatusDescription
DRAFT

The ad has been created but has not yet been submitted for review.

MODERATIONThe ad is under review.
PREACCEPTEDThe ad has been automatically accepted for displays, but will be further reviewed by a moderator.
ACCEPTEDThe ad was accepted after review.
REJECTEDThe ad was rejected after review.
Note.

If the ad was edited, and the new version is pending review (the MODERATION status) or was immediately rejected after review (the REJECTED status), the previous version of the ad continues being served if it was not suspended. In this case, the ad has the ON status.

If the new version of the ad was automatically accepted for display after editing (PREACCEPTED), and then it was rejected (REJECTED), displays of the previous version will not be resumed.

Special category

During the review, an ad can be assigned a label stating that the advertised product or service belongs to a special category. In this case, the ad is given the AdCategories parameter, which cannot be changed.

For certain categories, ad displays are forbidden. For others, ads are served with a special warning in accordance with the legislation of the Russian Federation.

To get the reference list of special categories, use the Dictionaries.get method.

These categories cannot be changed, assigned, or removed via the API. If you disagree with the category assigned, contact the Support service.

Age label

The AgeLabel parameter contains the age-appropriate category of the advertised product, if this category is required to be specified by the federal law of the Russian Federation “About advertising”. The way the age category is assigned depends on the type of ad.

The value of the age label depends on whether the ad belongs to the special category BABY_FOOD:

  • For ads that belong to the BABY_FOOD category, it is the age of the infant in months: "MONTHS_0", "MONTHS_1", "MONTHS_2", ..., "MONTHS_12".

  • For all other ads, it is the age that the informational product is appropriate for. Possible values: "AGE_0", "AGE_6", "AGE_12", "AGE_16", "AGE_18".

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

Restriction.

The API can only be used to change the value of the age category, if the ad has one. In order to change whether an ad has or doesn't have an age category, contact the Support service.

Add-ons

You can use the add and update methods to link a vCard, image, video extension, set of sitelinks, or callouts with an ad (depending on the ad type). For more information, see Adding vCards, images, sitelinks, callouts, and video extensions to an ad.

Bids for images and video extensions

Images and video extensions are only displayed in ad networks (the Yandex Advertising Network and external networks); they are not displayed in search results.

An image or video extension can be displayed only if the bid for the keyword or audience target meets the minimum CPC for an ad containing an image, which you can find on the Minimum and maximum CPC page. Otherwise, the ad is shown without the image or video extension.

Result of reviewing add-ons

The vCard, image, video extension, and sitelinks are not reviewed in isolation, but together with the ad. They are submitted for review automatically if the ad itself is under review or has already been reviewed.

The get method returns the result of reviewing the vCard (VCardModeration structure), image (AdImageModeration structure), sitelinks (SitelinksModeration structure), or video extension (Status parameter in the VideoExtension structure).

Review statusDescription
DRAFTThe add-on has not been submitted for review.
MODERATION

The add-on is under review.

ACCEPTEDThe add-on was accepted after review. The ad will contain the add-on when it is shown.
REJECTEDThe add-on was rejected after review.
UNKNOWNThe status is unknown. This value is used for backward compatibility and for displaying statuses that are not supported in this version of the API.