Quickstart

This guide uses a client library to retrieve Google Ads campaigns.

To enable API access, first obtain the required OAuth2 credentials. Then, add the authorization and account details to a config file. Once the config file is set up, you're ready to call the API.

Prerequisites

Config parameters

You'll need to supply the following information in the config file of your client library.

Developer token

Your developer token lets your app access the API, but the token is not restricted to only one Google Ads account. Once your token is approved, you can use the same token for requests against all your Google Ads accounts, even if they're not linked to the Google Ads Manager Account associated with the token. The accounts you manage are authorized by OAuth credentials from the manager account. A manager account requires only one set of credentials to manage all of its sub-accounts.

Only approved tokens can connect to the API for production Google Ads accounts; pending tokens can connect only to test accounts.

You can retrieve your developer token by signing in to your manager account then navigating to the API Center (TOOLS & SETTINGS > SETUP > API Center).

Key Points

• A company should have only one developer token.
• Once a client ID from a Google Cloud project is used with a developer token, the client ID is bound to the developer token and can't be used with another developer token. In other words:
  • A developer token can be used with multiple client IDs.
  • However, a client ID can be used with only one developer token.

Client customer ID

The client customer ID is the account number of the Google Ads client account you want to manage with the API, usually in the form 123-456-7890.

Optionally, the client customer ID can be left out of the config file and set programmatically. Once your developer token is approved, you can use a client customer ID from a production account instead of a test account.

OAuth2 client ID and client secret

The OAuth2 client ID and client secret map your client app to a project in the Google API Console and are used for OAuth2 authentication—allowing your app to operate on behalf of your account. They identify your app to Google and allow you to generate OAuth tokens for managing Google Ads users.

Note: The word "client" here refers to your app, not the Google Ads client account.

Consult Create a client ID and client secret for more details.

OAuth2 access and refresh tokens

Before your app can access private data using the API, it must obtain an OAuth2 access token that grants access to the API.

If you're using the client libraries, the OAuth2 access token is automatically taken care of for you. Otherwise, check out the API call example in the OAuth2 guide for details on how to generate an access token.

OAuth2 access tokens expire after a limited time. For this reason, the client libraries use the OAuth2 refresh token to automatically regenerate the OAuth2 access token.

OAuth2 access and refresh tokens has instructions for creating the refresh token.

For more information on using OAuth2 with Google APIs read the OAuth2 Authentication and OAuth2 Identity Platform documentation.

Test accounts

Production accounts serve ads that are rendered to users, and billing is involved. Test accounts, on the other hand, appear in the Google Ads UI as cancelled accounts since there are no active billing or serving, though API requests still work.

To view test accounts in the UI, you can unhide the accounts by choosing to view cancelled accounts.

Test accounts won't affect your live ads or charge your account, hence, they're a useful way to experiment with the API. Test accounts provide extra benefits during active development. Particularly, test accounts:

• Can be set up in a hierarchy and organized just like production accounts.
• Can be viewed and manipulated in the Google Ads UI, just like production 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. Because of this, impressions or cost data associated with test accounts will be empty.
• Have the same restrictions (including rate limits) as production accounts.

Since test accounts don't have budgets, you may see an error when creating a test sub-account in a manager account. You can ignore this error; the test account will still be created.

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.

Follow the instructions below to create a test manager account, a test client account, and a few campaigns to populate the test client account. Note that "client" here refers to a Google Ads client account, not your client app.

1. Create a test manager account (Select NEW GOOGLE ADS ACCOUNT and then name the new account something like [e-mail]). 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.
2. While signed in to your test manager account, create a test client account. Any client accounts you create from your test manager account are automatically test accounts.
3. Create a few test campaigns under the test client account in the Google Ads UI.
4. Take note of the client customer ID for the new test client account, and save it. You'll need this to make API calls later.

Important: Use the developer token of your production manager account when making requests against the test manager account. Even if it's not approved yet, the token will still work on test accounts, including the ones just created.