Share your feedback about the Google Ads (AdWords) API. Take the 2021 AdWords API and Google Ads API Annual Survey.

The AdWords API will sunset on April 27, 2022. Migrate to the Google Ads API to take advantage of the latest Google Ads features.

Template Ads

Template ads provide a flexible way of introducing new ad formats in addition to the specific ad types built into the AdWords API.

A template ad is comprised of a template (specified by the template ID) and the data that populates the template's fields. With template ads, you can create an ad that's not available as a concrete ad type, such as Gmail ads, YouTube Promoted Video ads, and many others. See the Template Ad reference data page for a full list of supported template ads.

Once you've created a template ad, you can make copies of the ad by referring to its originadid instead of re-uploading the same media.

This guide describes how to get started with a few different kinds of template ads.

App Promotion Ads

You can use the AdWords API to create mobile app promotion ads. Below is a sample SOAP request for creating an app promotion ad:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Header>
    <RequestHeader xmlns="https://adwords.google.com/api/adwords/cm/v201809">
      <clientCustomerId>...</clientCustomerId>
      <developerToken>...</developerToken>
      <userAgent>...</userAgent>
    </RequestHeader>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <mutate xmlns="https://adwords.google.com/api/adwords/cm/v201809">
      <operations>
        <operator>ADD</operator>
        <operand>
          <adGroupId>XXXXX</adGroupId>
          <ad xsi:type="TemplateAd">
            <url>http://play.google.com/store/apps/details?id=INSERT_ANDROID_APP_PACKAGE_HERE</url>
            <displayUrl>play.google.com/store</displayUrl>
            <templateId>353</templateId>
            <templateElements>
              <uniqueName>adData</uniqueName>
              <fields>
                <name>appId</name>
                <type>TEXT</type>
                <fieldText>XXXXX</fieldText>
              </fields>
              <fields>
                <name>appStore</name>
                <type>ENUM</type>
                <fieldText>XXXXX</fieldText>
              </fields>
              <fields>
                <name>headline</name>
                <type>TEXT</type>
                <fieldText>My awesome app</fieldText>
              </fields>
              <fields>
                <name>description1</name>
                <type>TEXT</type>
                <fieldText>Must download</fieldText>
              </fields>
              <fields>
                <name>description2</name>
                <type>TEXT</type>
                <fieldText>Best app ever</fieldText>
              </fields>
            </templateElements>
            <name>My App Promotion Ad</name>
          </ad>
          <status>ENABLED</status>
        </operand>
      </operations>
    </mutate>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

You can create app reengagement ads for Search Network app engagement campaigns. These are ads targeted at users who have already installed your app.

An app reengagement ad has a deep link to a specific action in your app to encourage users to perform the action.

Below is a sample SOAP request for creating an app reengagement ad:

<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:mustUnderstand="0">
      <ns1:clientCustomerId>...</ns1:clientCustomerId>
      <ns1:developerToken>...</ns1:developerToken>
      <ns1:userAgent>...</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>
          <adGroupId>XXXXX</adGroupId>
          <ad xmlns:ns2="https://adwords.google.com/api/adwords/cm/v201809" xsi:type="ns2:TemplateAd">
            <!-- Deep link -->
            <url>android-app://com.example.android/exampleapp/productid_1234</url>
            <displayUrl>example.com</displayUrl>
            <templateId>453</templateId>
            <templateElements>
              <uniqueName>adData</uniqueName>
              <fields>
                <name>appStore</name>
                <type>ENUM</type>
                <fieldText>2</fieldText>
              </fields>
              <fields>
                <name>appId</name>
                <type>TEXT</type>
                <fieldText>com.example.app</fieldText>
              </fields>
              <fields>
                <name>headline</name>
                <type>TEXT</type>
                <fieldText>Intergalactic cruise</fieldText>
              </fields>
              <fields>
                <name>description1</name>
                <type>TEXT</type>
                <fieldText>Free pretzels</fieldText>
              </fields>
              <fields>
                <name>description2</name>
                <type>TEXT</type>
                <fieldText>In-flight movies available</fieldText>
              </fields>
            </templateElements>
            <name>My App Reengagement Ad</name>
          </ad>
          <status>ENABLED</status>
        </operand>
      </operations>
    </mutate>
  </soapenv:Body>
