Lesson 1. What is Yandex Direct API

In this lesson, you will learn:

  1. What is an API?
  2. Why do I need Yandex Direct API
  3. Where to start
  4. Objects in the web interface and API
  5. Task
  6. What an API request looks like
  7. Useful links
  8. Questions

In this lesson, we will explain why Yandex Direct needs an API, and introduce you to the basics of its operation.

Yandex Direct is a unified platform for placing contextual ads and banner ads. Yandex Direct serves your ads to the target audience of your business, interested in your products or services.

To work with Yandex Direct, all you need to do is to open a web interface, create an account, and place your ads. After that, you can manage your ads in Yandex Direct not only in the web interface, but also via the API.

Tip. If you haven't worked with Yandex Direct yet, we recommend that you take the How to place an ad in Yandex Direct training course first, and read Help. This way you can better understand the common principles of creating and running advertising campaigns and master our API course better.

What is an API?

API means Application Programming Interface. The API of a service provides a set of pre-built procedures, functions, and structures that developers can use to create their programs, applications, and scripts (hereinafter referred to as apps) to interact with the service.

In other words, the API is a constructor that provides a set of building blocks (functions and methods) and rules how to use them. You can build your own app from such building blocks.

When interacting with a service via its API, your app sends a request to the service and gets a response containing the data requested. The API lets you automate the workflow of operations that you perform in the web interface.

Why do I need Yandex Direct API

Using Yandex Direct API, you can manage the same ads as in the web interface. The API allows you to automate routine operations, accelerate their execution, and hence boost your account management efficiency. The API is a right choice if you wish to handle large amounts of data, stay independent of the browser interface, and prefer to fine-tune your ads.

You can create an app for your tasks as an independent developer, advertiser, or advertising agency. For example, you can write a script to update bids based on your custom algorithm via the API automatically. You can integrate your corporate information system with Yandex Direct: upload a large number of ads from your database to Yandex Direct, automatically update ad texts as your product price changes, and stop and resume ad serving depending on product availability in stock. You can upload daily statistics on advertising campaigns to your analytical or finance system.

Both connection to the Yandex Direct API and usage are free of charge.

Where to start

To complete the course, you need to create an account in Yandex Direct. If you do not have an account yet, then create it:

  1. Log in to Yandex with the username you are going to use as an app developer. If you don't have a Yandex username, get one.
  2. In Yandex Direct web interface (https://direct.yandex.com) click the Get started button.
  3. Enter an email address you currently use, select your country and currency. Click Start using the service.
  4. Create your first advertising campaign: we recommend you to select “Text & Image Ads” campaign type. Specify the campaign parameters and create your first ad. For now, it is sufficient to create one draft ad with a single keyword. You don't need to submit ads for review or deposit money for the campaign.
Note. Read more about creating an account in Yandex Direct in Help. We also recommend that you take the lesson on this in Yandex Direct course.

Now you have an account in Yandex Direct. Let's see what your ads look like in the web interface and in the API.

Objects in the web interface and API

A Yandex Direct ad campaign contains ad groups, each of which contains ads and keywords. Ads can include additional elements, such as images, sitelinks, and others.

Links between objects in the API is shown in the diagram:

  • Campaign — an advertising campaign, AdGroup — an ad group, Ad — an ad.
  • Ad extensions: AdImage — an image, VCard — a virtual business card, SitelinksSet — a set of sitelinks, AdExtension — a callout.
  • Ad group targeting criteria: Keyword — keyword (and others, depending on the campaign type). You can set a bid for a targeting criteria — KeywordBid.


Go through the settings of your advertising campaign in Yandex Direct. Create new ads with different parameters. If you do not want to launch a real campaign, do not submit your ad groups for moderation to keep your ads in the “Draft” status.

Execute task

What an API request looks like

You can use API requests to retrieve the ads you see in the web interface. You can also make changes using API requests, and see the result immediately reflected in the web interface. The API works with each object individually: different API methods allow you to create an ad, update a vCard, get statistics, and more.

Here is the API request allowing you to retrieve the list of the user's ad campaigns. The request is sent using the HTTPS protocol's POST method.

In the next lessons, you will step through all the initial steps of working with the API:

  • You will learn how to get access to the API: register your application with Yandex OAuth service, apply for access, and get an OAuth token.
  • Also, you will learn to set up Sandbox: a testing debug environment for your app.
  • You will learn to write API requests: you will get familiar with services and methods provided by the API and learn request structure details.
  • Finally, you will get some advice on how to proceed from Sandbox practice to handling real-life ads of real users.

We strongly recommend that you study the lessons in their native order. Previous lesson information (and results of actions you performed there) are prerequisite for each next lesson.

Good luck!


  1. To work with the API, you need an account in Yandex Direct. What should you do to create an account in Yandex Direct?
  2. What can you do using Yandex Direct API?
  3. If you change an ad campaign via the Yandex Direct API, where can you see the changes?