AdWords API

SOAP Primer

We 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

Authorization
You need to include an OAuth2 access token in the form of Authorization : Bearer YOUR_ACCESS_TOKEN that identifies either an MCC manager acting on 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:

developerToken
A 22-character string that uniquely identifies an AdWords API developer. An example developer token string is ABcdeFGH93KL-NOPQ_STUv.
userAgent
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. Example: example.com:ReportDownloader:V7.18
clientCustomerId
When acting on behalf of a client, this header specifies that client's customer ID. Customer IDs are typically of the form 123-456-7890.
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; AdGroupCriterionService, AdGroupAdService; v201206+: AdGroupService, CampaignService, CampaignAdExtensionService, CampaignCriterionService)
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.

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

Sending SOAP 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. 0. Get your access token.

    First you need to register your application using the Google Cloud Console and create a Client ID as an Installed application. Google then provides information 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

    https://accounts.google.com/o/oauth2/auth?
    client_id=your-client-id&\
    response_type=code&\
    scope=https%3A%2F%2Fadwords.google.com%2Fapi%2Fadwords%2F&\
    redirect_uri=urn:ietf:wg:oauth:2.0:oob&\
    access_type=offline&\
    approval_prompt=auto

    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 https://accounts.google.com/o/oauth2/token

    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. 1. 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. If you need to identify the clientCustomerId, refer to these instructions.

    <?xml version="1.0" encoding="UTF-8"?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <soapenv:Header>
        <ns1:RequestHeader soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="0" xmlns:ns1="https://adwords.google.com/api/adwords/cm/v201402">
          <ns1:clientCustomerId>xxx-xxx-xxxx</ns1:clientCustomerId>
          <ns1:developerToken>YOUR_DEVELOPER_TOKEN</ns1:developerToken>
          <ns1:userAgent>YOUR_APPLICATION_NAME</ns1:userAgent>
          <ns1:validateOnly>false</ns1:validateOnly>
          <ns1:partialFailure>false</ns1:partialFailure>
        </ns1:RequestHeader>
      </soapenv:Header>
      <soapenv:Body>
        <mutate xmlns="https://adwords.google.com/api/adwords/cm/v201402">
          <operations>
            <operator>ADD</operator>
            <operand>
              <name>Hello World</name>
              <status>PAUSED</status>
              <budget>
                <budgetId>987654321</budgetId>
              </budget>
              <settings xsi:type="ns2:GeoTargetTypeSetting" xmlns:ns2="https://adwords.google.com/api/adwords/cm/v201402">
                <positiveGeoTargetType>DONT_CARE</positiveGeoTargetType>
              </settings>
              <settings xsi:type="ns3:KeywordMatchSetting" xmlns:ns3="https://adwords.google.com/api/adwords/cm/v201402">
                <optIn>false</optIn>
              </settings>
              <networkSetting>
                <targetGoogleSearch>true</targetGoogleSearch>
                <targetSearchNetwork>true</targetSearchNetwork>
                <targetContentNetwork>false</targetContentNetwork>
              </networkSetting>
              <biddingStrategyConfiguration>
                <biddingScheme xsi:type="ns4:ManualCpcBiddingScheme" xmlns:ns4="https://adwords.google.com/api/adwords/cm/v201402">
                  <enhancedCpcEnabled>false</enhancedCpcEnabled>
                </biddingScheme>
              </biddingStrategyConfiguration>
            </operand>
          </operations>
        </mutate>
      </soapenv:Body>
    </soapenv:Envelope>
    
  3. 2. 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 \
            https://adwords.google.com/api/adwords/cm/v201402

    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="http://schemas.xmlsoap.org/soap/envelope/">
        <soap:Header>
          <ResponseHeader xmlns="https://adwords.google.com/api/adwords/cm/v201402">
            <requestId>0004e93c496104180a42fee300007f7d</requestId>
            <serviceName>CampaignService</serviceName>
            <methodName>mutate</methodName>
            <operations>0</operations>
            <responseTime>602</responseTime>
          </ResponseHeader>
        </soap:Header>
        <soap:Body>
          <mutateResponse xmlns="https://adwords.google.com/api/adwords/cm/v201402">
            <rval>
              <ListReturnValue.Type>CampaignReturnValue</ListReturnValue.Type>
              <value>
                <id>123456789</id>
                <name>Hello World</name>
                <status>PAUSED</status>
                <servingStatus>SUSPENDED</servingStatus>
                <startDate>20131021</startDate>
                <endDate>20371230</endDate>
                <budget>
                  <budgetId>987654321</budgetId>
                  <name>Interplanetary Budget #1382345043485</name>
                  <period>DAILY</period>
                  <amount>
                    <ComparableValue.Type>Money</ComparableValue.Type>
                    <microAmount>50000000</microAmount>
                  </amount>
                  <deliveryMethod>STANDARD</deliveryMethod>
                  <isExplicitlyShared>true</isExplicitlyShared>
                  <status>ACTIVE</status>
                </budget>
                <conversionOptimizerEligibility>
                  <eligible>false</eligible>
                  <rejectionReasons>CAMPAIGN_IS_NOT_ACTIVE</rejectionReasons>
                  <rejectionReasons>CONVERSION_TRACKING_NOT_ENABLED</rejectionReasons>
                </conversionOptimizerEligibility>
                <adServingOptimizationStatus>OPTIMIZE</adServingOptimizationStatus>
                <settings xsi:type="KeywordMatchSetting" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                  <Setting.Type>KeywordMatchSetting</Setting.Type>
                  <optIn>false</optIn>
                </settings>
                <settings xsi:type="GeoTargetTypeSetting" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                  <Setting.Type>GeoTargetTypeSetting</Setting.Type>
                  <positiveGeoTargetType>DONT_CARE</positiveGeoTargetType>
                </settings>
                <networkSetting>
                  <targetGoogleSearch>true</targetGoogleSearch>
                  <targetSearchNetwork>true</targetSearchNetwork>
                  <targetContentNetwork>false</targetContentNetwork>
                </networkSetting>
                <biddingStrategyConfiguration>
                  <biddingStrategyType>MANUAL_CPC</biddingStrategyType>
                  <biddingScheme xsi:type="ManualCpcBiddingScheme" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                    <BiddingScheme.Type>ManualCpcBiddingScheme</BiddingScheme.Type>
                    <enhancedCpcEnabled>false</enhancedCpcEnabled>
                  </biddingScheme>
                </biddingStrategyConfiguration>
              </value>
            </rval>
          </mutateResponse>
        </soap:Body>
      </soap:Envelope>
    

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.