</soapenv:Envelope>

Gmail Ads

The following sections describe how to create several different types of Gmail ads.

Gmail Image Ad

Below is a sample SOAP request for creating a Gmail image ad:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Header>
    <RequestHeader xmlns="https://adwords.google.com/api/adwords/cm/v201809">
      <clientCustomerId>...</clientCustomerId>
      <developerToken>...</developerToken>
      <userAgent>...</userAgent>
    </RequestHeader>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <mutate xmlns="https://adwords.google.com/api/adwords/cm/v201809">
        <operations>
            <operator>ADD</operator>
            <operand>
                <adGroupId>XXXXX</adGroupId>
                <ad xmlns:ns2="https://adwords.google.com/api/adwords/cm/v201809" xsi:type="ns2:TemplateAd">
                    <displayUrl>www.example.com</displayUrl>
                    <finalUrls>http://www.example.com</finalUrls>
                    <templateId>459</templateId>
                    <templateElements>
                        <uniqueName>adData</uniqueName>
                        <fields>
                            <name>layout</name>
                            <type>ENUM</type>
                            <fieldText>gmail_image_ad_v1</fieldText>
                        </fields>
                        <fields>
                            <name>image</name>
                            <type>IMAGE</type>
                            <fieldMedia xsi:type="ns2:Image">
                                <data>INSERT_BASE_64_ENCODED_BYTES_FROM_IMAGE_FILE_HERE</data>
                            </fieldMedia>
                        </fields>
                        <fields>
                            <name>description</name>
                            <type>TEXT</type>
                            <fieldText>Round trip to Mars</fieldText>
                        </fields>
                        <fields>
                            <name>subject</name>
                            <type>TEXT</type>
                            <fieldText>Intergalactic cruise</fieldText>
                        </fields>
                        <fields>
                            <name>advertiser</name>
                            <type>TEXT</type>
                            <fieldText>Intergalactic Cruises, Inc.</fieldText>
                        </fields>
                        <fields>
                            <name>logo</name>
                            <type>IMAGE</type>
                            <fieldMedia xsi:type="ns2:Image">
                                <data>INSERT_BASE_64_ENCODED_BYTES_FROM_IMAGE_FILE_HERE</data>
                            </fieldMedia>
                        </fields>
                    </templateElements>
                    <name>Gmail image ad</name>
                </ad>
                <status>PAUSED</status>
            </operand>
        </operations>
    </mutate>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Gmail Single Promotion Ad

