The AdWords API is no longer supported. Use the Google Ads API instead.

Managing Accounts

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

This guide assumes you're already familiar with Google Ads manager and client accounts. If you need to brush up on the basics of Google Ads accounts and access levels, see the Google Ads 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 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.

If no clientCustomerId is specified in a request, 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:


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


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.

    <name>Account Created with MCS</name>
    <name>Google Ads Test Manager Account</name>

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:

The field canManageClients is read-only, and is ignored when creating a new client account.

The account management folder of each client library contains a code example for creating accounts:

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();
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. The name, 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();
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 administrative owner the CLIENT_CID in this request.

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
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 administrative owner the CLIENT_CID in this request.

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
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();
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

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

Moving client accounts

You can easily move Google Ads 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();
ManagedCustomerLink link = new ManagedCustomerLink();
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.


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 limit

Your manager account may eventually reach the limit on the number of accounts to which it can be linked. At that point, you must create a new parallel top-level manager account to handle new client accounts.

To obtain access to the new top-level manager account, you need to repeat the OAuth2 authorization for it. Note that you still use the developer token from your primary manager account when making API requests.


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 Google Ads accounts.

OAuth2 credentials

Each request to the AdWords API must be authorized to make changes or retrieve data for a specified Google Ads 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 Google Ads 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, OAuth2 credentials for a login associated with Manager Account 3 can make calls only against Client Account C. These credentials cannot make calls targeting Client Account A or B, because it doesn't manage them. OAuth2 credentials of a login associated with 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

Production manager and client accounts establish structure and organization, but what about testing experimental changes, or testing API calls while you're developing—without affecting your production environment? That's the purpose of test accounts.

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 Google Ads UI, just like production accounts.
  • Have the same restrictions (including rate limits) as production 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 Google Ads UI, and appear with a red label:

If you don't see the red Test account label on your Google Ads account page, then the account is a production account.

Getting started with test accounts

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

The first step is creating the root test manager account. All client accounts created under the test manager account will automatically be test accounts.

Perform these steps to create and use a test manager account:

  1. If you don't already have an API developer token or haven't applied for one (approval pending):
    1. Create a production manager account (for example,
    2. Request a developer token in the production manager account.
  2. Create a test manager account (Select NEW GOOGLE ADS ACCOUNT and then name the new account something like To create a test account, you must have a Google account that is not already linked to your production manager account. Create a new Google account.
  3. Once your test manager account is established, you can proceed to make API calls against it. 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,

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

Production developer token status Google Ads 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:

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 50 accounts in the hierarchy of a test manager account.
  • You can't issue mutate operations to BudgetOrderService from test accounts since the accounts don't have associated billing.
  • When testing uploading customer match lists, the test account needs to be added to an existing allowlisted manager account.

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

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.