Google Ads API is returning to beta status. Please read our blog post for more details.

Creating an Account

To create an account, send the Google Ads API a pre-populated Customer. Unlike creating other entities like campaigns, this is done with a special CreateCustomerClient method on the CustomerService rather than a "mutate" method. In the CreateCustomerClient method, you specify the customer ID of the manager account that will be managing the new client, not the customer ID of the client being mutated as usual.

Here is code demonstrating customer creation:

Java

private void runExample(GoogleAdsClient googleAdsClient, Long managerId) {
  // Formats the current date/time to use as a timestamp in the new customer description.
  String dateTime = ZonedDateTime.now().format(DateTimeFormatter.RFC_1123_DATE_TIME);

  // Initializes a Customer object to be created.
  Customer customer = Customer.newBuilder()
      .setDescriptiveName(
          StringValue.of("Account created with CustomerService on '" + dateTime + "'"))
      .setCurrencyCode(StringValue.of("USD"))
      .setTimeZone(StringValue.of("America/New_York"))
      // Optional: Sets additional attributes of the customer.
      .setTrackingUrlTemplate(StringValue.of("{lpurl}?device={device}"))
      .setFinalUrlSuffix(
          StringValue.of("keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}"))
      .setHasPartnersBadge(BoolValue.of(false))
      .build();

  // Sends the request to create the customer.
  try (CustomerServiceClient client =
      googleAdsClient.getLatestVersion().createCustomerServiceClient()) {
    CreateCustomerClientResponse response =
        client.createCustomerClient(managerId.toString(), customer);
    System.out.printf(
        "Created a customer with resource name '%s' under the manager account with"
            + " customer ID '%d'.%n",
        response.getResourceName(), managerId);
  }
}

C#

// Copyright 2019 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

using Google.Ads.GoogleAds.Lib;
using Google.Ads.GoogleAds.V2.Errors;
using Google.Ads.GoogleAds.V2.Resources;
using Google.Ads.GoogleAds.V2.Services;

using System;

namespace Google.Ads.GoogleAds.Examples.V2
{
    /// <summary>
    /// This code example illustrates how to create a new customer under a given manager account.
    ///
    /// Note: this example must be run using the credentials of a Google Ads manager account.
    /// By default, the new account will only be accessible via the manager account.
    /// </summary>
    public class CreateCustomer : ExampleBase
    {
        /// <summary>
        /// Main method, to run this code example as a standalone application.
        /// </summary>
        /// <param name="args">The command line arguments.</param>
        public static void Main(string[] args)
        {
            CreateCustomer codeExample = new CreateCustomer();
            Console.WriteLine(codeExample.Description);

            long managerCustomerId = long.Parse("INSERT_MANAGER_CUSTOMER_ID_HERE");
            codeExample.Run(new GoogleAdsClient(), managerCustomerId);
        }

        /// <summary>
        /// Returns a description about the code example.
        /// </summary>
        public override string Description
        {
            get
            {
                return "This code example illustrates how to create a new customer under a " +
                    "given manager account.\n Note: this example must be run using the " +
                    "credentials of a Google Ads manager account. By default, the new account " +
                    "will only be accessible via the manager account.";
            }
        }

