Working with the AdWords API effectively requires familiarity with several technical concepts. In this guide, we will cover the concepts you need to understand as a developer to work with the AdWords API effectively.

1. Prerequisites
   1. AdWords
   2. SOAP and XML
   3. ClientLogin API and OAuth
2. Understanding the AdWords API server environment
3. Understanding AdWords API billing
4. Making AdWords API calls

Prerequisites

To use the AdWords API effectively, you need to be familiar with various technologies and product concepts that the AdWords API uses. The most important ones are listed below:

AdWords

The AdWords API is meant to be used by advanced users who have already worked with AdWords. If you are new to AdWords, we highly recommend that you familiarize yourself with AdWords before using the API. The AdWords Certification Program Learning Center is a good resource to learn about AdWords features.

SOAP and XML

The AdWords API is a SOAP API. Making calls to the AdWords API involves sending HTTPS POST requests to the AdWords API servers and parsing the response. The request and response body is XML. The structure of the XML is defined by a WSDL document obtained by adding a ?wsdl parameter to the service URL (e.g. https://adwords.google.com/api/adwords/cm/v201306/CampaignService?wsdl). W3Schools has good tutorials on SOAP and XML in case you need to learn more about these technologies. If you are using a client library or a SOAP library to call the AdWords API, you probably won’t need to worry about SOAP and XML; however, knowledge of SOAP and XML can come in handy when debugging issues with the AdWords API.

ClientLogin API and OAuth

Important: ClientLogin and OAuth1.0a have been officially deprecated as of April 20, 2012. They will continue to work as per our deprecation policy, but we encourage you to migrate to OAuth 2.0 as soon as possible.

When using the AdWords API, you can use one of two authentication mechanisms to authenticate your calls.

1. ClientLogin API: The ClientLogin API allows you to use your AdWords account login email and password to obtain a long-lived token (referred to as authToken) that can be used to authenticate your calls to the AdWords API. The ClientLogin API is not part of the AdWords API, so the AdWords API documentation doesn’t talk about this API in detail.

   All our client libraries have support for the ClientLogin API, so you don’t need to implement the protocol if you are using our client libraries. However, there are a few things to keep in mind when using the ClientLogin API.

   1. The authTokens returned by the ClientLogin API are long-lived, and last 2 weeks. We recommend that developers cache and reuse the authTokens. If you call the ClientLogin API for a given account too frequently, it will eventually throw Captcha errors. You can refer to our best practices guide for more details.

   2. If you call the ClientLogin API too many times with an incorrect password, your account will get locked. In such cases, you can visit https://www.google.com/accounts/DisplayUnlockCaptcha to unlock your account.

   3. If your AdWords account has enabled 2-step verification, then you won’t be able to obtain an authToken with your regular login email / password. You will need to use an application-specific password instead. See our best practices guide to learn how to handle accounts with 2-step verification enabled.

2. OAuth: The biggest drawback of the ClientLogin API is that you need your customer’s login email and password to generate an authToken. OAuth is an open protocol used to allow secure API authorization from desktop and web applications without requiring the customer’s login email and password. Just like ClientLogin, OAuth is also not part of the AdWords API, and hence the documentation doesn’t talk about OAuth in detail. You can learn more about OAuth at http://oauth.net/. The AdWords API supports OAuth 1.0a and OAuth2 draft 10. Unlike ClientLogin tokens, OAuth 1.0a access tokens do not expire. Also, OAuth is not subject to CAPTCHA challenges like the ClientLogin API. To learn more about using OAuth with Google APIs, see this article for OAuth 1.0a and this article for OAuth 2.0. All our client libraries support both OAuth 1.0a and OAuth 2.0 authorization mechanisms.

Understanding the AdWords API server environment

The AdWords API's production environment consists of your actual AdWords accounts that serve ads and a test account used during development. The production environment is hosted at https://adwords.google.com. When you develop an AdWords API application, we recommend that you use your test account.

Understanding AdWords API billing

There is no charge for AdWords API usage. The AdWords API provides two access levels: Basic and Standard.

Basic

This is the default access level for all approved developer tokens. This access level allows developers to execute up to 10,000 operations per day.

Standard

This access level is for those needing more than 10,000 operations per day. To qualify for this access level, a developer will need to provide additional details and keep these details current with Google.

For more details about the access levels, see the FAQ and rate sheet.

Making AdWords API calls

Calls made against the AdWords API require two pieces of information: an approved developer token and credentials that allow access to the targeted account.

Developer Token

When you sign up for the AdWords API, a Developer Token is automatically generated for you. This token is 22 characters long, comprised of a-z, A-Z, 0-9, - and _. Right after you apply, your token will be pending approval. While pending, you will only be able to make calls against test accounts. After it has been approved, you will be able to target any AdWords account with your Developer Token. Developer tokens do not expire, but they may be rejected due to lack of use. See the Terms and Conditions for more details.

An approved Developer Token gives you the ability to make calls against the AdWords API. It does not affect or limit which accounts you can target—this is determined by the credentials you use to authorize your request.

Credentials

Each request to the AdWords API must be authorized to make changes or retrieve data for an AdWords account. The credentials used for an API call determine what account(s) can be targeted. We recommend using OAuth2 to authorize requests to the AdWords API. As an example, let’s assume the following account hierarchy:

        Root MCC 1
        |         |
    Sub MCC 2    Sub MCC 3
    |        |           |
Client A    Client B     Client C

Continuing with that example hierarchy, to make AdWords API calls against Client A, you can use the credentials of a login email associated with Client A, Sub MCC 2 or Root MCC 1. If you use either MCC, you’ll need to set the clientCustomerId header to indicate you are targeting a different account than the one you’ve authenticated with. We recommend that you always specify a clientCustomerId header, but if you don’t, the request will target the same account you’ve authenticated with. Calls made with the credentials of an MCC account can only target accounts that are beneath that MCC in the account hierarchy.

What accounts you can make calls against depends on your authenticated account’s access level. For instance, if you use a standard access login email of Root MCC 1 (and don’t specify a clientCustomerId of a child non-MCC account), you’ll only be able to make ManagedCustomerService calls against Root MCC 1. Note that the access level of the login email applies—if you’ve authenticated as a read-only login on Client B, you will only be able to make GET calls and download reports. Email-only logins cannot make AdWords API calls at all.

Your developer token might belong to Root MCC 1 or even a different MCC in another hierarchy—it does not affect which accounts you can target.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.