Documentation

Campaign

The Campaign object contains an advertising campaign's settings and summary statistics.

Service

Use the Campaigns service for managing campaigns.

Methods

add | update | delete | suspend | resume | archive | unarchive | get

Restrictions

Maximum of 3000 campaigns per advertiser. Maximum of 1000 unarchived campaigns.

Campaign type

The campaign type is set when creating a campaign and can't be changed.

The campaign type determines the type for child ad groups. You can only add the corresponding type of groups to the campaign.

Part of the campaign parameters are shared across all types of campaigns, and part of them depend on the type of campaign. The parameters that depend on the campaign type are passed in a child structure with the corresponding name.

The following types of campaigns are currently available:

  • TEXT_CAMPAIGN — A campaign with the type “Text & Image Ads”.

    To create or edit this type of campaign, you must pass the campaign parameters in the TextCampaign structure for the add or update method. For parameter descriptions, see the sections add: TextCampaign parameters and update: TextCampaign parameters.

    When getting campaign parameters, list the names of parameters that are shared across all campaign types in the FieldNames input parameter, and list the names of parameters that are specific to this campaign type in the TextCampaignFieldNames input parameter of the get method. For descriptions of the parameters returned for this type of campaign, see the section get: TextCampaign parameters.

  • MOBILE_APP_CAMPAIGN — A campaign with the type “Ads for mobile apps”. For more information about advertising mobile apps, see Ads for Mobile Apps in the Help for Yandex.Direct.

    To create or edit this type of campaign, you must pass the campaign parameters in the MobileAppCampaign structure for the add or update method. For parameter descriptions, see the sections add: MobileAppCampaign parameters and update: MobileAppCampaign parameters.

    When getting campaign parameters, list the names of parameters that are shared across all campaign types in the FieldNames input parameter, and list the names of parameters that are specific to this campaign type in the MobileAppCampaignFieldNames input parameter of the get method. For descriptions of the parameters returned for this type of campaign, see the section get: MobileAppCampaign parameters.

  • DYNAMIC_TEXT_CAMPAIGN — A campaign with the “Dynamic ads” type. For more information about dynamic text ads, see Dynamic ads in the Help for Yandex.Direct.

    To create or edit this type of campaign, you must pass the campaign parameters in the DynamicTextCampaign structure for the add or update method. For parameter descriptions, see the sections add: DynamicTextCampaign parameters and update: DynamicTextCampaign parameters.

    When getting campaign parameters, list the names of parameters that are shared across all campaign types in the FieldNames input parameter, and list the names of parameters that are specific to this campaign type in the DynamicTextCampaignFieldNames input parameter of the get method. For descriptions of the parameters returned for this type of campaign, see the section get: DynamicTextCampaign parameters.

Display strategies

See the section Display strategies.

Monetary parameters

Attention! All monetary campaign parameters (daily budget, weekly budget, and average price for automatic strategies) are passed via the Direct API as integer numbers. The passed value is a monetary value in the advertiser's currency, multiplied by 1,000,000.

Limits on monetary parameters are listed for each currency in the currency reference. To get the list of currencies, use the Dictionaries.get method.

Campaign status and state

The State parameter reflects the current state of displays in the campaign.

StateDescription
CONVERTEDThe campaign was run in Yandex units before the advertiser switched to currency. It is currently in a special archive and available only for read access. See the Terms of converting Advertiser account into currency of payment (excluding rubles).
Note. The get method returns a campaign in the CONVERTED state only if the States parameter is set to CONVERTED or the ID of this campaign is specified in the Ids parameter. If the Ids and States parameters are both omitted, the method doesn't return a campaign in the CONVERTED state.
ARCHIVEDThe campaign has been archived using the archive method, by the user in the web interface, or automatically (if the account funds were depleted and there haven't been any displays for more than 30 days).
SUSPENDEDThe owner has stopped the campaign using the suspend method or in the web interface.
ENDEDThe campaign ended (the end date has passed).
ONThe campaign is active and ads can be displayed.
OFFThe campaign is inactive (draft, pending review, rejected, no funds on the campaign or on the shared account, or no active ads).
UNKNOWNUsed for providing backward compatibility and displaying states that are not supported in this version of the API.

The Status parameter reflects the overall result of reviewing the campaign objects.

StatusDescription
DRAFT

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

MODERATIONThe campaign is under review.
ACCEPTEDAt least one of the campaign's ads was accepted after review.
REJECTEDAll of the campaign's ads were rejected after review.
UNKNOWNThis value is used for backward compatibility and for displaying statuses that are not supported in this version of the API.

The StatusPayment parameter indicates whether the campaign is ready for payments.

Payment statusDescription
DISALLOWED

Payment is not allowed (or only pre-payment before being reviewed is available).

ALLOWEDThe campaign was accepted after review, or the shared account is enabled.