Edit

Share via

Account Hierarchy and User Permissions

  • Article

Microsoft Advertising users can use the same login credentials to access multiple accounts, potentially with different permissions on each account. An agency can setup a hierarchy of accounts to manage all users and accounts from one parent account, use one central wallet to pay for everything, and share campaign resources such as Universal Event Tracking (UET) tags and remarketing lists across customers.

Note

In the context of hierarchies a Customer is also known as a "Manager account". An AdvertiserAccount is referred to as an "Account" or "Advertiser account".

See Entity Limits for more information about the campaign hierarchy within an account.

User Roles and Permissions

Your application might only need to support one Super Admin user on a known account. Even with such a relatively simple permission structure you'll want to understand the actions available for each user role, how users are provisioned on an account, how you can discover their current access rights, and how you can act on behalf of an authenticated Microsoft Advertising user with the Bing Ads API.

User Roles

The user role granted by a customer's Super Admin or the Microsoft Advertising system administrator determines service availability. For example a user with the Advertiser Campaign Manager role can add and update campaigns, but cannot create or update users. Unless otherwise noted in the reference content per service operation, the following table describes at a high level the service restrictions per user role.

Note

Only Super Admin and Standard users can be set as the primary contact for an account. For more details about user roles see the How do I give someone access to my Microsoft Advertising account? help topic.

User Role Available Services
Advertiser Campaign Manager This role has permissions to view selected accounts and add, edit, or delete campaigns within the selected accounts. The Advertiser Campaign Manager can view payment methods, but cannot manage any billing and payment tasks.

Read operations for all services are available.

Write operations with the Customer Management service are generally not available. One exception is that the Advertiser Campaign Manager can update the AutoTagType element of an AdvertiserAccount using the UpdateAccount operation.
Aggregator Read and write operations for all services are available, except DeleteCustomer.
Standard user This role has permissions to manage campaigns and perform some billing activities on selected accounts. This role cannot add, edit, or delete payment methods; add or delete accounts. Standard users can link and unlink advertiser accounts, but cannot manage customer to customer level client links.

Standard users can manage some users in the accounts they have access to. A Standard user can invite or delete other Standard users, Advertiser Campaign Managers, and Viewers, and view information about all users in the context of the current customer. However, Standard users cannot invite or delete a Super Admin, nor can they edit a Super Admin's role.

Standard users in the customer that owns an unshared audience or UET tag can update their properties (other than scope) such as description and name. While the audience or UET tag is shared, a Standard user cannot update these properties. For more details, see the Share Audiences and UET Tags technical guide.

Read operations for all services are available.

Write operations with the Customer Billing service and Customer Management service are generally not available. Exceptions of operations available to a Standard user are AddInsertionOrder, UpdateInsertionOrder, and UpdateAccount.
Super Admin This role has full permissions for all accounts. A Super Admin can manage everything related to billing and payments, account details, and other users (including other Super Admins). The Super Admin can specify which accounts other users have access to. When signing up as a new customer, the first user is the Super Admin.

A Super Admin user in the customer that owns the audience or UET tag can update the customer account sharing scope of an audience or UET tag. Super Admin users in parent customers of the hierarchy can also update the scope. Other audience or UET tag properties (other than scope) such as description and name can only be updated by a Super Admin user in the customer that owns the audience or UET tag. Super Admin users in parent customers of the hierarchy cannot update these details. For more details, see the Share Audiences and UET Tags technical guide.

Read and write operations for all services are available, except DeleteCustomer
Viewer This role has read-only permissions.

Read operations for all services are available.

Super Admin permissions on linked customers are restricted if the link permission (CustomerLinkPermission) is "Standard". Their permissions are not restricted if the link permission is "Administrative". They also retain full Super Admin permissions on customers they can directly access e.g., where they signed up.

Customer Link Permission

Please also note that taken individually, a user has the same role on the CustomerId, AccountIds, and LinkedAccountIds for a given CustomerRole; however, if a user has multiple customer roles then taken as a whole the effective permissions depend on the full set of CustomerRole objects returned by GetUser. Several examples are provided in Get User Roles.

Assign User Roles

When signing up for a new account in the Microsoft Advertising web application, you'll be granted the Super Admin user role. A Super Admin can create new users with the Advertiser Campaign Manager, Super Admin, Standard, or Viewer role. The Aggregator role is provisioned by special request through the System Administrator. For more information, see Aggregator Hierarchy and contact your account manager.