Below is a sample SOAP request for creating a Gmail single promotion ad:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Header>
    <RequestHeader xmlns="https://adwords.google.com/api/adwords/cm/v201809">
      <clientCustomerId>...</clientCustomerId>
      <developerToken>...</developerToken>
      <userAgent>...</userAgent>
    </RequestHeader>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <mutate xmlns="https://adwords.google.com/api/adwords/cm/v201809">
        <operations>
            <operator>ADD</operator>
            <operand>
                <adGroupId>XXXXX</adGroupId>
                <ad xmlns:ns2="https://adwords.google.com/api/adwords/cm/v201809" xsi:type="ns2:TemplateAd">
                    <displayUrl>www.example.com</displayUrl>
                    <finalUrls>http://www.example.com</finalUrls>
                    <templateId>464</templateId>
                    <templateElements>
                        <uniqueName>adData</uniqueName>
                        <fields>
                            <name>layout</name>
                            <type>ENUM</type>
                            <fieldText>gmail_single_promotion_ad_v1</fieldText>
                        </fields>
                        <fields>
                            <name>callToActionUrl1</name>
                            <type>URL</type>
                            <fieldText>http://www.example.com/booktrip</fieldText>
                        </fields>
                        <fields>
                            <name>callToActionButton1ButtonColor</name>
                            <type>ENUM</type>
                            <fieldText>#4486f8</fieldText>
                        </fields>
                        <fields>
                            <name>callToActionButton1TextColor</name>
                            <type>ENUM</type>
                            <fieldText>#ffffff</fieldText>
                        </fields>
                        <fields>
                            <name>callToActionButton1</name>
                            <type>TEXT</type>
                            <fieldText>Book trip</fieldText>
                        </fields>
                        <fields>
                            <name>content</name>
                            <type>TEXT</type>
                            <fieldText>Great deals on Venus</fieldText>
                        </fields>
                        <fields>
                            <name>headlineTextColor</name>
                            <type>ENUM</type>
                            <fieldText>#4486f9</fieldText>
                        </fields>
                        <fields>
                            <name>headline</name>
                            <type>TEXT</type>
                            <fieldText>Book now</fieldText>
                        </fields>
                        <fields>
                            <name>image</name>
                            <type>IMAGE</type>
                            <fieldMedia xsi:type="ns2:Image">
                                <data>INSERT_BASE_64_ENCODED_BYTES_FROM_IMAGE_FILE_HERE</data>
                            </fieldMedia>
                        </fields>
                        <fields>
                            <name>description</name>
                            <type>TEXT</type>
                            <fieldText>Space flights</fieldText>
                        </fields>
                        <fields>
                            <name>subject</name>
                            <type>TEXT</type>
                            <fieldText>Intergalactic cruises</fieldText>
                        </fields>
                        <fields>
                            <name>advertiser</name>
                            <type>TEXT</type>
                            <fieldText>Intergalactic Cruises, Inc.</fieldText>
                        </fields>
                        <fields>
                            <name>logo</name>
                            <type>IMAGE</type>
                            <fieldMedia xsi:type="ns2:Image">
                                <data>INSERT_BASE_64_ENCODED_BYTES_FROM_IMAGE_FILE_HERE</data>
                            </fieldMedia>
                        </fields>
                    </templateElements>
                    <name>Gmail single promotion ad</name>
                </ad>
                <status>PAUSED</status>
            </operand>
        </operations>
    </mutate>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Gmail multi-product Ad

