Campaign

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

Restrictions

To get the limit on the number of campaigns for an advertiser, use the method Clients.get or AgencyClients.get (see the CAMPAIGNS_TOTAL_PER_CLIENT and CAMPAIGNS_UNARCHIVED_PER_CLIENT elements in the Restrictions array).

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 “Text & Image ads” type.

    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 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 get: TextCampaign parameters.

  • UNIFIED_CAMPAIGN — A unified performance campaign

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

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

  • SMART_CAMPAIGN: A campaign with the “Smart banners” type. For more information about smart banners, see Smart banners in the Help for Yandex Direct.

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

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

  • DYNAMIC_TEXT_CAMPAIGN — A campaign with the “Dynamic ads” type. For more information about dynamic 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 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 get: DynamicTextCampaign parameters.

  • MOBILE_APP_CAMPAIGN — A campaign with the “Ads for mobile apps” type. 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 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 get: MobileAppCampaign parameters.

  • MCBANNER_CAMPAIGN — A campaign with the “Search banner” type. For more information about banners in search results, see Search banners in the Help for Yandex Direct.

    This type of campaign only allows getting statistics via the Yandex Direct API.

  • CPM_BANNER_CAMPAIGN — A campaign with the “Display campaign” type. For more information about display campaigns, see Display banners in the Help for Yandex Direct.

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

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

  • CPM_DEALS_CAMPAIGN — A campaign with the “Display campaign with deals” type. For more information about deals, see Deals in the Help for Yandex Direct.

    This type of campaign only allows getting statistics via the Yandex Direct API.

  • CPM_FRONTPAGE_CAMPAIGN — A campaign with the “Display campaign on the Home page” type. For more information about this type of campaigns, see Display banner on the Yandex Home page in the Help for Yandex Direct.

    This type of campaign only allows getting statistics via the Yandex Direct API.

  • CPM_PRICE — A campaign with the “Campaign with fixed CPM” type. For more information about this type of campaigns, see Campaigns with fixed CPM in the Yandex Direct Help.

    This type of campaign only allows getting statistics via the Yandex Direct API.

Monetary parameters

Attention. All monetary campaign parameters (daily budget, weekly budget, and average price for automatic strategies) are passed via the Yandex 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.

State Description
CONVERTED The campaign was run in Yandexunits before the advertiser switched to a real currency. It has now been moved to a special archive and is read-only.
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 both the Ids and States parameters are omitted, the method doesn't return a campaign in the CONVERTED state.
ARCHIVED The 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).
SUSPENDED The owner has stopped the campaign using the suspend method or in the web interface.
ENDED The campaign ended (the end date has passed).
ON The campaign is active and ads can be displayed.
OFF The campaign is inactive (draft, pending review, rejected, no funds on the campaign or on the shared account, or no active ads).
UNKNOWN Used for providing backward compatibility and displaying states that are not supported in this version of the API.
State Description
CONVERTED The campaign was run in Yandexunits before the advertiser switched to a real currency. It has now been moved to a special archive and is read-only.
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 both the Ids and States parameters are omitted, the method doesn't return a campaign in the CONVERTED state.
ARCHIVED The 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).
SUSPENDED The owner has stopped the campaign using the suspend method or in the web interface.
ENDED The campaign ended (the end date has passed).
ON The campaign is active and ads can be displayed.
OFF The campaign is inactive (draft, pending review, rejected, no funds on the campaign or on the shared account, or no active ads).
UNKNOWN Used 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.

Status Description
DRAFT

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

MODERATION The campaign is under review.
ACCEPTED At least one of the campaign's ads was accepted after review.
REJECTED All of the campaign's ads were rejected after review.
UNKNOWN This value is used for backward compatibility and for displaying statuses that are not supported in this version of the API.
Status Description
DRAFT

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

MODERATION The campaign is under review.
ACCEPTED At least one of the campaign's ads was accepted after review.
REJECTED All of the campaign's ads were rejected after review.
UNKNOWN This 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 status Description
DISALLOWED

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

ALLOWED The campaign was accepted after review, or the shared account is enabled.
Payment status Description
DISALLOWED

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

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