Technically new users cannot be created programmatically; however, you can use the SendUserInvitation operation to invite people to sign up under an existing Microsoft Advertising account. When you invite someone to an account or set of accounts, you will also set the user role. Microsoft Advertising generates an email invitation that is sent to the invitee. By clicking on the emailed link and completing the Microsoft Advertising sign up workflow, they are accepting the invitation to manage accounts with the user role that you provisioned in the SendUserInvitation request.

Note

A person can use the same login credentials when signing up for new accounts and accepting invitations to existing accounts. In either case when the same credentials are used to complete the sign up workflow, the person is considered to have Multi-User Credentials. From the perspective of each Super Admin managing users in their customer scope, the user's role, account access, and contact information are unique. Any permissions the user has in the context of another customer is not taken into account when acting within the scope of the current customer.

A Super Admin has the option to modify their users' access to different accounts and potentially modify the user role e.g., from Viewer to Standard user. To update a user's role, call the UpdateUserRoles operation.

Get User Roles

To get a list of the users who can access one or more accounts of a customer, call the GetUsersInfo operation. The operation returns an array of objects that contains the log in email address and identifier of each user. Then you can get the details of each user in the list, such as their role and account permissions in Microsoft Advertising, call the GetUser operation. When calling GetUser if you leave the UserId element nil, the response will include details for the current authenticated user as specified by the request header credentials.

Here is an example CustomerRoles element returned by the GetUser operation.

<CustomerRoles xmlns:e1335="https://bingads.microsoft.com/Customer/v13/Entities" d4p1:nil="false" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
  <e1335:CustomerRole>
    <e1335:RoleId>ValueHere</e1335:RoleId>
    <e1335:CustomerId>ValueHere</e1335:CustomerId>
    <e1335:AccountIds d4p1:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
      <a1:long>ValueHere</a1:long>
    </e1335:AccountIds>
    <e1335:LinkedAccountIds d4p1:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
      <a1:long>ValueHere</a1:long>
    </e1335:LinkedAccountIds>
    <e1335:CustomerLinkPermission d4p1:nil="false">ValueHere</e1335:CustomerLinkPermission>
  </e1335:CustomerRole>
</CustomerRoles>

Each CustomerRole represents the permissions that a person has when accessing the corresponding account or set of accounts.

Taken individually, a user has the same role on the CustomerId, AccountIds, and LinkedAccountIds for a given CustomerRole; however, if a user has multiple customer roles then taken as a whole the effective permissions depend on the full set of CustomerRole objects returned by GetUser. Several examples are provided below.

Roles Example for New User

If you just signed up for the first time with Microsoft Advertising and created a new account, the GetUser operation will return one CustomerRole object.

  • The RoleId is 41 because the first user of a new account has the Super Admin user role.
  • The CustomerId is the customer identifier provisioned when you signed up.
  • The AccountIds element is empty because a Super Admin can always access all advertiser accounts in the customer with the CustomerId identifier.
  • The LinkedAccountIds element is empty because you have not yet linked to any client advertiser accounts.
  • The CustomerLinkPermission is empty because you can access advertiser accounts directly via the assigned CustomerId.
<CustomerRoles xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
	<a:CustomerRole>
	   <a:RoleId>41</a:RoleId>
	   <a:CustomerId>999</a:CustomerId>
	   <a:AccountIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
	   <a:LinkedAccountIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
	   <a:CustomerLinkPermission i:nil="true"/>
	</a:CustomerRole>
 </CustomerRoles>

Roles Example for Multi-User Credentials

If you accept an invitation to be a user in another customer with your existing login credentials from the previous example, you have Multi-User Credentials in Microsoft Advertising. Your login credentials directly associated with each of the customer identifiers and the GetUser operation will return two CustomerRole objects. In this example the elements within each CustomerRole are equivalent except for the CustomerId. The RoleId depends on the role assigned when the Super Admin of Manager Account L1 (customer ID 111) sent you the invitation.

<CustomerRoles xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <a:CustomerRole>
      <a:RoleId>41</a:RoleId>
      <a:CustomerId>999</a:CustomerId>
      <a:AccountIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
      <a:LinkedAccountIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
      <a:CustomerLinkPermission i:nil="true"/>
  </a:CustomerRole>
  <a:CustomerRole>
      <a:RoleId>41</a:RoleId>
      <a:CustomerId>111</a:CustomerId>
      <a:AccountIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
      <a:LinkedAccountIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
      <a:CustomerLinkPermission i:nil="true"/>
  </a:CustomerRole>
</CustomerRoles>

Roles Example for Account Hierarchy