Below is a sample SOAP request for creating a Gmail multi-product ad:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Header>
    <RequestHeader xmlns="https://adwords.google.com/api/adwords/cm/v201809">
      <clientCustomerId>...</clientCustomerId>
      <developerToken>...</developerToken>
      <userAgent>...</userAgent>
    </RequestHeader>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <mutate xmlns="https://adwords.google.com/api/adwords/cm/v201809">
        <operations>
            <operator>ADD</operator>
            <operand>
                <adGroupId>XXXXX</adGroupId>
                <ad xmlns:ns2="https://adwords.google.com/api/adwords/cm/v201809" xsi:type="ns2:TemplateAd">
                    <displayUrl>www.example.com</displayUrl>
                    <finalUrls>http://www.example.com</finalUrls>
                    <templateId>466</templateId>
                    <templateElements>
                        <uniqueName>adData</uniqueName>
                        <fields>
                            <name>layout</name>
                            <type>ENUM</type>
                            <fieldText>gmail_multi_product_ad_v1</fieldText>
                        </fields>
                        <fields>
                            <name>content</name>
                            <type>TEXT</type>
                            <fieldText>Choose your destination</fieldText>
                        </fields>
                        <fields>
                            <name>headlineTextColor</name>
                            <type>ENUM</type>
                            <fieldText>#4486f9</fieldText>
                        </fields>
                        <fields>
                            <name>headline</name>
                            <type>TEXT</type>
                            <fieldText>Multiple destinations available</fieldText>
                        </fields>
                        <fields>
                            <name>header</name>
                            <type>IMAGE</type>
                            <fieldMedia xsi:type="ns2:Image">
                                <data>INSERT_BASE_64_ENCODED_BYTES_FROM_IMAGE_FILE_HERE</data>
                            </fieldMedia>
                        </fields>
                        <fields>
                            <name>product_5_buttonColor</name>
                            <type>ENUM</type>
                            <fieldText>#4486f8</fieldText>
                        </fields>
                        <fields>
                            <name>product_5_buttonTextColor</name>
                            <type>ENUM</type>
                            <fieldText>#ffffff</fieldText>
                        </fields>
                        <fields>
                            <name>product_5_titleColor</name>
                            <type>ENUM</type>
                            <fieldText>#000000</fieldText>
                        </fields>
                        <fields>
                            <name>product_4_buttonColor</name>
                            <type>ENUM</type>
                            <fieldText>#4486f8</fieldText>
                        </fields>
                        <fields>
                            <name>product_4_buttonTextColor</name>
                            <type>ENUM</type>
                            <fieldText>#ffffff</fieldText>
                        </fields>
                        <fields>
                            <name>product_4_titleColor</name>
                            <type>ENUM</type>
                            <fieldText>#000000</fieldText>
                        </fields>
                        <fields>
                            <name>product_3_buttonColor</name>
                            <type>ENUM</type>
                            <fieldText>#4486f8</fieldText>
                        </fields>
                        <fields>
                            <name>product_3_buttonTextColor</name>
                            <type>ENUM</type>
                            <fieldText>#ffffff</fieldText>
                        </fields>
                        <fields>
                            <name>product_3_titleColor</name>
                            <type>ENUM</type>
                            <fieldText>#000000</fieldText>
                        </fields>
                        <fields>
                            <name>product_2_buttonColor</name>
                            <type>ENUM</type>
                            <fieldText>#4486f8</fieldText>
                        </fields>
                        <fields>
                            <name>product_2_buttonTextColor</name>
                            <type>ENUM</type>
                            <fieldText>#ffffff</fieldText>
                        </fields>
                        <fields>
                            <name>product_2_titleColor</name>
                            <type>ENUM</type>
                            <fieldText>#000000</fieldText>
                        </fields>
                        <fields>
                            <name>product_1_buttonColor</name>
                            <type>ENUM</type>
                            <fieldText>#4486f8</fieldText>
                        </fields>
                        <fields>
                            <name>product_1_buttonTextColor</name>
                            <type>ENUM</type>
                            <fieldText>#ffffff</fieldText>
                        </fields>
                        <fields>
                            <name>product_1_titleColor</name>
                            <type>ENUM</type>
                            <fieldText>#000000</fieldText>
                        </fields>
                        <fields>
                            <name>product_0_buttonColor</name>
                            <type>ENUM</type>
                            <fieldText>#4486f8</fieldText>
                        </fields>
                        <fields>
                            <name>product_0_buttonTextColor</name>
                            <type>ENUM</type>
                            <fieldText>#ffffff</fieldText>
                        </fields>
                        <fields>
                            <name>product_0_titleColor</name>
                            <type>ENUM</type>
                            <fieldText>#000000</fieldText>
                        </fields>
                        <fields>
                            <name>product_1_buttonText</name>
                            <type>TEXT</type>
                            <fieldText>Cruise to Venus</fieldText>
                        </fields>
                        <fields>
                            <name>product_1_buttonUrl</name>
                            <type>URL</type>
                            <fieldText>http://www.example.com/venus</fieldText>
                        </fields>
                        <fields>
                            <name>product_1_title</name>
                            <type>TEXT</type>
                            <fieldText>Book Venus trip</fieldText>
                        </fields>
                        <fields>
                            <name>product_1_image</name>
                            <type>IMAGE</type>
                            <fieldMedia xsi:type="ns2:Image">
                                <data>INSERT_BASE_64_ENCODED_BYTES_FROM_IMAGE_FILE_HERE</data>
                            </fieldMedia>
                        </fields>
                        <fields>
                            <name>product_0_buttonText</name>
                            <type>TEXT</type>
                            <fieldText>Cruise to Mars</fieldText>
                        </fields>
                        <fields>
                            <name>product_0_buttonUrl</name>
                            <type>URL</type>
                            <fieldText>http://www.example.com/mars</fieldText>
                        </fields>
                        <fields>
                            <name>product_0_title</name>
                            <type>TEXT</type>
                            <fieldText>Book Mars trip</fieldText>
                        </fields>
                        <fields>
                            <name>product_0_image</name>
                            <type>IMAGE</type>
                            <fieldMedia xsi:type="ns2:Image">
                                <data>INSERT_BASE_64_ENCODED_BYTES_FROM_IMAGE_FILE_HERE</data>
                            </fieldMedia>
                        </fields>
                        <fields>
                            <name>description</name>
                            <type>TEXT</type>
                            <fieldText>Travel to your favorite planet</fieldText>
                        </fields>
                        <fields>
                            <name>subject</name>
                            <type>TEXT</type>
                            <fieldText>Intergalactic cruises</fieldText>
                        </fields>
                        <fields>
                            <name>advertiser</name>
                            <type>TEXT</type>
                            <fieldText>Intergalactic Cruises, Inc.</fieldText>
                        </fields>
                        <fields>
                            <name>logo</name>
                            <type>IMAGE</type>
                            <fieldMedia xsi:type="ns2:Image">
                                <data>INSERT_BASE_64_ENCODED_BYTES_FROM_IMAGE_FILE_HERE</data>
                            </fieldMedia>
                        </fields>
                    </templateElements>
                    <name>Gmail multi-product ad</name>
                </ad>
                <status>PAUSED</status>
            </operand>
        </operations>
    </mutate>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

