What's new in version 5

Addresses

Version 5 doesn't have universal addresses that are the same for all requests. The API version 5 consists of separate services, and each service has its own address.

The services are designed to work with specific classes of objects. For example, the Campaigns service is used for managing campaigns. It has the following addresses:

  • For JSON requests:

    https://api.direct.yandex.com/json/v5/campaigns
  • For SOAP requests:

    https://api.direct.yandex.com/v5/campaigns
  • WSDL description:

    https://api.direct.yandex.com/v5/campaigns?wsdl

The addresses and methods for each of the services are listed in the API reference guide.

Request for API access

To get access to version 5 of the API, you must submit a request and wait for approval. This is required for all applications, including those that started using the API before application registration was required and that continued using versions 4 and Live 4 without submitting the request for access.

Authorization

Similar to older versions of the API, version 5 requests must specify an OAuth access token that authorizes access to a specific user's data. The difference is that the access token must be passed in the HTTP Authorization header, not in the request body. For example:

Authorization: Bearer 0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f
Attention. Bearer is an OAuth constant. It must always be specified.

Working with agency clients

In version 5, an agency can only work with the data of a single advertiser – a client of the agency – in each request. Pass the advertiser's username in the HTTP Client-Login header.

For example:

Client-Login: agrom

If you need to obtain or change data for multiple advertisers, you must make a separate request for each advertiser.

Structure of objects

Sitelinks, vCards, callouts, and keywords are independent objects in version 5 of the API. There are separate services provided for working with them. This simplifies data management. For example, to change the phone number in a vCard, you don't need to edit all the ads that use it. Version 5 also provides full support for ad groups.

Working with data

Version 5 uses a completely different logic for working with objects (creating, editing, getting, and so on).

In a request to create or change multiple objects, each object is processed separately. For example, if an application sends a request to create 100 ads and one of them has invalid parameter values, the other 99 ads are still created successfully.

Unlike previous versions, you don't need to pass all the object parameters when editing an object. You can just specify the parameters that you need to change the values for. The other parameters won't be changed. The Yandex Direct server will still check the entire object and return an error if the object has become invalid with the new parameter values.

A similar rule applies to getting data – the server only returns the object parameters requested by the application, instead of returning all the parameters. Requesting only the necessary parameters can significantly speed up data exchange.

Currency

In version 5, all the methods accept and return monetary values in the advertiser's currency. The Currency parameter, which was introduced in the Live 4 version for backward compatibility, is not used.

Attention. All monetary values (bids, strategy parameters, and others) are passed via the API as integers: the amount in the currency, multiplied by 1,000,000. For example, for a bid of 2.5 rubles, you would pass the integer 2,500,000.

Technical limitations

In versions 4 and Live 4 of the API, there was a maximum of five simultaneous requests per user. In version 5, up to five simultaneous requests are allowed per advertiser. It doesn't matter which of the advertiser's representatives or agencies is making the request.

Version 5 doesn't apply any restrictions to the number of calls of individual methods.

Points

The point system in version 5 is similar to version 4 and Live 4, but there are a few differences:

  • Points are granted in regular intervals throughout the day, rather than once a day.

  • Points are deducted both for errors and for successful calls.

  • An agency can spend its own points on operations with data for a client advertiser.

  • The response to every request returns the available points remaining. You don't need to call a separate method to check the point balance.

Request ID

Version 5 of the API assigns each request a unique ID and returns it in the request response. Please indicate this ID when contacting the Support service.