Building upon the Roles Example for Multi-User Credentials (although Multi-User Credentials are not required to build a hierarchy), let's say for example, one of the Super Admin users in Manager Account L1 (customer ID 111) (whether you or another Super Admin) setup an Agency Hierachy under Manager Account L1 (customer ID 111) with both customer and advertiser account client links:

  • Manager Account L1 (customer ID 111) links to Manager Account L2 (customer ID 222) with an Administrative link.
  • Manager Account L2 (customer ID 222) links to Manager Account L3 (customer ID 333) with a Standard link.
  • Manager Account L3 (customer ID 333) links to Ad Account 4A (account ID 444111) with an account level link. Ad Account 4A (account ID 444111) is directly under Manager Account L4 (customer ID 444), which is not itself included in the customer level hierarchy.

You still have access to the original customer you signed up i.e., 999, and you are still a direct user on Manager Account L1 (customer ID 111). Now the GetUser operation will return two additional CustomerRole objects i.e., one each for Manager Account L2 (customer ID 222) and Manager Account L3 (customer ID 333). You can access all of the AccountIds and LinkedAccountIds that are accessible via Manager Account L2 (customer ID 222) and 333 respectively. In this example you can access Ad Account 4A (account ID 444111) through Manager Account L3 (customer ID 333) i.e., when calling service operations that require the customer identifier, you must use Manager Account L3 (customer ID 333) to access account 444111.

<CustomerRoles xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <a:CustomerRole>
      <a:RoleId>41</a:RoleId>
      <a:CustomerId>999</a:CustomerId>
      <a:AccountIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
      <a:LinkedAccountIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
      <a:CustomerLinkPermission i:nil="true"/>
  </a:CustomerRole>
  <a:CustomerRole>
      <a:RoleId>41</a:RoleId>
      <a:CustomerId>111</a:CustomerId>
      <a:AccountIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
      <a:LinkedAccountIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
      <a:CustomerLinkPermission i:nil="true"/>
  </a:CustomerRole>
  <a:CustomerRole>
      <a:RoleId>41</a:RoleId>
      <a:CustomerId>222</a:CustomerId>
      <a:AccountIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
      <a:LinkedAccountIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
      <a:CustomerLinkPermission>Administrative</a:CustomerLinkPermission>
  </a:CustomerRole>
  <a:CustomerRole>
      <a:RoleId>41</a:RoleId>
      <a:CustomerId>333</a:CustomerId>
      <a:AccountIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
      <a:LinkedAccountIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <b:long>444111</b:long>
      </a:LinkedAccountIds>
      <a:CustomerLinkPermission>Standard</a:CustomerLinkPermission>
  </a:CustomerRole>
</CustomerRoles>

The customer roles inform which customers you can access but do not always describe how you obtained the access. The GetLinkedAccountsAndCustomersInfo operation returns the customer and account hierarchy under the specified customer. For details and examples see View the Hierarchy.

Roles Example for Aggregator Hierarchy

If you just signed up for the first time with Microsoft Advertising, obtained Aggregator credentials, and created one new customer and advertiser account via SignupCustomer, the GetUser operation will return two CustomerRole objects. The elements within each CustomerRole are equivalent except for the RoleId. An Aggregator has two role identifiers in Microsoft Advertising i.e., 41 and 33.

<CustomerRoles xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <a:CustomerRole>
      <a:RoleId>33</a:RoleId>
      <a:CustomerId>111</a:CustomerId>
      <a:AccountIds i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
      <a:LinkedAccountIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <b:long>111222</b:long>                  
      </a:LinkedAccountIds>
      <a:CustomerLinkPermission i:nil="true"/>
  </a:CustomerRole>
  <a:CustomerRole>
      <a:RoleId>41</a:RoleId>
      <a:CustomerId>111</a:CustomerId>
      <a:AccountIds i:nil="true" xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays"/>
      <a:LinkedAccountIds xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <b:long>111222</b:long>                  
      </a:LinkedAccountIds>
      <a:CustomerLinkPermission i:nil="true"/>
  </a:CustomerRole>
</CustomerRoles>

Access and Developer Tokens

To programmatically act on behalf of a Microsoft Advertising user, you must obtain their consent. At the end of the consent workflow you can get an access token that represents the user. The access token has the same roles and access to the same accounts as the user has in the Microsoft Advertising web application. In other words, the same accounts and user role permissions available in the Microsoft Advertising web application are available to the user programmatically through the API. For information on getting an access token to act on behalf of a Microsoft Advertising user, see Authentication with OAuth.

