API Call Structure

This guide describes the elements of an API call and demonstrates making a basic call using cURL.

If you're using a client library or a SOAP library to interact with the API, you probably won't need to worry about the underlying SOAP and XML. However, knowing a bit about them can come in handy when testing and debugging.

Making calls to the API involves sending HTTPS POST requests to a service and interpreting the response. The body of the request and response is comprised of XML defined by a WSDL.

WSDL elements

You can print the WSDL by appending a ?wsdl to the service URL:

https://adwords.google.com/api/adwords/cm/v201809/CampaignService?wsdl.

Request headers

HTTP headers accompany the SOAP+XML body in the request:

Authorization: You need to include an OAuth2 access token in the form of Authorization : Bearer access-token that identifies either a manager account 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. Note that our client libraries automatically refresh expired tokens.
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, for example, example.com:ReportDownloader:V7.18.
clientCustomerId: Customer ID of the target Google Ads account, typically in the form of 123-456-7890. Required for all calls to all services except 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 and available for only some services): If set to true, the service will perform all operations that are free of errors, and return the errors for the failing operations. This header is ignored for non-mutate operations.

Response headers

The following headers are returned with the response XML. We recommend that you log these values for debugging purposes.

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.

API call example

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

Request

Get your OAuth2 client ID and client secret (if you haven't done so already). Follow the instructions in the OAuth2 guide.

Get an OAuth2 access token. To request your access token from OAuth2, enter your OAuth2 client ID in the following URL, and paste it in your browser:

https://accounts.google.com/o/oauth2/auth?client_id=client-id&response_type=code&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fadwords&redirect_uri=urn:ietf:wg:oauth:2.0:oob&access_type=offline&prompt=consent

A screen appears where you grant your application access to your Google Ads data:

After you accept the request, you'll receive an authorization code that can be exchanged for an access token.

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

curl \
  -d code=authorization-code \
  -d client_id=client-id \
  -d client_secret=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 access token. The access token is what you need when sending requests to AdWords API services.

{
"access_token" : "ya29.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"token_type" : "Bearer",
"expires_in" : 3600,
"refresh_token" : "1/Ixxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Create a SOAP request. The following sample XML snippet 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. The XML elements are defined in the WSDL.

<?xml version="1.0"?>
<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 xmlns:ns1="https://adwords.google.com/api/adwords/cm/v201809" soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="0">
      <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/v201809">
      <operations>
        <operator>ADD</operator>
        <operand>
          <name>Hello World</name>
          <status>PAUSED</status>
          <budget>
            <budgetId>YOUR_BUDGET_ID</budgetId>
          </budget>
          <settings xmlns:ns2="https://adwords.google.com/api/adwords/cm/v201809" xsi:type="ns2:GeoTargetTypeSetting">
            <positiveGeoTargetType>DONT_CARE</positiveGeoTargetType>
          </settings>
          <advertisingChannelType>SEARCH</advertisingChannelType>
          <networkSetting>
            <targetGoogleSearch>true</targetGoogleSearch>
            <targetSearchNetwork>true</targetSearchNetwork>
            <targetContentNetwork>false</targetContentNetwork>
          </networkSetting>
          <biddingStrategyConfiguration>
            <biddingScheme xmlns:ns4="https://adwords.google.com/api/adwords/cm/v201809" xsi:type="ns4:ManualCpcBiddingScheme">
              <enhancedCpcEnabled>false</enhancedCpcEnabled>
            </biddingScheme>
          </biddingStrategyConfiguration>
        </operand>
      </operations>
    </mutate>
  </soapenv:Body>
</soapenv:Envelope>

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 access-token" \
     --data @hello_world.xml \
       https://adwords.google.com/api/adwords/cm/v201809/CampaignService

Response

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"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <ResponseHeader xmlns="https://adwords.google.com/api/adwords/cm/v201809">
      <requestId>00053282f54911280ac10da199076e99</requestId>
      <serviceName>CampaignService</serviceName>
      <methodName>mutate</methodName>
      <operations>1</operations>
      <responseTime>269</responseTime>
    </ResponseHeader>
  </soap:Header>
  <soap:Body>
    <mutateResponse xmlns="https://adwords.google.com/api/adwords/cm/v201809">
      <rval>
        <ListReturnValue.Type>CampaignReturnValue</ListReturnValue.Type>
        <value>
          <id>123456789</id>
          <name>Hello World</name>
          <status>PAUSED</status>
          <servingStatus>SUSPENDED</servingStatus>
          <startDate>20160510</startDate>
          <endDate>20371230</endDate>
          <budget>
            <budgetId>YOUR_BUDGET_ID</budgetId>
            <name>...</name>
            <amount>
              <ComparableValue.Type>Money</ComparableValue.Type>
              <microAmount>50000000</microAmount>
            </amount>
            <deliveryMethod>STANDARD</deliveryMethod>
            <isExplicitlyShared>true</isExplicitlyShared>
            <status>ENABLED</status>
          </budget>
          <conversionOptimizerEligibility>
            <eligible>false</eligible>
            <rejectionReasons>NOT_ENOUGH_CONVERSIONS</rejectionReasons>
          </conversionOptimizerEligibility>
          <adServingOptimizationStatus>OPTIMIZE</adServingOptimizationStatus>
          <settings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="GeoTargetTypeSetting">
            <Setting.Type>GeoTargetTypeSetting</Setting.Type>
            <positiveGeoTargetType>DONT_CARE</positiveGeoTargetType>
          </settings>
          <advertisingChannelType>SEARCH</advertisingChannelType>
          <networkSetting>
            <targetGoogleSearch>true</targetGoogleSearch>
            <targetSearchNetwork>true</targetSearchNetwork>
            <targetContentNetwork>false</targetContentNetwork>
            <targetPartnerSearchNetwork>false</targetPartnerSearchNetwork>
          </networkSetting>
          <biddingStrategyConfiguration>
            <biddingStrategyType>MANUAL_CPC</biddingStrategyType>
            <biddingScheme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ManualCpcBiddingScheme">
              <BiddingScheme.Type>ManualCpcBiddingScheme</BiddingScheme.Type>
              <enhancedCpcEnabled>false</enhancedCpcEnabled>
            </biddingScheme>
          </biddingStrategyConfiguration>
          <campaignTrialType>BASE</campaignTrialType>
          <baseCampaignId>123456789</baseCampaignId>
        </value>
      </rval>
    </mutateResponse>
  </soap:Body>
</soap:Envelope>