Basic Concepts

Working with the AdWords API requires familiarity with several technical concepts. Here we cover the basic concepts you need to effectively work with the AdWords API.

The AdWords API is meant to be used by advanced AdWords users. If you are new to AdWords, check out the AdWords getting started guide. The AdWords certification program is also a good resource for learning about AdWords.

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 When you're developing your application, we recommend that you use your test account.


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

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.
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 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 waiting for token approval, you'll only be able to make calls against test accounts. After approval, you'll 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.


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

        Root MA 1
        |       |
    Sub MA 2   Sub MA 3
    |      |      |
    A      B      C

Continuing with the example hierarchy, to make AdWords API calls against Client A, you can use the credentials of a login email associated with Client A and set the clientCustomerId header to Client A, Sub MA 2 or Root MA 1. If you use either of the manager accounts (MA), then set the clientCustomerId to that manager account or one of its child accounts.

Calls made with the credentials of a manager account can only target the manager account or accounts that are beneath the manager account in the hierarchy.

Your developer token can belong to Root MA 1 or even a different manager account in another hierarchy--it doesn't affect which accounts you can target.


The AdWords API is a SOAP API. Making calls to the AdWords API involves sending HTTPS POST requests to the AdWords API servers and then 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.

If you are using a client library or a SOAP library to interact with 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.

We now introduce you to the parameters in the AdWords API SOAP request and response headers, then show you an example of making a SOAP call using cURL.

Request headers

HTTP Headers

You need to include an OAuth2 access token in the form of Authorization : Bearer YOUR_ACCESS_TOKEN that identifies either a manager account acting on the behalf of a client, or an advertiser directly managing their own account. Directions for retrieving an access token can be found in the OAuth2 guide. An access token is valid for an hour after you acquire it; when it expires, refresh the access token to retrieve a new one. (Our client libraries automatically refresh expired tokens.)

Soap headers

When sending a request to any of the AdWords API web services, you must provide the following headers with your request:

A 22-character string that uniquely identifies an AdWords API developer. An example developer token string is ABcdeFGH93KL-NOPQ_STUv.
A user-specified string that defines the sender and purpose of the request. Set this to your application name and version in order to help us find your requests when diagnosing a problem, e.g.,
Customer ID of the target AdWords account, typically in the form of 123-456-7890. Required for all calls to all services except to CustomerService and ReportDefinitionService.
validateOnly (optional)
If set to true, the request is validated but not performed. You can use this header to validate user-provided data.
partialFailure (optional; AdGroupAdService, AdGroupBidModifierService, AdGroupCriterionService, AdGroupService, BudgetService, CampaignCriterionService, CampaignService, FeedItemService, OfflineConversionFeedService)
If set to true, the service will perform error-free operations and return the failing operations' errors. This header is ignored for non-mutate operations.

Response headers

The following headers are returned with the response XML. For support and debugging purposes, we recommend that you log these values.

String that uniquely identifies this request.
Number of operations performed in this request.
Elapsed time in milliseconds between the web service receiving the request and sending the response.

API call example

This example demonstrates how to interact with the AdWords API using cURL. Although cURL and SOAP+XML would be impractical for building a real-world application, it demonstrates how the AdWords API functions at the lowest level.

  1. Get your access token. First, you need to register your application using the Google Developers Console and create a Client ID as an Installed application. Google then provides some information that you'll need later, such as a client ID and a client secret.

    To request your authentication token from OAuth2, paste the following URL in your browser

    You will then see a screen to grant your application access to your AdWords data:

    After you accept the request, you will get an authorization code that can be exchanged for an access token.

    Finally, you can make the request to exchange the authorization code for an access token:

    curl \
      -d code=your-authorization-code \
      -d client_id=your-client-id \
      -d client_secret=your-client-secret \
      -d redirect_uri=urn:ietf:wg:oauth:2.0:oob \
      -d grant_type=authorization_code

    If you've made a proper request, Google will return your OAuth2 token. The access token (shown in bold after access_token :) is what you need when sending requests to AdWords API services.

      "access_token" : "ya29.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "token_type" : "Bearer",
      "expires_in" : 3600,
      "refresh_token" : "1/Ixxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

  2. Create a SOAP request. The following XML defines a SOAP request that adds a budget. Save this XML (with your authentication token and account login replacing the placeholders) as hello_world.xml.

    <?xml version="1.0" encoding="UTF-8"?>
    <soapenv:Envelope xmlns:soapenv="" xmlns:xsd="" xmlns:xsi="">
    <ns1:RequestHeader soapenv:actor="" soapenv:mustUnderstand="0" xmlns:ns1="">
    <mutate xmlns="">
          <name>Hello World</name>
          <settings xsi:type="ns2:GeoTargetTypeSetting" xmlns:ns2="">
          <settings xsi:type="ns3:KeywordMatchSetting" xmlns:ns3="">
            <biddingScheme xsi:type="ns4:ManualCpcBiddingScheme" xmlns:ns4="">

  3. Send the request. Use cURL to send this SOAP request to CampaignService. You can send your access token by including it in the HTTP header like this:

    curl --header "Content-Type: application/soap+xml" \
         --header "Authorization : Bearer YOUR_ACCESS_TOKEN" \
         --data @hello_world.xml \

    After the AdWords API server processes your request, it returns a response that contains the XML data representing the newly-added campaign:

    <?xml version="1.0" encoding="UTF-8"?>
      <soap:Envelope xmlns:soap="">
      <ResponseHeader xmlns="">
      <mutateResponse xmlns="">
            <name>Hello World</name>
            <settings xsi:type="GeoTargetTypeSetting" xmlns:xsi="">
              <biddingScheme xsi:type="ManualCpcBiddingScheme" xmlns:xsi="">

Next step

Proceed to Working with Objects for a discussion of the objects and operations you'll be encountering.

Send feedback about...

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