You'll also need a developer token that uniquely identifies your application. Obtaining a developer token for API access does not grant additional permissions to any Microsoft Advertising accounts. A developer token enables programmatic access to the accounts already provisioned for a user. For information, see Get a Developer Token.

Tip

To get an access token and make your first service call using the Bing Ads API, see the Quick Start guide.

The AuthenticationToken and DeveloperToken headers must be set in every request via the Bing Ads API. Here is an example call to the GetUser operation.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v13="https://bingads.microsoft.com/Customer/v13">
  <soapenv:Header>
      <v13:DeveloperToken>DeveloperTokenGoesHere</v13:DeveloperToken>
      <v13:AuthenticationToken>AccessTokenGoesHere</v13:AuthenticationToken>
  </soapenv:Header>
  <soapenv:Body>
      <v13:GetUserRequest>
        <v13:UserId xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
      </v13:GetUserRequest>
  </soapenv:Body>
</soapenv:Envelope>

Multi-User Credentials

You can use one set of Microsoft Advertising multi-user credentials to access advertiser accounts across multiple customers, potentially with different user roles and permissions.

It might help to think of "multi-user" credentials to mean "multiple user roles", since from one perspective you only login with one user name to access multipe customers with varying permissions. One person's credentials can act with multiple distinct user roles. For example, your multi-user credentials grants you access to Customer A and Customer B. However, your Viewer user role for Customer A limits you from making any changes on the accounts that Belong to Customer A. But as a Super Admin for Customer B, you have full control over that customer's accounts.

If you already have multiple sets of login credentials you can ask support to consolidate to one set of credentials. The user role and account access through each customer that you had before consolidation are retained. Also note, the same person's credentials can be associated with separate sets of user contact information i.e., unique contact information per customer.

For more details see the Microsoft Advertising help topic Managing your user name to access multiple accounts.

Multi-User Consolidation

If you already login with multiple sets of credentials e.g., two email addresses, multi-user credentials can be provisioned manually. Contact support or your account manager to merge existing user names into a single user name. Another option is to have an invitation sent to you from each customer that you want to manage, and then accept each invitation using the login credentials that you want to keep. This option is available either through the Microsoft Advertising web application or the SendUserInvitation service operation. Once you accept the invitation with existing Microsoft Advertising credentials, you will have "multi-user" credentials.

Let's consider the following user roles and permissions before multi-user consolidation. In the Microsoft Advertising web application each user must log in separately and has different permissions during each logged in session. Likewise via the API each user's access token (see Authentication with OAuth) represents permissions limited to the corresponding user and role.

User Role Permissions
[email protected] Viewer Customer A - All Accounts
[email protected] Super Admin Customer B - All Accounts
[email protected] Viewer Customer C - Account A
[email protected] Standard user Customer B - All Accounts

First please note that only one email address per customer can be consolidated, so in this example [email protected] and [email protected] cannot be consolidated together. Now let's see what happens after the top three users are consolidated under [email protected].

  • No changes for user [email protected] whether via the Microsoft Advertising web application, Microsoft Advertising Editor, or API.
  • The user [email protected] can log in via the Microsoft Advertising web application and Microsoft Advertising Editor. The consolidated users i.e., [email protected] and [email protected] no longer have permissions to sign in via the Microsoft Advertising web application or Microsoft Advertising Editor. While signed in as [email protected], you can switch context to the customer accounts with corresponding user roles that had previously been assigned to [email protected] and [email protected]. Although you can access multiple customers signed in with one user's credentials ([email protected]), you will need to switch from customer to customer to manage the accounts that are linked with unique user roles. Customers and their related accounts remain distinct. For more details see the Microsoft Advertising help topic Managing your user name to access multiple accounts.
  • After multi-user consolidation the access token for user [email protected] will represent permissions to the consolidated list (superset) of accounts. The user role in effect will depend on the customer and account identifiers specified in the service request. Access tokens for [email protected] and [email protected] will no longer be accepted i.e., error 120 - UserLoginAccessDenied will be returned.

Multi-User Contact Info

A person with multi-user credentials is represented by multiple User objects and corresponding user identifiers. In effect, the same person's credentials can be associated with separate sets of user contact information i.e., unique contact information per customer.

