Documentation

get

Returns a list of advertisers who are agency clients, their parameters, and settings for each advertiser's chief representative.
Note. For requests to the AgencyClients service:
  • In the Authorization header, specify the access token you received for the agency representative.
  • Don't specify the Client-Login header.

Request

Request structure in JSON format:

{
  "method": "get",
  "params": { 
    "SelectionCriteria
[no-highlight[

Client selection criteria.

To get parameters for all of the agency‘s clients, specify an empty SelectionCriteria structure.

Required

Yes

]no-highlight]
": { /* AgencyClientsSelectionCriteria */ "Logins
[no-highlight[

Selects clients with the specified representative usernames. Maximum of 10,000 items in the array.

Required

No

]no-highlight]
": [(string), ... ], "Archived
[no-highlight[

Selects clients based on whether they are archived: YES – archived clients; NO – active clients.

Required

No

]no-highlight]
": ( "YES" | "NO" ) }, /* required */ "FieldNames
[no-highlight[

The names of parameters to get.

Required

Yes

]no-highlight]
": [( "AccountQuality" | "Archived" | "ClientId" | "ClientInfo" | "CountryId" | "CreatedAt" | "Currency" | "Grants" | "Login" | "Notification" | "OverdraftSumAvailable" | "Phone" | "Representatives" | "Restrictions" | "Settings" | "Type" | "VatRate" )], /* required */ "Page
[no-highlight[

Structure that defines the page for paginated selection of data.

Required

No

]no-highlight]
": { /* LimitOffset */ "Limit": (long), "Offset": (long) } } }
Parameter Type Description Required
params structure (for JSON) / GetRequest (for SOAP)
SelectionCriteria AgencyClientsSelectionCriteria

Client selection criteria.

To get parameters for all of the agency's clients, specify an empty SelectionCriteria structure.

Yes
FieldNames array of AgencyClientFieldEnum

The names of parameters to get.

Yes
Page LimitOffset

Structure that defines the page for paginated selection of data.

No
AgencyClientsSelectionCriteria structure
Logins array of stringSelects clients with the specified representative usernames. Maximum of 10,000 items in the array.No
Archived YesNoEnumSelects clients based on whether they are archived: YES – archived clients; NO – active clients.No

Response

Note. 
  • The Login, ClientInfo, CreatedAt, Notification, and Phone parameters belong to the advertiser's chief representative (see Roles and access of Yandex.Direct users). The other parameters relate to the advertiser.

  • If the Logins parameter in the request specifies the username of a representative other than the chief representative, the response contains the username of the advertiser's chief representative instead of the username from the request.

  • If the Logins parameter in the request specifies multiple representative usernames for the same advertiser, this advertiser (and chief representative) is only listed once in the response.

  • All the advertiser's representatives are listed in the Representatives parameter.

Response structure in JSON format:

{
  "result": { 
    "Clients
[no-highlight[

Advertisers – agency clients and their chief representatives.

]no-highlight]
": [{ /* ClientGetItem */ "AccountQuality
[no-highlight[

Indicates the quality of the account (see the section Account quality index in the Help for Yandex.Direct).

]no-highlight]
": (decimal), /* nillable */ "Archived
[no-highlight[

Indicates that the advertiser is archived (inactive).

]no-highlight]
": ( "YES" | "NO" ), "ClientId
[no-highlight[

Advertiser ID.

]no-highlight]
": (long), "ClientInfo
[no-highlight[

Client name (maximum of 255 characters).

]no-highlight]
": (string), "CountryId
[no-highlight[

ID of the advertiser‘s country from the reference list of regions.

To get the list of regions, use the Dictionaries.get method.

]no-highlight]
": (int), "CreatedAt
[no-highlight[

Date the user was registered in Yandex.Direct, in the format YYYY-MM-DD.

]no-highlight]
": (string), "Currency
[no-highlight[

The advertiser‘s currency.

To get the list of currencies, use the Dictionaries.get method.

]no-highlight]
": ( "RUB" | "BYN" | "CHF" | "EUR" | "KZT" | "TRY" | "UAH" | "USD" | "YND_FIXED" ), "Grants
[no-highlight[

The advertiser‘s permissions for campaign management.

]no-highlight]
": [{ /* GrantGetItem */ "Privilege
[no-highlight[

Name of the permission:

]no-highlight]
": ( "EDIT_CAMPAIGNS" | "IMPORT_XLS" | "TRANSFER_MONEY" ), /* required */ "Value
[no-highlight[

Whether the client has this permission.

]no-highlight]
": ( "YES" | "NO" ), /* required */ "Agency
[no-highlight[

The name of the advertising agency, if the permission is granted by an agency.

]no-highlight]
": (string) }, ... ], "Login
[no-highlight[

Username of the Yandex.Direct user.

]no-highlight]
": (string), "Notification
[no-highlight[

The Yandex.Direct user‘s settings for SMS and email notifications.

]no-highlight]
": { /* NotificationGet */ "Lang
[no-highlight[

Language for notifications.

]no-highlight]
": ( "RU" | "UK" | "EN" | "TR" ), /* required */ "SmsPhoneNumber
[no-highlight[

The phone number for sending SMS notifications from the user‘s Yandex profile (see Mobile numbers in the Help for Yandex.Passport).

]no-highlight]
": (string), /* required */ "Email
[no-highlight[

The email address for sending notifications related to the account (no more than 255 characters).

]no-highlight]
": (string), /* required */ "EmailSubscriptions
[no-highlight[

Types of notifications to send by email.

]no-highlight]
": [{ /* EmailSubscriptionItem */ "Option
[no-highlight[

Type of notification:

  • RECEIVE_RECOMMENDATIONS — Yandex.Direct news and recommendations.

  • TRACK_MANAGED_CAMPAIGNS — Notifications for campaigns that have a personal manager.

  • TRACK_POSITION_CHANGES — Warnings about ads getting moved lower than the bid originally provided for.

]no-highlight]
": ( "RECEIVE_RECOMMENDATIONS" | "TRACK_MANAGED_CAMPAIGNS" | "TRACK_POSITION_CHANGES" ), /* required */ "Value
[no-highlight[

Whether to send this type of notification.

]no-highlight]
": ( "YES" | "NO" ) /* required */ }, ... ] /* required */ }, "OverdraftSumAvailable
[no-highlight[

The overdraft limit currently available to the advertiser (see Payment deferral in the Help for Yandex.Direct).

Returned as an integer that represents the overdraft limit in the advertiser‘s currency, multiplied by 1,000,000.

]no-highlight]
": (long), "Phone
[no-highlight[

Phone number of the Yandex.Direct user (255 characters maximum).

]no-highlight]
": (string), "Representatives
[no-highlight[

Representatives of the advertiser.

See Roles and access of Yandex.Direct users.

]no-highlight]
": [{ /* Representative */ "Login
[no-highlight[

Username.

]no-highlight]
": (string), /* required */ "Email
[no-highlight[

Email address to send notifications to.

]no-highlight]
": (string), /* required */ "Role
[no-highlight[

The user‘s role:

  • CHIEF — Chief representative of the advertiser.

  • DELEGATE — Other representative of the advertiser.

  • UNKNOWN — This role isn‘t supported in this version of the API.

See Roles and access of Yandex.Direct users.

]no-highlight]
": ( "CHIEF" | "DELEGATE" | "UNKNOWN" ) /* required */ }, ... ], "Restrictions
[no-highlight[

Limits on the number of objects for an advertiser.

]no-highlight]
": [{ /* ClientRestrictionItem */ "Element
[no-highlight[

Name of the restriction:

  • CAMPAIGNS_TOTAL_PER_CLIENT — The maximum number of campaigns per advertiser.

  • CAMPAIGNS_UNARCHIVED_PER_CLIENT — The maximum number of unarchived campaigns per advertiser.

  • ADGROUPS_TOTAL_PER_CAMPAIGN — The maximum number of groups per campaign.

  • ADS_TOTAL_PER_ADGROUP — The maximum number of ads per group.

  • KEYWORDS_TOTAL_PER_ADGROUP — The maximum number of keywords per group.

  • AD_EXTENSIONS_TOTAL — The maximum number of ad extensions per advertiser.

  • STAT_REPORTS_TOTAL_IN_QUEUE — The maximum number of statistical reports being generated simultaneously.

  • FORECAST_REPORTS_TOTAL_IN_QUEUE — The maximum number of budget forecast reports stored on the server.

  • WORDSTAT_REPORTS_TOTAL_IN_QUEUE — The maximum number of search query statistics reports stored on the server.

]no-highlight]
": ( "CAMPAIGNS_TOTAL_PER_CLIENT" | "CAMPAIGNS_UNARCHIVED_PER_CLIENT" | "ADGROUPS_TOTAL_PER_CAMPAIGN" | "ADS_TOTAL_PER_ADGROUP" | "KEYWORDS_TOTAL_PER_ADGROUP" | "AD_EXTENSIONS_TOTAL" | "STAT_REPORTS_TOTAL_IN_QUEUE" | "FORECAST_REPORTS_TOTAL_IN_QUEUE" | "WORDSTAT_REPORTS_TOTAL_IN_QUEUE" ), /* required */ "Value
[no-highlight[

The limit value.

]no-highlight]
": (int) /* required */ }, ... ], "Settings
[no-highlight[

Advertiser settings that only allow YES or NO values.

]no-highlight]
": [{ /* ClientSettingGetItem */ "Option
[no-highlight[

Setting name:

  • CORRECT_TYPOS_AUTOMATICALLY — Automatically fix errors and typos.

  • DISPLAY_STORE_RATING — Add data from external sources to the ad (see Data from third parties in the Help for Yandex.Direct).

  • SHARED_ACCOUNT_ENABLED — The shared account is enabled.

]no-highlight]
": ( "CORRECT_TYPOS_AUTOMATICALLY" | "DISPLAY_STORE_RATING" | "SHARED_ACCOUNT_ENABLED" ), /* required */ "Value
[no-highlight[

Setting value.

]no-highlight]
": ( "YES" | "NO" ) /* required */ }, ... ], "Type
[no-highlight[

Client type: SUBCLIENT.

]no-highlight]
": (string), "VatRate
[no-highlight[

The agency‘s VAT rate.

]no-highlight]
": (decimal) /* nillable */ }, ... ], "LimitedBy
[no-highlight[

Sequential number of the last object returned. It is included if there was a limit on the number of objects in the response. See the section Paginated selection.

]no-highlight]
": (long) } }
Parameter Type Description
result structure (for JSON) / GetResponse (for SOAP)
Clients array of ClientGetItemAdvertisers – agency clients and their chief representatives.
LimitedBy longSequential number of the last object returned. It is included if there was a limit on the number of objects in the response. See the section Paginated selection.
ClientGetItem structure
AccountQuality decimal, nillableIndicates the quality of the account (see the section Account quality index in the Help for Yandex.Direct).
Archived YesNoEnumIndicates that the advertiser is archived (inactive).
ClientId longAdvertiser ID.
ClientInfo string

Client name (maximum of 255 characters).

CountryId int

ID of the advertiser's country from the reference list of regions.

To get the list of regions, use the Dictionaries
[no-highlight[

This service is for getting reference data: regions, time zones, currency exchange rates, metro stations, restrictions on parameter values, and other information.

More Dictionaries

]no-highlight]
.get
[no-highlight[

Returns reference data: regions, time zones, currency exchange rates, metro stations, restrictions on parameter values, ad exchanges (SSPs), and other information.

More get

]no-highlight]
method.
CreatedAt string

Date the user was registered in Yandex.Direct, in the format YYYY-MM-DD.

Currency CurrencyEnum

The advertiser's currency.

To get the list of currencies, use the Dictionaries
[no-highlight[

This service is for getting reference data: regions, time zones, currency exchange rates, metro stations, restrictions on parameter values, and other information.

More Dictionaries

]no-highlight]
.get
[no-highlight[

Returns reference data: regions, time zones, currency exchange rates, metro stations, restrictions on parameter values, ad exchanges (SSPs), and other information.

More get

]no-highlight]
method.
Grants array of GrantGetItemThe advertiser's permissions for campaign management.
Login string

Username of the Yandex.Direct user.

Notification NotificationGet

The Yandex.Direct user's settings for SMS and email notifications.

OverdraftSumAvailable long

The overdraft limit currently available to the advertiser (see Payment deferral in the Help for Yandex.Direct).

Returned as an integer that represents the overdraft limit in the advertiser's currency, multiplied by 1,000,000.

Phone string

Phone number of the Yandex.Direct user (255 characters maximum).

Representatives array of Representative

Representatives of the advertiser.

See Roles and access of Yandex.Direct users.

Restrictions array of ClientRestrictionItemLimits on the number of objects for an advertiser.
Settings array of ClientSettingGetItemAdvertiser settings that only allow YES or NO values.
Type string

Client type: SUBCLIENT.

VatRate decimal, nillableThe agency's VAT rate.
GrantGetItem structure
Privilege PrivilegeEnum

Name of the permission:

Value YesNoEnumWhether the client has this permission.
Agency stringThe name of the advertising agency, if the permission is granted by an agency.
NotificationGet structure
Lang LangEnumLanguage for notifications.
SmsPhoneNumber stringThe phone number for sending SMS notifications from the user's Yandex profile (see Mobile numbers in the Help for Yandex.Passport).
Email string

The email address for sending notifications related to the account (no more than 255 characters).

EmailSubscriptions array of EmailSubscriptionItemTypes of notifications to send by email.
EmailSubscriptionItem structure
Option EmailSubscriptionEnum

Type of notification:

  • RECEIVE_RECOMMENDATIONS — Yandex.Direct news and recommendations.

  • TRACK_MANAGED_CAMPAIGNS — Notifications for campaigns that have a personal manager.

  • TRACK_POSITION_CHANGES — Warnings about ads getting moved lower than the bid originally provided for.

Value YesNoEnumWhether to send this type of notification.
Representative structure
Login stringUsername.
Email stringEmail address to send notifications to.
Role RepresentativeRoleEnum

The user's role:

  • CHIEF — Chief representative of the advertiser.

  • DELEGATE — Other representative of the advertiser.

  • UNKNOWN — This role isn't supported in this version of the API.

See Roles and access of Yandex.Direct users.

ClientRestrictionItem structure
Element ClientRestrictionEnum

Name of the restriction:

  • CAMPAIGNS_TOTAL_PER_CLIENT — The maximum number of campaigns per advertiser.

  • CAMPAIGNS_UNARCHIVED_PER_CLIENT — The maximum number of unarchived campaigns per advertiser.

  • ADGROUPS_TOTAL_PER_CAMPAIGN — The maximum number of groups per campaign.

  • ADS_TOTAL_PER_ADGROUP — The maximum number of ads per group.

  • KEYWORDS_TOTAL_PER_ADGROUP — The maximum number of keywords per group.

  • AD_EXTENSIONS_TOTAL — The maximum number of ad extensions per advertiser.

  • STAT_REPORTS_TOTAL_IN_QUEUE — The maximum number of statistical reports being generated simultaneously.

  • FORECAST_REPORTS_TOTAL_IN_QUEUE — The maximum number of budget forecast reports stored on the server.

  • WORDSTAT_REPORTS_TOTAL_IN_QUEUE — The maximum number of search query statistics reports stored on the server.

Value intThe limit value.
ClientSettingGetItem structure
Option ClientSettingGetEnum

Setting name:

  • CORRECT_TYPOS_AUTOMATICALLY — Automatically fix errors and typos.

  • DISPLAY_STORE_RATING — Add data from external sources to the ad (see Data from third parties in the Help for Yandex.Direct).

  • SHARED_ACCOUNT_ENABLED — The shared account is enabled.

Value YesNoEnumSetting value.