        /// <summary>
        /// Runs the code example.
        /// </summary>
        /// <param name="client">The Google Ads client.</param>
        /// <param name="managerCustomerId">The manager customer ID.</param>
        public void Run(GoogleAdsClient client, long managerCustomerId)
        {
            // Get the CustomerService.
            CustomerServiceClient customerService = client.GetService(Services.V2.CustomerService);

            Customer customer = new Customer()
            {
                DescriptiveName = $"Account created with CustomerService on '{DateTime.Now}'",

                // For a list of valid currency codes and time zones see this documentation:
                // https://developers.google.com/adwords/api/docs/appendix/codes-formats.
                CurrencyCode = "USD",
                TimeZone = "America/New_York",

                // The below values are optional. For more information about URL
                // options see: https://support.google.com/google-ads/answer/6305348.
                TrackingUrlTemplate = "{lpurl}?device={device}",
                FinalUrlSuffix = "keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}",
                HasPartnersBadge = false
            };

            try
            {
                // Create the account.
                CreateCustomerClientResponse response = customerService.CreateCustomerClient(
                    managerCustomerId.ToString(), customer);

                // Display the result.
                Console.WriteLine($"Created a customer with resource name " +
                    $"'{response.ResourceName}' under the manager account with customer " +
                    $"ID '{managerCustomerId}'");
            }
            catch (GoogleAdsException e)
            {
                Console.WriteLine("Failure:");
                Console.WriteLine($"Message: {e.Message}");
                Console.WriteLine($"Failure: {e.Failure}");
                Console.WriteLine($"Request ID: {e.RequestId}");
            }
        }
    }
}

PHP

<?php
/**
 * Copyright 2018 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

namespace Google\Ads\GoogleAds\Examples\AccountManagement;

require __DIR__ . '/../../vendor/autoload.php';

use GetOpt\GetOpt;
use Google\Ads\GoogleAds\Examples\Utils\ArgumentNames;
use Google\Ads\GoogleAds\Examples\Utils\ArgumentParser;
use Google\Ads\GoogleAds\Lib\V2\GoogleAdsClient;
use Google\Ads\GoogleAds\Lib\V2\GoogleAdsClientBuilder;
use Google\Ads\GoogleAds\Lib\V2\GoogleAdsException;
use Google\Ads\GoogleAds\Lib\OAuth2TokenBuilder;
use Google\Ads\GoogleAds\V2\Errors\GoogleAdsError;
use Google\Ads\GoogleAds\V2\Resources\Customer;
use Google\ApiCore\ApiException;
use Google\Protobuf\BoolValue;
use Google\Protobuf\StringValue;

/**
 * This example illustrates how to create a new customer under a given manager account.
 *
 * Note: this example must be run using the credentials of a Google Ads manager account. By default,
 * the new account will only be accessible via the manager account.
 */
class CreateCustomer
{
    const MANAGER_CUSTOMER_ID = 'INSERT_MANAGER_CUSTOMER_ID_HERE';

    public static function main()
    {
        // Either pass the required parameters for this example on the command line, or insert them
        // into the constants above.
        $options = (new ArgumentParser())->parseCommandArguments([
            ArgumentNames::MANAGER_CUSTOMER_ID => GetOpt::REQUIRED_ARGUMENT
        ]);

        // Generate a refreshable OAuth2 credential for authentication.
        $oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();

        // Construct a Google Ads client configured from a properties file and the
        // OAuth2 credentials above.
        $googleAdsClient = (new GoogleAdsClientBuilder())
            ->fromFile()
            ->withOAuth2Credential($oAuth2Credential)
            ->build();

        try {
            self::runExample(
                $googleAdsClient,
                $options[ArgumentNames::MANAGER_CUSTOMER_ID] ?: self::MANAGER_CUSTOMER_ID
            );
        } catch (GoogleAdsException $googleAdsException) {
            printf(
                "Request with ID '%s' has failed.%sGoogle Ads failure details:%s",
                $googleAdsException->getRequestId(),
                PHP_EOL,
                PHP_EOL
            );
            foreach ($googleAdsException->getGoogleAdsFailure()->getErrors() as $error) {
                /** @var GoogleAdsError $error */
                printf(
                    "\t%s: %s%s",
                    $error->getErrorCode()->getErrorCode(),
                    $error->getMessage(),
                    PHP_EOL
                );
            }
        } catch (ApiException $apiException) {
            printf(
                "ApiException was thrown with message '%s'.%s",
                $apiException->getMessage(),
                PHP_EOL
            );
        }
    }