The GetUser response can vary depending on who makes the call, even with the same user identifier. Let's say for example, that prior to consolidation the identifiers for [email protected], [email protected], and [email protected] were 123, 456, and 789 respectively. Each user identifier effectively maps a person to a specific customer e.g., identifier 123 maps [email protected] to the original customer that the person could access. In this example we refer to 123 as the original user identifier.

  • If the access token for [email protected] is used to call GetUser, and the UserId is nil or UserId is set to the original user identifier (e.g., 123), the operation will return CustomerRole objects for all customers that the user can access.
  • If the access token for [email protected] is used to call GetUser, and the UserId is set to either 456 or 789, the operation will only return one CustomerRole object that maps this person to a specific customer.

The Name, Lcid, JobTitle, and ContactInfo user settings for the same person will be automatically synchronized with any updates that occur after user consolidation. The LastModifiedByUserId and LastModifiedTime are also in sync across each returned User object, unless you had an old username merged and have not updated any user settings since the consolidation.

Note

The TimeStamp differs from the LastModifiedTime. All TimeStamp values are unique per User and when you call UpdateUser you must include the corresponding user's timestamps (including the address timestamp).

For example let's say you haven't updated user information for [email protected] since prior to consolidation with [email protected] and [email protected]. After consolidation and until the user settings are updated post-consolidation, you will continue to observe a distinct LastModifiedByUserId and LastModifiedTime within each returned User object.

User Id Contact Info Id Permissions LastModifiedByUserId
123 234 Customer A - All Accounts 123
456 567 Customer B - All Accounts 456
789 890 Customer C - Account A 789

Now let's say that [email protected] is acting in the context of Customer B and updates their contact information. The updated contact information as well as the same LastModifiedByUserId and LastModifiedTime are now syncrhonized across all returned User objects.

User Id Contact Info Id Permissions LastModifiedByUserId
123 234 Customer A - All Accounts 456
456 567 Customer B - All Accounts 456
789 890 Customer C - Account A 456

Account Hierarchy

Search advertising businesses typically align with one or more of the following account management models.

  • A direct advertiser builds a Bing Ads API application for its own advertising campaigns and is billed directly by Microsoft for valid ad clicks.
  • A tool provider builds a Bing Ads API application for other companies to manage their advertising campaigns, and is not billed by Microsoft. The advertiser user owns the accounts, is billed directly by Microsoft for valid ad clicks, and may pay a fee to the tool provider.
  • An agency builds a Bing Ads API application for their company to manage the campaigns of their advertising clients. The client of the agency owns the accounts, is billed directly by Microsoft for valid ad clicks, and may pay a fee to the agency.
  • An aggregator or reseller builds a Bing Ads API application to manage the campaigns of their advertising clients, and is billed directly by Microsoft for valid live clicks. The advertiser does not sign up for Microsoft Advertising credentials, and may pay a fee to the aggregator.

Regardless of the business model, the initial sign up and user role provisioning is more or less the same. The sections below discuss additional steps needed to setup agency and aggregator hierarchies.

Agency Hierarchy

An agency builds a Bing Ads API application for their company to manage the campaigns of their advertising clients. Client links enable an agency to manage some or all aspects of an advertiser account. The client link request can limit the scope to individual client advertiser accounts or all accounts under the customer.

Note

In the context of hierarchies a Customer is also known as a "Manager account". An AdvertiserAccount is referred to as an "Account" or "Advertiser account".

There is no set limit to the amount of client accounts that can be linked to an agency; however, only 5 levels of depth are supported for manager account to manager account links. At each level (L1, L2, L3, L4, L5) a manager account could link to any number of manager accounts and ad accounts. For more information about becoming an agency, see the help article Managing your clients as an agency on Microsoft Advertising or Resources for agency partners.

To setup a hierarchy to manage client accounts, the agency must send an invitation to the client, which must then be accepted by an authorized user in the client customer. To determine whether a link already exists, call the SearchClientLinks operation and check the Status element of any returned ClientLink. To search by individual account, set the predicate field to ClientAccountId and set the predicate value to the account identifier that you want to find.

Note

Only a user with Super Admin or Standard credentials can add, update, and search for client links to advertiser accounts. Only a user with Super Admin credentials can add, update, and search for client links to customers.

If a link exists with status either Active, LinkAccepted, LinkInProgress, LinkPending, UnlinkInProgress, or UnlinkPending, the agency cannot initiate a duplicate client link.

If a client link to the specified account does not yet exist, or if the lifecycle of an existing link had ended with status of Expired, LinkCanceled, LinkDeclined, LinkFailed, or Inactive, then the agency can initiate a new client link invitation by calling the AddClientLinks operation. The service transitions client link status to LinkPending immediately.

Important

For advertiser account client links, the agency must specify whether the client or agency will be responsible for billing by setting the IsBillToClient element in the client link request.

