UpdateUserRoles Service Operation - Customer Management

Updates the roles of the specified user.

Request Elements

The UpdateUserRolesRequest object defines the body and header elements of the service operation request. The elements must be in the same order as shown in the Request SOAP.

Request Body Elements

Element Description Data Type
CustomerId The identifier of the customer to which the user belongs. long
DeleteAccountIds An array of identifiers of the accounts to remove from the list of accounts that the user can manage.

For usage, see the Remarks section below.
long array
DeleteCustomerIds An array of identifiers of the customers to remove from the list of customers that the user can manage.

For usage, see the Remarks section below.
long array
DeleteRoleId The identifier of the role to which the values specified in the DeleteAccountIds or DeleteCustomerIds element applies, if set.

Possible values include the following:
16 - The user has the Advertiser Campaign Manager role.
33 - The user has the Aggregator role.
41 - The user has the Super Admin role.
100 - The user has the ClientViewer role.
203 - The user has the Standard role.

For more information, see User Roles and Available Service Operations.

Important: The list above provides examples of possible return values. Other values might be returned. Deprecated or internal roles can be included in the response.
int
NewAccountIds An array of identifiers of the accounts to restrict the user to. The user will be able to manage only these accounts.

If the user is currently restricted to a set of accounts, set this element to the new accounts that you want the user to also manage. For example, if the user currently manages accounts 123 and 456, and you want the user to also manage account 789, set this element to 789.

For usage, see the Remarks section below.
long array
NewCustomerIds An array of identifiers of the customers to restrict the user to. The user will be able to manage only these customers.

For usage, see the Remarks section below.
long array
NewRoleId The identifier of the role to which the values specified in the NewAccountIds or NewCustomerIds element applies to, if set.

Possible values include the following:
16 - The user has the Advertiser Campaign Manager role.
33 - The user has the Aggregator role.
41 - The user has the Super Admin role.
100 - The user has the ClientViewer role.
203 - The user has the Standard role.

For more information, see User Roles and Available Service Operations.

Important: The list above provides examples of possible return values. Other values might be returned. Deprecated or internal roles can be included in the response.
int
UserId The identifier of the user whose role you want to update. long

Request Header Elements

Element Description Data Type
AuthenticationToken The OAuth access token that represents a Microsoft Account user who has permissions to Bing Ads accounts. string
DeveloperToken The developer token used to access the Bing Ads API. string
Password The Bing Ads managed user's sign-in password. string
UserName The Bing Ads managed user's sign-in name. You must not set this element to a Microsoft account or email address. string

Important

The UserName and Password header elements are deprecated. In future versions of the API, Bing Ads will transition exclusively to Microsoft Account (email address) authentication. For more information, see Authentication with OAuth. UserName and Password are still required for Bing Ads managed credentials, but they are not applicable for Microsoft account authentication. To authenticate a Microsoft account, use the AuthenticationToken] header instead of UserName and Password.

Response Elements

The UpdateUserRolesResponse object defines the body and header elements of the service operation response. The elements are returned in the same order as shown in the Response SOAP.

Response Body Elements

Element Description Data Type
LastModifiedTime The date and time that the user roles were last updated. The value is in Coordinated Universal Time (UTC).

The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types.
dateTime

Response Header Elements

Element Description Data Type
TrackingId The identifier of the log entry that contains the details of the API call. string

Request SOAP

The following template shows the order of the body and header elements for the SOAP request.

<s:Envelope xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header xmlns="https://bingads.microsoft.com/Customer/v12">
    <Action mustUnderstand="1">UpdateUserRoles</Action>
    <ApplicationToken i:nil="false">ValueHere</ApplicationToken>
    <AuthenticationToken i:nil="false">ValueHere</AuthenticationToken>
    <DeveloperToken i:nil="false">ValueHere</DeveloperToken>
    <Password i:nil="false">ValueHere</Password>
    <UserName i:nil="false">ValueHere</UserName>
  </s:Header>
  <s:Body>
    <UpdateUserRolesRequest xmlns="https://bingads.microsoft.com/Customer/v12">
      <CustomerId>ValueHere</CustomerId>
      <UserId>ValueHere</UserId>
      <NewRoleId i:nil="false">ValueHere</NewRoleId>
      <NewAccountIds i:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <a1:long>ValueHere</a1:long>
      </NewAccountIds>
      <NewCustomerIds i:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <a1:long>ValueHere</a1:long>
      </NewCustomerIds>
      <DeleteRoleId i:nil="false">ValueHere</DeleteRoleId>
      <DeleteAccountIds i:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <a1:long>ValueHere</a1:long>
      </DeleteAccountIds>
      <DeleteCustomerIds i:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <a1:long>ValueHere</a1:long>
      </DeleteCustomerIds>
    </UpdateUserRolesRequest>
  </s:Body>
</s:Envelope>

Response SOAP

