Quickstart

In this quickstart, you use a client library to retrieve your Google Ads campaigns. To enable API access, you first need to obtain the required OAuth2 credentials. You then add the authorization and account details to a config file. Once the config file is set up, you're ready to make calls against 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 grants access to the API, not to a particular 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 manager account associated with the developer token. The accounts you manage are authorized by OAuth credentials specific to that account. A manager account only requires one set of credentials to manage all subaccounts.

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 going to the API Center (TOOLS > SETUP > API Center).

Key Point: Make sure you're in a Manager account when applying for a developer token.

Client customer ID

The client customer ID is the account number of the Google Ads client account you want to manage via 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 account (optional)

Production accounts serve ads that are rendered to users, and billing is involved. Test accounts won't affect your live ads or charge your account, hence, they're a useful way to experiment with the API. Because test accounts don't serve any actual ads, impressions or cost data will often be zeroed out in API calls.

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. Go to the Google Ads manager accounts page and create a test manager account.

2. Use the Google Ads UI to create a test client account under the test manager account you created above. While logged in to Google Ads as your test manager account, any client accounts you create will automatically be 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 add this to your config file 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 you just created.