Managing Accounts

This guide explains how to manage AdWords accounts—including manager, client, and test accounts—using the AdWords API.

This guide assumes you're already familiar with AdWords manager and client accounts. If you need to brush up on the basics of AdWords accounts and access levels, see the AdWords Help Center manager account and access levels pages.

Creating and organizing accounts

CustomerService and ManagedCustomerService are the API services used to create accounts, obtain account information, and manage links between accounts. For managing account labels, use AccountLabelService.

CustomerService

CustomerService provides information about your accounts. It has a getCustomers() method that takes no arguments and returns a list of Customer objects containing fields such as customerId, currencyCode, and dateTimeZone. CustomerService also has a mutate() method that can be used to update various attributes of a customer, including the autoTaggingEnabled and conversionTrackingSetting fields.

In v201605 and earlier, if no clientCustomerId is specified, then the response will contain a single entry for the authenticated account. You must specify a clientCustomerId when authenticating as a manager account to obtain info for a specific account (see Authentication below for more details).

Starting with v201607, if no clientCustomerId is specified, then the response will contain multiple entries if more than one account is directly accessible by the authenticated account. If you only want results for a single account, you must specify the clientCustomerId in your request.

Example response:

<rval>
   <customerId>123456789</customerId>
   <currencyCode>USD</currencyCode>
   <dateTimeZone>America/New_York</dateTimeZone>
   <descriptiveName>myaccount</descriptiveName>
   <canManageClients>false</canManageClients>
</rval>

The Reference documentation contains a list of values for currencies and timezones.

ManagedCustomerService

ManagedCustomerService also has a get() method and a generic selector. There are more fields to choose from than with CustomerService--consult the reference documentation for more details.

In addition to a list of accounts that meet the criteria in your selector, you'll also get a list of ManagedCustomerLink objects that describe the relationship between accounts.

<rval>
 <totalNumEntries>3</totalNumEntries>
 <Page.Type>ManagedCustomerPage</Page.Type>
 <entries>
    <name>Account Created with MCS</name>
    <login/>
    <companyName/>
    <customerId>789</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>ZAR</currencyCode>
    <dateTimeZone>Pacific/Pago_Pago</dateTimeZone>
 </entries>
 <entries>
    <name>Adwords Test Manager Account</name>
    <login>my-manager-account@example.com</login>
    <companyName/>
    <customerId>123</customerId>
    <canManageClients>true</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
 </entries>
 <entries>
    <name>myaccount</name>
    <login>myaccount@example.com</login>
    <companyName/>
    <customerId>456</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
 </entries>
 <links>
    <managerCustomerId>123</managerCustomerId>
    <clientCustomerId>456</clientCustomerId>
 </links>
 <links>
    <managerCustomerId>123</managerCustomerId>
    <clientCustomerId>789</clientCustomerId>
 </links>
</rval>

ManagedCustomerService is also used to create new accounts. These new accounts will belong to the effective user, which must also be a manager account. Here is a sample request:

<operations>
  <operator>ADD</operator>
  <operand>
    <name>Foo</name>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
  </operand>
</operations>

Example response:

<rval>
  <value>
    <name>Foo</name>
    <customerId>9876543210</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
  </value>
</rval>

Fields such as companyName, login, and canManageClients are read-only, and are ignored when creating a new client account. ManagedCustomerService cannot be used to update a client account once it has been created.

Linking accounts

Linking a manager and client account allows the manager account to make requests on behalf of its client accounts.

ManagedCustomerService is used to manage links between accounts, allowing for automated management of your account hierarchy:

To link a manager account and a client account:

  1. The manager account must extend an invitation to the client account.
  2. The client must accept the invitation.

Extending invitations

A manager account can invite a client account or another manager account to be managed.

In this scenario, the MANAGER_ID can be either the manager account you're authenticated as, or another child manager account within your hierarchy. CLIENT_CID must be a client or manager account that is not currently managed by a manager account in your hierarchy.

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.PENDING);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.ADD);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

Invitations are extended by sending an ADD operation with a PENDING link status.

Get pending invitations

Invitations that have not been acted on can be retrieved with ManagedCustomerService.getPendingInvitations, from either the client or manager account. After the client responds by accepting or declining, or if the manager account rescinds the invitation, the invitation is no longer pending.

Only ACTIVE links will be displayed in a ManagedCustomerService.get() call--CANCELLED, REFUSED, and INACTIVE links are never returned.

The following call returns all pending invitations for the manager account.

PendingInvitationSelector selector = new PendingInvitationSelector();
PendingInvitation[] invitations = managedCustomerService.getPendingInvitations(selector);