The following template shows the order of the body and header elements for the SOAP response.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header xmlns="https://bingads.microsoft.com/Customer/v12">
    <TrackingId d3p1:nil="false" xmlns:d3p1="http://www.w3.org/2001/XMLSchema-instance">ValueHere</TrackingId>
  </s:Header>
  <s:Body>
    <UpdateUserRolesResponse xmlns="https://bingads.microsoft.com/Customer/v12">
      <LastModifiedTime>ValueHere</LastModifiedTime>
    </UpdateUserRolesResponse>
  </s:Body>
</s:Envelope>

Code Syntax

The example syntax can be used with Bing Ads SDKs. See Bing Ads Code Examples for more examples.

public async Task<UpdateUserRolesResponse> UpdateUserRolesAsync(
    long customerId,
    long userId,
    int? newRoleId,
    IList<long> newAccountIds,
    IList<long> newCustomerIds,
    int? deleteRoleId,
    IList<long> deleteAccountIds,
    IList<long> deleteCustomerIds)
{
    var request = new UpdateUserRolesRequest
    {
        CustomerId = customerId,
        UserId = userId,
        NewRoleId = newRoleId,
        NewAccountIds = newAccountIds,
        NewCustomerIds = newCustomerIds,
        DeleteRoleId = deleteRoleId,
        DeleteAccountIds = deleteAccountIds,
        DeleteCustomerIds = deleteCustomerIds
    };

    return (await CustomerManagementService.CallAsync((s, r) => s.UpdateUserRolesAsync(r), request));
}
static UpdateUserRolesResponse updateUserRoles(
    java.lang.Long customerId,
    java.lang.Long userId,
    int newRoleId,
    ArrayOflong newAccountIds,
    ArrayOflong newCustomerIds,
    int deleteRoleId,
    ArrayOflong deleteAccountIds,
    ArrayOflong deleteCustomerIds) throws RemoteException, Exception
{
    UpdateUserRolesRequest request = new UpdateUserRolesRequest();

    request.setCustomerId(customerId);
    request.setUserId(userId);
    request.setNewRoleId(newRoleId);
    request.setNewAccountIds(newAccountIds);
    request.setNewCustomerIds(newCustomerIds);
    request.setDeleteRoleId(deleteRoleId);
    request.setDeleteAccountIds(deleteAccountIds);
    request.setDeleteCustomerIds(deleteCustomerIds);

    return CustomerManagementService.getService().updateUserRoles(request);
}
static function UpdateUserRoles(
    $customerId,
    $userId,
    $newRoleId,
    $newAccountIds,
    $newCustomerIds,
    $deleteRoleId,
    $deleteAccountIds,
    $deleteCustomerIds)
{

    $GLOBALS['Proxy'] = $GLOBALS['CustomerManagementProxy'];

    $request = new UpdateUserRolesRequest();

    $request->CustomerId = $customerId;
    $request->UserId = $userId;
    $request->NewRoleId = $newRoleId;
    $request->NewAccountIds = $newAccountIds;
    $request->NewCustomerIds = $newCustomerIds;
    $request->DeleteRoleId = $deleteRoleId;
    $request->DeleteAccountIds = $deleteAccountIds;
    $request->DeleteCustomerIds = $deleteCustomerIds;

    return $GLOBALS['CustomerManagementProxy']->GetService()->UpdateUserRoles($request);
}
response=customermanagement_service.UpdateUserRoles(
    CustomerId=CustomerId,
    UserId=UserId,
    NewRoleId=NewRoleId,
    NewAccountIds=NewAccountIds,
    NewCustomerIds=NewCustomerIds,
    DeleteRoleId=DeleteRoleId,
    DeleteAccountIds=DeleteAccountIds,
    DeleteCustomerIds=DeleteCustomerIds)

Remarks

As an example use case if an advertiser campaign manager is limited to managing accounts 123, 456, and 789, and you no longer want the user to manage 456, set the following elements accordingly:

  • Set the NewRoleId element to 16 (advertiser campaign manager role).

  • Set the NewAccountIds element to an array that contains 123 and 789.

  • Set the DeleteRoleId element to 16 (advertiser campaign manager role).

  • Set the DeleteAccountIds element to an array that contains 456.

If an advertiser campaign manager is limited to managing accounts 123 and 789, and you now want the user to manage all accounts, set the following elements accordingly:

  • Set the NewRoleId element to 16 (advertiser campaign manager role).

  • Set the NewAccountIds element to NULL.

  • Set the DeleteRoleId element to 16 (advertiser campaign manager role).

  • Set the DeleteAccountIds element to an array that contains 123, 456, and 789.

Users with account level roles can be restricted to specific accounts. Users with customer level roles can access all accounts within the user's customer, and their access cannot be restricted to specific accounts.

Note

When attempting to restrict customer level user roles to specific accounts the UpdateUserRoles operation will not fail, and the user will retain access for all accounts within the user's customer.

Requirements

Service: CustomerManagementService.svc v12
Namespace: https://bingads.microsoft.com/Customer/v12