Introduction

You can use the API for the Yandex.Audience service to:

  • Manage segments.
  • Manage delegates.
  • Manage accounts and access rights.

To use the Yandex.Audience API, you must get authorization using an OAuth access token. You must send the access token in every API request.

This guide provides examples of accessing the service to demonstrate what you can do with the API. The methods in examples use sample data that is publicly available to all users.

Structure of the API

The API has the following sections:

  • Managing segments – For getting, creating, and deleting segments. To create segments, you can use: your own data; segments from Yandex.Metrica; intersections, unions, or exclusions of existing segments.
  • Managing permissions – For getting information about current permissions, as well as creating and deleting permissions to work with segments.
  • Managing accounts – For getting a list of accounts that the user represents.
  • Managing delegates – For creating, changing, and removing account delegates.
  • Managing pixels – For creating, changing, and removing pixels.

Versioning

All sections of the Yandex.Audience API support versioning. Each version has its own identifier (v1, v2, and so on). When a new version of the API is released, the previous version continues working for backward compatibility.

If you are just starting to use the API, use the latest version. If you are already using previous versions of the API, we recommend that you gradually migrate to the latest version, since support for older versions will eventually be discontinued.

When forming API requests, always specify the version you want to work with.

https://api-audience.yandex.com/v1/management/...
https://api-audience.yandex.com/v2/management/...

Resources

The Yandex.Audience API is implemented as a RESTful HTTP interface.

Everything that can be controlled via the API is represented by resources: a segment, the list of segments, access to a segment, and so on.

In other words, a resource is an integral part of the system that you can access:
  • Read the content and current state of the resource (GET).
  • Change the content and state and write it to the resource (PUT).
  • Delete the resource (DELETE).
  • Perform special actions, such as adding new segments (POST).

Each resource has its own unique URL. All actions are performed by sending the corresponding methods of the HTTP protocol to resource URLs.

For example, to get the list of segments, you need to make a GET request to the URL of the list of segments. And to create a new segment, you need to make a POST request with the segment body to the URL of the segment.