To update a client link, its TimeStamp element is required for validation, so you must first call the SearchClientLinks operation to get the existing ClientLink object. Then modify the Status element of the returned ClientLink, and include the updated ClientLink object in a subsequent call to the UpdateClientLinks operation.

Note

The client can accept or decline through an application built on the Bing Ads API, or through the Accounts & Billing tab in the Microsoft Advertising web application.

The client can only use the UpdateClientLinks operation to update the status as LinkAccepted or LinkDeclined.

  • If the client sets the status to LinkDeclined, the client link lifecycle ends. You cannot update a declined client link, and you must send a new invitation to manage the client account.
  • If the client sets the status to LinkAccepted, the status transitions to LinkInProgress. If the link process succeeds, the service updates the client link status to Active.

If the link cannot be established for example, due to a billing transition error, the service updates the client link status to LinkFailed. You cannot update a failed client link, and you must send a new invitation to manage the client account. If the client or agency does not take action within 30 days, the service sets the status to LinkExpired and the client link lifecycle ends. You cannot update an expired client link, and you must send a new invitation to manage the client account.

Link to Client

If the client link status is LinkPending, the agency can choose to cancel a prior link request.

If the client link status is Active, the agency can choose to terminate the existing relationship with the client. To initiate the unlink process, the agency sets the client link status to UnlinkRequested and calls the UpdateClientLinks operation. Updating the status with UnlinkRequested effectively sets the status to UnlinkInProgress. The service transitions client link status to UnlinkPending immediately, and then waits for system resources to proceed. The state should transition quickly to UnlinkInProgress.

If the unlink process fails for example, due to a billing transition error, the client link resumes to Active status. If the unlink process succeeds the status will update to Inactive, and the client link lifecycle ends. You cannot update an inactive client link, and you must send a new invitation to manage the client account.

Unlink from Client

For code examples that show how to add and update a client link invitation, see Client Links Code Example.

View the Hierarchy

An agency has several options to view the accounts hierarchy.

  • The GetUser operation returns user roles per customer and linked accounts. The customer roles inform which customers you can access but do not always describe how you obtained the access. Determining the user role will make a difference between Administrative and Standard client links. For customer role examples, see Get User Roles.
  • The SearchClientLinks operation will give you the current status of a client link if you already have the agency and client entity identifiers. For example, you can search by managing customer ID and either client account ID or client customer ID.
  • The GetLinkedAccountsAndCustomersInfo operation returns the customer and account hierarchy under the specified customer.

Let's say for example, that an agency hierarchy was setup under Manager Account L1 (customer ID 111) with both customer and advertiser account client links:

  • Before the hierarchy was setup, four separate manager accounts had been provisioned. Manager Account L1 contains Ad Account 1A and Ad Account 1B. Manager Account L2 contains Ad Account 2A and Ad Account 2B. Manager Account L3 contains Ad Account 3A and Ad Account 3B. Manager Account L4 contains Ad Account 4A and Ad Account 4B.
  • Manager Account L1 (customer ID 111) links to Manager Account L2 (customer ID 222) with an Administrative link.
  • Manager Account L2 (customer ID 222) links to Manager Account L3 (customer ID 333) with a Standard link.
  • Manager Account L3 (customer ID 333) links to Ad Account 4A (account ID 444111) with an account level link. Ad Account 4A (account ID 444111) is directly under Manager Account L4 (customer ID 444), which is not itself included in the customer level hierarchy. In this example you can access Ad Account 4A (account ID 444111) through Manager Account L3 (customer ID 333) i.e., when calling service operations that require the customer identifier, you must use Manager Account L3 (customer ID 333) to access account 444111.

A user with access to the full hierarchy who signs into the Microsoft Advertising web application on Manager Account L1 (customer ID 111) would have access to the following account view.

Manager Account with Hierarchy

