Documentation

update

Changes the parameters of advertisers who are agency clients, and user settings for chief representatives of advertisers.
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.

Restrictions

Maximum of 1000 clients per method call.

Request

Note. The ClientInfo, Notification, and Phone parameters belong to the advertiser's chief representative (see Roles and access of Yandex.Direct users). The ClientId, Grants, and Settings parameters belong to the advertiser.

Request structure in JSON format:

{
  "method": "update",
  "params": { 
    "Clients
[no-highlight[

The parameters (for agency client advertisers) and user settings (for chief representatives of advertisers) that you need to change.

Required

Yes

]no-highlight]
": [{ /* AgencyClientUpdateItem */ "ClientId
[no-highlight[

Advertiser ID.

Required

Yes

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

Client name (maximum of 255 characters).

Required

No

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

The advertiser‘s permissions for campaign management.

Required

No

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

Name of the permission:

For the IMPORT_XLS permission, you can only set the YES value if the EDIT_CAMPAIGNS permission is also set to YES. Otherwise, an error is returned.

For the EDIT_CAMPAIGNS permission, you can only set the NO value if the IMPORT_XLS permission is set to NO. Otherwise, an error is returned.

Required

Yes

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

Whether the client has this permission.

Required

Yes

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

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

Required

No

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

Language for notifications.

Required

No

]no-highlight]
": ( "RU" | "UK" | "EN" | "TR" ), "Email
[no-highlight[

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

Required

No

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

Types of notifications to send by email.

Required

No

]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.

Required

Yes

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

Whether to send this type of notification.

Required

Yes

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

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

Required

No

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

Advertiser settings that only allow YES or NO values.

Required

No

]no-highlight]
": [{ /* ClientSettingUpdateItem */ "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).

Required

Yes

]no-highlight]
": ( "DISPLAY_STORE_RATING" | "CORRECT_TYPOS_AUTOMATICALLY" ), "Value
[no-highlight[

Setting value.

Required

Yes

]no-highlight]
": ( "YES" | "NO" ) }, ... ] }] /* required */ } }
Parameter Type Description Required
params structure (for JSON) / UpdateRequest structure (for SOAP)
Clients array of AgencyClientUpdateItemThe parameters (for agency client advertisers) and user settings (for chief representatives of advertisers) that you need to change.Yes
AgencyClientUpdateItem structure
ClientId longAdvertiser ID.Yes
ClientInfo stringClient name (maximum of 255 characters).No
Grants array of GrantItemThe advertiser's permissions for campaign management.No
Notification NotificationUpdate

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

No
Phone string

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

No
Settings array of ClientSettingUpdateItemAdvertiser settings that only allow YES or NO values.No
GrantItem structure
Privilege PrivilegeEnum

Name of the permission:

For the IMPORT_XLS permission, you can only set the YES value if the EDIT_CAMPAIGNS permission is also set to YES. Otherwise, an error is returned.

For the EDIT_CAMPAIGNS permission, you can only set the NO value if the IMPORT_XLS permission is set to NO. Otherwise, an error is returned.

Yes
Value YesNoEnumWhether the client has this permission.Yes
NotificationUpdate structure
Lang LangEnumLanguage for notifications.No
Email string

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

No
EmailSubscriptions array of EmailSubscriptionItemTypes of notifications to send by email.No
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.

Yes
Value YesNoEnumWhether to send this type of notification.Yes
ClientSettingUpdateItem structure
Option ClientSettingUpdateEnum

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).

Yes
Value YesNoEnumSetting value.Yes

Response

Response structure in JSON format:

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

The result of changing parameters for agency client advertisers and user settings for chief representatives of advertisers.

]no-highlight]
": [{ /* ClientsActionResult */ "ClientId
[no-highlight[

Advertiser ID. Returned if there are no errors; see the section Operations on object arrays.

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

Warnings that occurred during the operation.

]no-highlight]
": [{ /* ExceptionNotification */ "Code": (int), /* required */ "Message": (string), /* required */ "Details": (string) }, ... ], "Errors
[no-highlight[

Errors that occurred during the operation.

]no-highlight]
": [{ /* ExceptionNotification */ "Code": (int), /* required */ "Message": (string), /* required */ "Details": (string) }, ... ] }, ... ] /* required */ } }
Parameter Type Description
result structure (for JSON) / UpdateResponse structure (for SOAP)
UpdateResults array of ClientsActionResultThe result of changing parameters for agency client advertisers and user settings for chief representatives of advertisers.
ClientsActionResult structure
ClientId longAdvertiser ID. Returned if there are no errors; see the section Operations on object arrays.
Warnings array of ExceptionNotification

Warnings that occurred during the operation.

Errors array of ExceptionNotification

Errors that occurred during the operation.