You can also set the managerCustomerIds and clientCustomerIds fields with manager and client account customer IDs (respectively), to return pending invitations for those accounts. Note that the clientCustomerIds must be managed through the hierarchy of the effective account to see their links. When the effective user is a client account, only pending invitations for that account will be seen.

This request returns PendingInvitations with ManagedCustomer records. Name, login, companyName, customerId, canManageClients fields will be populated for both manager and client.

Rescinding invitations

If you send an invitation to manage a client account but then change your mind, you can rescind the invitation by setting the link status to CANCELLED in a SET operation, with the effective account as a manager account that can manage this link.

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.CANCELLED);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

Client declines

The client can also decline the invitation by setting the link status to REFUSED in a SET operation. The effective user must match or manage as an adminstrative owner the CLIENT_CID in this request.

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.REFUSED);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

Client accepts

The client accepts the invitation by using SET to set the link status to ACTIVE. As with declining, the effective user must match or manage as an adminstrative owner the CLIENT_CID in this request.

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.ACTIVE);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

When a client or its manager have decided to part ways, the account link can be terminated: Use SETto set the LinkStatus to INACTIVE.

ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.INACTIVE);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

This can be done as either the manager or client account.

Moving client accounts

You can easily move AdWords accounts from one manager account to another using ManagedCustomerService.mutateManager(). Both client and manager accounts can be moved using the mutateManager() method.

MoveOperation op = new MoveOperation();
op.setOldManagerCustomerId(MANAGER_CID);
op.setOperator(Operator.SET);
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.ACTIVE);
link.setManagerCustomerId(NEW_MANAGER_CID);
op.setOperand(link);
managedCustomerService.mutateManager(new MoveOperation[]{op});

The new manager and old manager must both be managed by the effective account. The link status must be ACTIVE. Use the NEW_MANAGER_CID as the link's managerCustomerId and specify the old MANAGER_CID in the MoveOperation's oldManagerCustomerId.

AccountLabelService

Account labels can be used to help organize and manage accounts. Through AccountLabelService, you can add, update, or remove labels at the account level. With the API, you can manage your submanager's account labels as well.

Manager account limits

There are some limitations you should be aware of when working with manager accounts. You can find them on the System Limits reference page, along with the complete list of other system limits.

AdWords accounts rarely come close to these limitations. If an AdWords account you need to manage has already maxed out on any limits, you'll have to fix the issues prior to linking that account.

In addition, be careful to not exceed operational rate limits.

Authentication

Calls made against the AdWords API require an approved developer token, and credentials generated in OAuth2, for the targeted account.

The simplest approach is to authenticate as a manager account. Once you're authenticated, you are granted access to all accounts under that manager account. Authentication is handled using OAuth2.

Developer token

When you sign up for the AdWords API, a developer token is automatically generated for you. Right after you apply, your token will be pending approval.

While waiting for token approval, you'll be able to make calls against test accounts. After token approval, you'll be able to target production AdWords accounts.

OAuth2 credentials

Each request to the AdWords API must be authorized to make changes or retrieve data for a specified AdWords account. The OAuth2 credentials used in an API call determine which account(s) can be targeted.

Calls made with the credentials of a manager account can target the manager account, or any accounts for which you have the OAuth2 credentials. For example, let's look at a typical AdWords account hierarchy:

Your developer token can belong to Root Manager Account 1, or even a different manager account in another hierarchy: It doesn't affect which accounts you can target, as long as you supply the client customer ID for the targeted account.

To make API calls against Client account A, you can use the OAuth2 credentials of a login associated with Client account A, and set the clientCustomerId request header to the customer ID of either Client A, Manager Account 2, or Root Manager Account 1.

In this structure, Manager Account 3 can make calls only against Client Account C. It cannot make calls targeting Client Account A or B, because it doesn't manage them. Root Manager Account 1 can make calls against any of the accounts in the hierarchy.

Calls made with the credentials of a manager account can only target the manager account or accounts that are beneath it in the hierarchy. Thus, in this hierarchy, only Root Manager Account 1 can make calls against Client Account D.

If you use either of the manager accounts, then set the clientCustomerId to that manager account, or one of its child accounts.

Test accounts

Manager and client accounts are useful for organizing, but what about testing experimental changes, or testing API calls while you're developing, without affecting your production environment? That's what test accounts are for.

Test accounts allow you to try out new API implementations or account configurations, prior to implementing the changes in your production environment.