If you search by customer ID 111 the GetLinkedAccountsAndCustomersInfo response includes Ad Account 1A and Ad Account 1B within AccountsInfo. Information about Manager Account L2 is returned within CustomersInfo.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Header>
      <h:TrackingId xmlns:h="https://bingads.microsoft.com/Customer/v13">f4f8d20a-e354-4bfc-b196-bef9d766d372</h:TrackingId>
   </s:Header>
   <s:Body>
      <GetLinkedAccountsAndCustomersInfoResponse xmlns="https://bingads.microsoft.com/Customer/v13">
         <AccountsInfo xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <a:AccountInfo>
               <a:Id>111111</a:Id>
               <a:Name>Ad Account 1A</a:Name>
               <a:Number>E101NUMB</a:Number>
               <a:AccountLifeCycleStatus>Pause</a:AccountLifeCycleStatus>
               <a:PauseReason>2</a:PauseReason>
            </a:AccountInfo>
            <a:AccountInfo>
               <a:Id>111222</a:Id>
               <a:Name>Ad Account 1B</a:Name>
               <a:Number>E102NUMB</a:Number>
               <a:AccountLifeCycleStatus>Pause</a:AccountLifeCycleStatus>
               <a:PauseReason>2</a:PauseReason>
            </a:AccountInfo>
         </AccountsInfo>
         <CustomersInfo xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <a:CustomerInfo>
               <a:Id>222</a:Id>
               <a:Name>Manager Account L2</a:Name>
            </a:CustomerInfo>
         </CustomersInfo>
      </GetLinkedAccountsAndCustomersInfoResponse>
   </s:Body>
</s:Envelope>

Likewise if you search by customer ID 222 the GetLinkedAccountsAndCustomersInfo response includes Ad Account 2A and Ad Account 2B within AccountsInfo. Information about Manager Account L3 is returned within CustomersInfo.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Header>
      <h:TrackingId xmlns:h="https://bingads.microsoft.com/Customer/v13">f4f8d20a-e354-4bfc-b196-bef9d766d372</h:TrackingId>
   </s:Header>
   <s:Body>
      <GetLinkedAccountsAndCustomersInfoResponse xmlns="https://bingads.microsoft.com/Customer/v13">
         <AccountsInfo xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <a:AccountInfo>
               <a:Id>222111</a:Id>
               <a:Name>Ad Account 2A</a:Name>
               <a:Number>E201NUMB</a:Number>
               <a:AccountLifeCycleStatus>Pause</a:AccountLifeCycleStatus>
               <a:PauseReason>2</a:PauseReason>
            </a:AccountInfo>
            <a:AccountInfo>
               <a:Id>222222</a:Id>
               <a:Name>Ad Account 2B</a:Name>
               <a:Number>E202NUMB</a:Number>
               <a:AccountLifeCycleStatus>Pause</a:AccountLifeCycleStatus>
               <a:PauseReason>2</a:PauseReason>
            </a:AccountInfo>
         </AccountsInfo>
         <CustomersInfo xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <a:CustomerInfo>
               <a:Id>333</a:Id>
               <a:Name>Manager Account L3</a:Name>
            </a:CustomerInfo>
         </CustomersInfo>
      </GetLinkedAccountsAndCustomersInfoResponse>
   </s:Body>
</s:Envelope>

Now if you search by customer ID 333 the GetLinkedAccountsAndCustomersInfo response includes Ad Account 3A, Ad Account 3B, and Ad Account 4A within AccountsInfo. No manager accounts are listed within CustomersInfo.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Header>
      <h:TrackingId xmlns:h="https://bingads.microsoft.com/Customer/v13">e9ecedcc-720d-4ba4-a3e8-9bdef148dae2</h:TrackingId>
   </s:Header>
   <s:Body>
      <GetLinkedAccountsAndCustomersInfoResponse xmlns="https://bingads.microsoft.com/Customer/v13">
         <AccountsInfo xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <a:AccountInfo>
               <a:Id>333111</a:Id>
               <a:Name>Ad Account 3A</a:Name>
               <a:Number>E301NUMB</a:Number>
               <a:AccountLifeCycleStatus>Pause</a:AccountLifeCycleStatus>
               <a:PauseReason>2</a:PauseReason>
            </a:AccountInfo>
            <a:AccountInfo>
               <a:Id>333222</a:Id>
               <a:Name>Ad Account 3B</a:Name>
               <a:Number>E302NUMB</a:Number>
               <a:AccountLifeCycleStatus>Pause</a:AccountLifeCycleStatus>
               <a:PauseReason>2</a:PauseReason>
            </a:AccountInfo>
            <a:AccountInfo>
               <a:Id>444111</a:Id>
               <a:Name>Ad Account 4A</a:Name>
               <a:Number>E401NUMB</a:Number>
               <a:AccountLifeCycleStatus>Pause</a:AccountLifeCycleStatus>
               <a:PauseReason>2</a:PauseReason>
            </a:AccountInfo>
         </AccountsInfo>
         <CustomersInfo xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"/>
      </GetLinkedAccountsAndCustomersInfoResponse>
   </s:Body>
</s:Envelope>