    /**
     * Runs the example.
     *
     * @param GoogleAdsClient $googleAdsClient the Google Ads API client
     * @param int $managerCustomerId the manager customer ID
     */
    public static function runExample(GoogleAdsClient $googleAdsClient, int $managerCustomerId)
    {
        $customer = new Customer([
            'descriptive_name' => new StringValue(
                ['value' => 'Account created with CustomerService on ' . date('Ymd h:i:s')]
            ),
            // For a list of valid currency codes and time zones see this documentation:
            // https://developers.google.com/adwords/api/docs/appendix/codes-formats.
            'currency_code' => new StringValue(['value' => 'USD']),
            'time_zone' => new StringValue(['value' => 'America/New_York']),
            // The below values are optional. For more information about URL
            // options see: https://support.google.com/google-ads/answer/6305348.
            'tracking_url_template' => new StringValue(['value' => '{lpurl}?device={device}']),
            'final_url_suffix' => new StringValue([
                    'value' => 'keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}'
            ]),
            'has_partners_badge' => new BoolValue(['value' => false])
        ]);

        // Issues a mutate request to create an account
        $customerServiceClient = $googleAdsClient->getCustomerServiceClient();
        $response = $customerServiceClient->createCustomerClient($managerCustomerId, $customer);

        printf(
            'Created a customer with resource name "%s" under the manager account with '
            . 'customer ID %d.%s',
            $response->getResourceName(),
            $managerCustomerId,
            PHP_EOL
        );
    }
}

CreateCustomer::main();

Python

def main(client, manager_customer_id):
    customer_service = client.get_service('CustomerService', version='v2')
    customer = client.get_type('Customer', version='v2')
    today = datetime.today().strftime('%Y%m%d %H:%M:%S')
    customer.descriptive_name.value = ('Account created with '
                                       'CustomerService on %s' % today)
    # For a list of valid currency codes and time zones see this documentation:
    # https://developers.google.com/adwords/api/docs/appendix/codes-formats
    customer.currency_code.value = 'USD'
    customer.time_zone.value = 'America/New_York'
    # The below values are optional. For more information about URL
    # options see: https://support.google.com/google-ads/answer/6305348
    customer.tracking_url_template.value = '{lpurl}?device={device}'
    customer.final_url_suffix.value = ('keyword={keyword}&matchtype={matchtype}'
                                       '&adgroupid={adgroupid}')
    customer.has_partners_badge.value = False

    try:
        response = customer_service.create_customer_client(
            manager_customer_id, customer)
        print(('Customer created with resource name "%s" under manager account '
               'with customer ID "%s"') %
               (response.resource_name, manager_customer_id))
    except google.ads.google_ads.errors.GoogleAdsException as ex:
        print('Request with ID "%s" failed with status "%s" and includes the '
              'following errors:' % (ex.request_id, ex.error.code().name))
        for error in ex.failure.errors:
            print('\tError with message "%s".' % error.message)
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print('\t\tOn field: %s' % field_path_element.field_name)
        sys.exit(1)

Ruby

def create_customer(manager_customer_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  customer = client.resource.customer do |c|
    c.descriptive_name = "Account created with CustomerService on #{(Time.new.to_f * 1000).to_i}"

    # For a list of valid currency codes and time zones, see this documentation:
    # https://developers.google.com/adwords/api/docs/appendix/codes-formats
    c.currency_code = "USD"
    c.time_zone = "America/New_York"

    # The below values are optional. For more information about URL options, see:
    # https://support.google.com/google-ads/answer/6305348
    c.tracking_url_template = "{lpurl}?device={device}"
    c.final_url_suffix = "keyword={keyword}&matchtype={matchtype}&adgroupid={adgroupid}"

    c.has_partners_badge = false
  end

  response = client.service.customer.create_customer_client(manager_customer_id, customer)

  puts "Created a customer with resource name #{response.resource_name} under" +
      " the manager account with customer ID #{manager_customer_id}."
end

Send feedback about...

Google Ads API Beta
Google Ads API Beta
Need help? Visit our support page.