HTML5 Ads

You can use the API to create HTML5 ads.

Below is a sample SOAP request for creating an HTML5 ad using a ZIP file as the source:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Header>
    <RequestHeader xmlns="https://adwords.google.com/api/adwords/cm/v201809">
      <clientCustomerId>...</clientCustomerId>
      <developerToken>...</developerToken>
      <userAgent>...</userAgent>
    </RequestHeader>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <mutate xmlns="https://adwords.google.com/api/adwords/cm/v201809">
      <operations>
        <operator>ADD</operator>
        <operand>
          <adGroupId>XXXXX</adGroupId>
            <ad xsi:type="TemplateAd">
            <displayUrl>www.example.com/html5</displayUrl>
            <finalUrls>http://example.com/html5</finalUrls>
            <templateId>419</templateId>
            <templateElements>
              <uniqueName>adData</uniqueName>
              <fields>
                <name>Custom_layout</name>
                <type>MEDIA_BUNDLE</type>
                <fieldMedia xsi:type="MediaBundle">
                  <type>MEDIA_BUNDLE</type>
                  <data>INSERT_BASE_64_ENCODED_BYTES_FROM_ZIP_FILE_HERE</data>
                  <entryPoint>carousel/index.html</entryPoint>
                </fieldMedia>
              </fields>
              <fields>
                <name>layout</name>
                <type>ENUM</type>
                <fieldText>Custom</fieldText>
              </fields>
            </templateElements>
            <dimensions>
              <width>300</width>
              <height>250</height>
            </dimensions>
            <name>Ad for HTML5</name>
          </ad>
          <status>ENABLED</status>
        </operand>
      </operations>
    </mutate>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

HTML5 Media Bundles

You can upload HTML5 media bundles, such as ZIP files containing HTML5 content, using the MediaService.

Below is a sample request uploading HTML5 content using the MediaService:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SOAP-ENV:Header>
    <RequestHeader xmlns="https://adwords.google.com/api/adwords/cm/v201809">
      <clientCustomerId>...</clientCustomerId>
      <developerToken>...</developerToken>
      <userAgent>...</userAgent>
    </RequestHeader>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <upload xmlns="https://adwords.google.com/api/adwords/cm/v201809">
      <media xsi:type="MediaBundle">
        <type>MEDIA_BUNDLE</type>
        <data>INSERT_BASE_64_ENCODED_BYTES_FROM_ZIP_FILE_HERE</data>
      </media>
    </upload>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>