Now if you search by customer ID 444 the GetLinkedAccountsAndCustomersInfo response includes Ad Account 4A and Ad Account 4B within AccountsInfo. No manager accounts are listed within CustomersInfo.

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Header>
      <h:TrackingId xmlns:h="https://bingads.microsoft.com/Customer/v13">e5799094-dad6-45b8-983b-4ace50efd86b</h:TrackingId>
   </s:Header>
   <s:Body>
      <GetLinkedAccountsAndCustomersInfoResponse xmlns="https://bingads.microsoft.com/Customer/v13">
         <AccountsInfo xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <a:AccountInfo>
               <a:Id>444111</a:Id>
               <a:Name>Ad Account 4A</a:Name>
               <a:Number>E401NUMB</a:Number>
               <a:AccountLifeCycleStatus>Pause</a:AccountLifeCycleStatus>
               <a:PauseReason>2</a:PauseReason>
            </a:AccountInfo>
            <a:AccountInfo>
               <a:Id>444222</a:Id>
               <a:Name>Ad Account 4B</a:Name>
               <a:Number>E402NUMB</a:Number>
               <a:AccountLifeCycleStatus>Pause</a:AccountLifeCycleStatus>
               <a:PauseReason>2</a:PauseReason>
            </a:AccountInfo>
         </AccountsInfo>
         <CustomersInfo xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance"/>
      </GetLinkedAccountsAndCustomersInfoResponse>
   </s:Body>
</s:Envelope>

Here are some notable takeaways from the example responses above:

  • Although GetLinkedAccountsAndCustomersInfo appears to return a similar structure whether requested by customer ID 111 or 222, there is a notable difference. As mentioned in the scenario introduction the link from Mananger Account L1 to Manager Account L2 is an Administrative link whereas the link from Manager Account L2 to Manager Account L3 is Standard. The GetLinkedAccountsAndCustomersInfo response does not include details about link type i.e., Administrative or Standard. Since the link type can further refine a user's permission depending on their user role, it is included with each CustomerRole when you call GetUser.
  • When searching by customer ID 333 there is no apparent difference between Ad Account 3A, Ad Account 3B, and Ad Account 4A. As mentioned in the scenario introduction Ad Account 4A is accessible via an advertiser account client link, whereas the other accounts are directly contained by Manager Account L3. If you have a requirement to determine the direct owner of each account you can call other service operations e.g., GetAccount or SearchAccounts.
  • In the current hierarchy Ad Account 4B is only available to users in Manager Account L4. Users in Manager Account L3 can be provisioned to access 3 accounts, users in Manager Account L2 can be provisioned to access 5 accounts, and users in Manager Account L1 can be provisioned to access 7 accounts. A Super Admin can choose to limit each user's access to a subset of the available accounts.

Aggregator Hierarchy

The aggregator role is offered to a limited set of partners that offer search-marketing tools and services to a large number of advertisers. The aggregator role allows partners to programmatically create new customer accounts. The aggregator is billed by invoice for all advertising costs incurred by their clients. The advertiser typically does not sign up for Microsoft Advertising credentials, and may pay a fee to the aggregator.

An Aggregator user is provisioned in the primary customer shell. As described in Entity Limits all advertising activity is organized by customer, which can have one or more accounts. Every time SignupCustomer is called by the Aggregator user, a new advertiser account is created within a new customer.

Important

The Aggregator user role is required for SignupCustomer. If a Super Admin user is added to the aggregator customer after your initial credentials are provisioned, by default the user can manage the data of all customers that the aggregator manages. The user won't be able to call SignupCustomer, but will otherwise have read and write access to the campaign data.

The SignupCustomer operation requires both of the Customer and AdvertiserAccount objects. The customer object includes the customer's name, the address where the customer is located, the market in which the customer operates, and the industry in which the customer participates. Although it is possible to add multiple customers with the same details, you should use unique customer names so that users can easily distinguish between customers in a user interface. The account object must specify the name of the account; the type of currency to use to settle the account; and the payment method identifier, which must be set to null. The operation generates an invoice account and sets the payment method identifier to the identifier associated with the aggregator's invoice. The billing rolls up to the aggregator's payment instrument, and aggregators are invoiced for all charges incurred by the customers they manage.

How to Get Aggregator Credentials

To request aggregator credentials, please contact your designated account management team for details about getting the Aggregator role. If you are not currently an aggregator but would like to become one, go to the Microsoft Advertising Partner Program welcome page.

See Also

Customer Management Service Reference
Bing Ads API Web Service Addresses