Test accounts can be set up in a hierarchy and organized just like production accounts, but provide extra benefits during active development. Particularly, test accounts:

  • Don't require an approved developer token, so you can start experimenting with the API immediately, even before your application is reviewed or approved.
  • Can't serve ads or interact with your production accounts in any way.
  • Can be viewed and manipulated in the AdWords web interface, just like normal accounts.

Because test and production accounts cannot interact in any way, you cannot use a test account under your existing production manager account. To use test accounts, you'll need a new account hierarchy, with a test manager account as the root.

Test accounts are accessible from the AdWords web interface, and appear with a red label (see below).

Test accounts have the same restrictions (including rate limits) as production accounts.

Getting started with test accounts

Prior to making API requests to a test account, make sure you also have a production (non-test) manager account and a developer token, even if the token is still pending approval.

Using your production manager account, you must first create a test manager account prior to creating test client accounts. All client accounts created under the test manager account will be automatically marked as test accounts.

Perform the following steps to create and use a test account:

  1. If you don't already have a production manager account and/or a production manager developer token:
    1. Create a production manager account (for example, production-manager@mycompany.example.com)
    2. Request a developer token in the production manager account.
  2. Create a test manager account (for example, test-manager@mycompany.example.com). To create a test account, you must have an existing Google account that is not already linked to an AdWords account. You can create a new Google account at accounts.google.com.
  3. Use the production manager account's developer token when making requests againsts the test manager account.
  4. When requesting an OAuth2 refresh token, make sure you're logged in as the test manager account user (for example, test-manager@mycompany.example.com)

The table below explains the allowed interactions between different AdWords account types and a developer's token based on its approval status:

Production developer token status AdWords account type Allowed
Pending Approval Test Yes
Pending Approval Non-Test No
Approved Test Yes
Approved Non-Test Yes

Using OAuth2 with test accounts

To access a test account using OAuth2, the test manager account user must grant permission to your client application. Therefore, when requesting a refresh token, ensure you're logged in as the test manager account rather than the production manager account.

When you want to switch from the test manager account to the production manager account, simply reconfigure the client library to use the production manager account's refresh token.

Request headers

All requests to test accounts should be sent to the same endpoint as production requests:

https://www.googleapis.com/auth/adwords/

Request and response SOAP headers are identical to those returned in production accounts. For authorization headers, make sure to use your test account credentials.

Additional characteristics of test accounts

There are a few things to keep in mind when working with test accounts:

  • The TargetingIdeaService and TrafficEstimatorService return dummy data to test accounts.
  • Since test accounts don't serve ads, they also have no metrics. This impacts reports: Values for impressions, costs, etc. will all be zero.
  • Test accounts don't have any associated clicks, so they can't be used to test offline conversion uploads.
  • The DataService won't return bid landscapes for test accounts because bid landscapes are based on ads served from the account.
  • You can only have 100 accounts in the hierarchy of a test manager account. The limit for production accounts is much higher.

Developing with test accounts

When signing up for AdWords API access, you may be asked to demonstrate some features of your application. One such feature is reporting, which can be difficult to emulate when using only test accounts.

Because test accounts don't serve impressions, they don't produce any metrics. It's still possible to download structural reports—but you will see only zero-impression rows, which means that segments won't work.

As a workaround, we suggest displaying fake data. The Token Review team needs to see that your app can interact with and display report data. By mocking out the report call (that is, pretending the report call succeeded, and using a locally stored file containing fake report data), you can add report data without actually getting it from the API.

Make sure your test report data is in the correct format. For example, if you run a campaign performance report with date, campaign name, campaign ID, impressions, clicks, and costs, you'll get a file like this:

"CAMPAIGN_PERFORMANCE_REPORT (Mar 20, 2013-Mar 23, 2013)"
Day,Campaign,Campaign ID,Impressions,Clicks,Cost
20130320,Widgets,123,1211,19,14.92
20130320,Sprockets,456,300,4,2.92
20130321,Widgets,123,901,12,9.86
20130321,Sprockets,456,340,5,3.86
20130322,Widgets,123,1065,16,11.23
20130322,Sprockets,456,509,6,5.23
20130323,Widgets,123,1005,15,10.12
20130323,Sprockets,456,287,3,1.12

By constructing such a file and storing it locally, your application can mock the call to the API. When the report is requested, return the stored file and process that, rather than making an actual API call. You can create a file like this for each report you want to display.

Testing with production data

You can test using production data in a read-only fashion on your production accounts if you use the validateOnly header in your requests, and you have an approved developer token.

Send feedback about...

AdWords API
AdWords API
Need help? Visit our support page.