Version 4 (deprecated)

Stable version of the Yandex.Direct API. Released in May, 2011.

Address for requests in JSON format:

https://api.direct.yandex.ru/v4/json/

Address of the WSDL (for using the SOAP protocol):

https://api.direct.yandex.ru/v4/wsdl/

Address for SOAP requests:

https://api.direct.yandex.ru/v4/soap/

New in version 4

Attention.
  • Account access may be suspended for advertisers using Yandex units who haven't made payments for over a year. In this case, calling API methods results in the error 54, and the web interface doesn't allow access to any operations except switching to a currency.

    To continue using the API, you need to switch your account to a payment currency. To do this, click Switch now in the Yandex.Direct web interface. For more information about switching to a currency, see the Help for Yandex.Direct: Russian rubles or other currency.

  • As of October 10, 2016, advertising agencies can only register clients who are using a real currency. Registration of clients who use Yandex units has been disabled. Accordingly, the logic of the CreateNewSubclient method has changed. Details

  • Statistics provided by the GetSummaryStat and CreateNewReport methods are available for the three years prior to the current month. For example, on September 15, 2016, you can get data starting from September 1, 2013.

  • Introduced changes in data structures on April 25, 2016: types changed for the BannerID, BannerIDS, Banner, and Banners parameters. Details

  • The DisabledDomains campaign parameter now supports ad exchanges (SSPs).

  • For theGetWordstatReportList method, added the Failed value for the StatusReport output parameter.

    For the GetForecastList method, added the Failed value for the StatusForecast output parameter.

  • The RelevantPhrasesBudgetLimit campaign parameter no longer supports the value –1. To allow unlimited spending on related keywords (within the campaign budget), use the value 100.

  • Changed the restrictions for keywords. Now an ad group can contain a maximum of 200 keywords, and the maximum length of each keyword is 4096 characters.

  • The GetBanners, GetBannerPhrases andGetBannerPhrasesFilter methods return restrictions on getting auction results. Details
  • Beginning October 22, 2015, creating new SSL certificates is no longer available. Certificates created earlier can be used until they expire.

  • Added a limitation for the CreateOrUpdateBanners method: no more than 1000 ads per call.
  • Introduced the procedure for registering applications.
  • Established requirements for applications that access the API.
  • All interaction with the API, including getting WSDL descriptions, is performed over the HTTPS protocol. HTTP access is forbidden.

  • On April 1, 2014, changes were made in data structures: the parameter type was changed for PhraseID. Details

  • Corrected the default behavior for the CreateNewReport and GetSummaryStat methods: if the client operates in a real currency, the report will show the CPC before applying the discount, converted from the currency to Yandex units.

  • The GetCampaignsParams method, which returns the parameters of multiple campaigns for a single call. Recommended instead of the GetCampaignParams method.
  • Block of finance methods:
    • CreateInvoice — Generates an invoice for one or more campaigns.
    • GetCreditLimits — Returns information about credit provided to an advertising agency for campaign payments.
    • PayCampaigns — Pays for a campaign using credit.
    • TransferMoney — Transfers funds between campaigns.

    The finance methods are protected by additional tokens (see Accessing finance methods).

  • The GetChanges method checks for changes in campaigns and ads, in the region and time zone directories, and in Yandex.Catalog.
  • The DeleteWordstatReport method deletes the report on keyword statistics.
  • The UpdateClientInfo method changes clients' personal information, permissions and notification parameters.
  • The GetSummaryStat method — Returns aggregate statistics for campaigns for each day of the specified time period.
  • Substitution variables in website links (see the input parameters Param1 and Param2 in the CreateOrUpdateBanners method). The substitution variables are set for keywords, and are automatically inserted in links to the advertiser's website when displaying ads. This lets you modify links depending on the keyword that found the ad.

Changes to data structures

  • The output parameter SumAvailableForTransfer in the GetCampaignParams, GetCampaignsParams and GetCampaignsList methods. Specifies the amount available to transfer using the TransferMoney method.
  • The output parameter Strategy in the GetCampaignParams and GetCampaignsParams methods. Contains a structure with settings for the display strategy. The Strategy parameter replaced the AutoBudget, AutobudgetSum and AutobudgetMaxBid parameters, which were used in previous versions of the API and deprecated in version 4.
  • The ClientRights parameter, which describes clients' rights. Output parameter for the GetClientInfo and GetClientsList methods, and input parameter for the UpdateClientInfo method.
  • The CampaignEmails output parameter in the GetClientInfo and GetClientsList methods. Contains the email addresses for all the client's campaigns.
  • The Filter input parameter in the GetClientsList and GetSubClients methods. Sets conditions for selecting clients.
  • The PhrasesType input parameter in the SetAutoPrice method. Sets conditions for selecting keywords to calculate the CPC for.
  • The Scope input parameter in the SetAutoPrice method. Sets the parameters for calculating CPC for keywords that are disabled in the search but active in the Yandex Advertising Network.
  • The GetPhrases input parameter in the GetBanners method. Specifies whether it is necessary to output a Phrases array in the response with data for all the ad's keywords.
  • The MinusKeywords output parameter in the GetBanners method. Contains the negative keywords that are shared for all the ad's keywords (these are added to the negative keywords specified in the keywords).

Other changes

  • The methods GetRegions, GetRubrics and GetTimeZones return data in English if the locale parameter is not specified in the method call. In the previous version, the language was set to Russian.
  • Generated statistics reports are no longer overwritten when the number of reports reaches its limit (maximum of five). Previously, if there were five reports, calling the CreateNewWordstatReport method caused the oldest report to be deleted in order to create space for the new report. Now the method returns an error message in this situation. To free up space for a new report, use the DeleteWordstatReport method.

    The same approach is implemented for budget forecasts that are generated using the CreateNewForecast method. To delete them, use the DeleteForecastReport method.