Discover v201008 - ServicedAccountService

The ability to retrieve a list of client accounts and their details is useful when you’re managing a large number of accounts using the AdWords API. This was previously possible only with AccountService in the legacy v13 version of the AdWords API. The v201008 version introduces the ServicedAccountService, which brings similar functionality to the new AdWords API. This blog post discusses the differences between the old AccountService and the new ServicedAccountService.

Retrieving client account hierarchy

In v13, you could retrieve the list of client accounts linked to an MCC using the getClientAccounts or getClientAccountInfos methods of AccountService. In the v201008 version of the AdWords API, you can use the get method of ServicedAccountService to get the same results. The following code shows the service in action.

// Get the ServicedAccountService.
ServicedAccountService servicedAccountService =
    (ServicedAccountService) user.GetService(AdWordsService.v201008.
        ServicedAccountService);
 
ServicedAccountSelector selector = new ServicedAccountSelector();
 
try {
  ServicedAccountGraph graph = servicedAccountService.get(selector);
 
  if (graph != null && graph.accounts != null) {
    // Display the accounts.
    Console.WriteLine("There are {0} customers under this account" +
        " hierarchy.", graph.accounts.Length);
    for (int i = 0; i < graph.accounts.Length; i++) {
      Console.WriteLine("{0}) Customer id: {1}\nLogin email: {2}\n" +
          "Company name: {3}\nIsMCC: {4}\n", i + 1,
          graph.accounts[i].customerId, graph.accounts[i].login,
          graph.accounts[i].companyName,
          graph.accounts[i].canManageClients);
    }
  }
} catch (Exception ex) {
  Console.WriteLine("Failed to retrieve accounts. Exception says \"{0}\"",
      ex.Message);
}

ServicedAccountService also allows you to retrieve links that exist between the accounts. To retrieve the links, set the enablePaging field of ServicedAccountSelector to false. The following code shows how to retrieve account links:

selector.enablePaging = false;
selector.serviceTypes = new ServiceType[] { ServiceType.UI_AND_API,
    ServiceType.API_ONLY };
...
...
if (graph != null && graph.accounts != null) {
  // Display the accounts.
  ...
  ...
  // Display the links.
  foreach (Link link in graph.links) {
      Console.WriteLine("There is a {0} link of type {1} from" +
         "{2:###-###-####} to {3:###-###-####}", link.typeOfLink,
         link.serviceType, link.managerId.id, link.clientId.id);
  }
}

An important difference between AccountService.getClientAccounts and ServicedAccountService.get is that getClientAccounts returns only the immediate child accounts, whereas ServicedAccountService.get() returns all of the accounts in the hierarchy. This was harder to do in v13 as you first had to call getClientAccountInfos to find out whether or not a child account is a manager, and then recursively call getClientAccounts to navigate the entire account hierarchy.

To retrieve only the immediate child accounts of your MCC to mimic the behavior of v13’s getClientAccounts method, you can select the relevant accounts as follows:

private Account[] GetClientAccountsForMCC(ServicedAccountGraph graph,
    long mccId) {
  List retval = new List();
  foreach (Link link in graph.links) {
    if (link.managerId.id == mccId) {
      foreach (Account account in graph.accounts) {
        if (account.customerId == link.clientId.id) {
          retval.Add(account);
        }
      }
    }
  }
  return retval.ToArray();
}

Retrieving and updating account information

In v13, you can retrieve and update some fields of a client account using getAccountInfo and updateAccountInfo. This functionality isn’t yet available in v201008, but will be available in a future version of the AdWords API.

Retrieving MCC alerts

In v13, you could retrieve the MCC alerts about your child accounts using getMccAlerts. This functionality is now available through AlertService, another new service introduced in v201008. We will write more about AlertService in a future post.

Please check out this service and share your feedback with us on the forum.

-- Anash P. Oommen, AdWords API Team