Customer Match  |  Google Ads API  |  Google Developers (2022)

You can find more information on Customer Match requirements and eligibility inthe Google Ads Help Center.

Customer Match with email or mailing address

For advertisers with rich CRM databases, you can define and target audiencelists based on your CRM data. You can upload CRM data in bulk, append/removedata, or use these user lists to create alogical_user_list.

These audience lists are eligible to serve on Google Search, YouTube, Gmail,and the Google Display Network.

Per policy, you will only be allowed to upload data that you have acquiredyourself (first party). You are not allowed to buy email lists from thirdparties and upload them into the account.

For privacy concerns, email addresses, first names, and last names must behashed using the SHA-256 algorithm before being uploaded. In order tostandardize the hash results, prior to hashing one of these values you must:

  • Remove leading/trailing whitespaces.

  • Convert the text to lowercase.

Java

// Creates the first user data based on an email address.UserData userDataWithEmailAddress = UserData.newBuilder() .addUserIdentifiers( UserIdentifier.newBuilder() .setHashedEmail(normalizeAndHash(sha256Digest, "customer@example.com"))) .build();// Creates the second user data based on a physical address.UserData userDataWithPhysicalAddress = UserData.newBuilder() .addUserIdentifiers( UserIdentifier.newBuilder() .setAddressInfo( OfflineUserAddressInfo.newBuilder() .setHashedFirstName(normalizeAndHash(sha256Digest, "John")) .setHashedLastName(normalizeAndHash(sha256Digest, "Doe")) .setCountryCode("US") .setPostalCode("10011"))) .build();

AddCustomerMatchUserList.java

Video: Remarketing Using Customer Match

C#

// Creates a first user data based on an email address.UserData userDataWithEmailAddress = new UserData(){ UserIdentifiers = { new UserIdentifier() { // Hash normalized email addresses based on SHA-256 hashing algorithm. HashedEmail = NormalizeAndHash("customer@example.com") } }};// Creates a second user data based on a physical address.UserData userDataWithPhysicalAddress = new UserData(){ UserIdentifiers = { new UserIdentifier() { AddressInfo = new OfflineUserAddressInfo() { // First and last name must be normalized and hashed. HashedFirstName = NormalizeAndHash("John"), HashedLastName = NormalizeAndHash("Doe"), // Country code and zip code are sent in plain text. CountryCode = "US", PostalCode = "10011" } } }}; 

PHP

// Creates a first user data based on an email address.$userDataWithEmailAddress = new UserData([ 'user_identifiers' => [ new UserIdentifier([ // Hash normalized email addresses based on SHA-256 hashing algorithm. 'hashed_email' => self::normalizeAndHash('customer@example.com') ]) ]]);// Creates a second user data based on a physical address.$userDataWithPhysicalAddress = new UserData([ 'user_identifiers' => [ new UserIdentifier([ 'address_info' => new OfflineUserAddressInfo([ // First and last name must be normalized and hashed. 'hashed_first_name' => self::normalizeAndHash('John'), 'hashed_last_name' => self::normalizeAndHash('Doe'), // Country code and zip code are sent in plain text. 'country_code' => 'US', 'postal_code' => '10011' ]) ]) ]]); 

Python

def _build_offline_user_data_job_operations(client): """Builds and returns two sample offline user data job operations. Args: client: The Google Ads client. Returns: A list containing the operations. """ # Creates a first user data based on an email address. user_data_with_email_address_operation = client.get_type( "OfflineUserDataJobOperation" ) user_data_with_email_address = user_data_with_email_address_operation.create user_identifier_with_hashed_email = client.get_type("UserIdentifier") # Hash normalized email addresses based on SHA-256 hashing algorithm. user_identifier_with_hashed_email.hashed_email = _normalize_and_hash( "customer@example.com" ) user_data_with_email_address.user_identifiers.append( user_identifier_with_hashed_email ) # Creates a second user data based on a physical address. user_data_with_physical_address_operation = client.get_type( "OfflineUserDataJobOperation" ) user_data_with_physical_address = ( user_data_with_physical_address_operation.create ) user_identifier_with_address = client.get_type("UserIdentifier") # First and last name must be normalized and hashed. user_identifier_with_address.address_info.hashed_first_name = ( _normalize_and_hash("John") ) user_identifier_with_address.address_info.hashed_last_name = ( _normalize_and_hash("Doe") ) # Country and zip codes are sent in plain text. user_identifier_with_address.address_info.country_code = "US" user_identifier_with_address.address_info.postal_code = "10011" user_data_with_physical_address.user_identifiers.append( user_identifier_with_address ) return [ user_data_with_email_address_operation, user_data_with_physical_address_operation, ] 

Ruby

operations = []# Creates a first user data based on an email address.operations << client.operation.create_resource.offline_user_data_job do |u| u.user_identifiers << client.resource.user_identifier do |uid| # Hash normalized email addresses based on SHA-256 hashing algorithm. uid.hashed_email = normalize_and_hash("customer@example.com") endend# Creates a second user data based on a physical address.operations << client.operation.create_resource.offline_user_data_job do |u| u.user_identifiers << client.resource.user_identifier do |uid| uid.address_info = client.resource.offline_user_address_info do |a| # First and last name must be normalized and hashed. a.hashed_first_name = normalize_and_hash("John") a.hashed_last_name = normalize_and_hash("Doe") # Country code and zip code are sent in plain text. a.country_code = "US" a.postal_code = "10011" end endend

add_customer_match_user_list.rb

Video: Google Ads API Workshop - Spring 2019 - Overview

Perl

# Create a first user data based on an email address.my $user_data_with_email_address = Google::Ads::GoogleAds::V10::Common::UserData->new({ userIdentifiers => [ Google::Ads::GoogleAds::V10::Common::UserIdentifier->new({ # Hash normalized email addresses based on SHA-256 hashing algorithm. hashedEmail => normalize_and_hash('customer@example.com')})]});# Create a second user data based on a physical address.my $user_data_with_physical_address = Google::Ads::GoogleAds::V10::Common::UserData->new({ userIdentifiers => [ Google::Ads::GoogleAds::V10::Common::UserIdentifier->new({ addressInfo => Google::Ads::GoogleAds::V10::Common::OfflineUserAddressInfo->new({ # First and last name must be normalized and hashed. hashedFirstName => normalize_and_hash("John"), hashedLastName => normalize_and_hash("Doe"), # Country code and zip code are sent in plain text. countryCode => "US", postalCode => "10011" })})]}); 

Options for Customer Match in different campaign types

Search network-only campaigns
A crm_based_user_list is available. Ads will show on the search network.
Display network-only campaigns
A crm_based_user_list and its similar_user_list are available. Ads willshow on Gmail only if there are GSP creatives.
Display Expansion on Search campaigns
A crm_based_user_list is available. Ads will show on the search network andon Gmail (only if there are GSP creatives).
Video campaigns
A crm_based_user_list and its similar_user_list are available. Ads willshow on YouTube only if there are in-stream TrueView ads.

Customer Match with phone number

Similar to Customer Match with emails, you can also perform customer matchingwith phone numbers.

For privacy concerns, the phone number needs to be hashed using the SHA-256algorithm before being uploaded. In order to standardize results, convert eachphone number to E164 format before hashing.This format represents a phone number as a number up to fifteen digits in lengthstarting with a + sign (e.g. +12125650000, +442070313000).

If the phone number is not correctly formatted before hashing, the API willstill accept the hashed phone number, but the phone number will not be matchedwith a customer.

Customer Match with mobile device IDs

Similar to Customer Match with emails, you can also perform customer matchingusing IDFA (Identifier for Advertising) or AAID (Google Advertising ID) mobiledevice IDs. Note that mobile device IDs cannot be combined with any other typesof customer data.

Customer Match considerations

When implementing Customer Match, keep the following points in mind:

  • It takes 6 to 48 hours for a list to be populated with members, so you'll mostlikely see an "In Progress"status (on the Google Ads UI)if you upload to an audience list more frequently than once every 12 hours.

    If your job includes a remove_alloperation, it may run for up to 72 hours.

    Video: Making Requests to Google Ad Manager API with PHP

  • The operations collection for eachAddOfflineUserDataJobOperationsRequestcan contain at most 100,000 identifiers across all of the UserData objects in the operations.If you need to submit more than100,000 identifiers for a job, send multiple requests with the same jobresource_name.

  • When uploading store sales transactions, the following limits apply to thenumber of operations added to a job:

    • There are no limits on the number of operations you can add to a singlejob. However, for optimal processing, we recommend adding up to 10,000identifiers in a single call tothe OfflineUserDataJobService.AddOfflineUserDataJobOperationsmethod and up to 1,000,000 identifiers to a single job.
  • Do not mix create and remove operations within the sameOfflineUserDataJob. Doing so can resultin aCONFLICTING_OPERATIONerror.

  • To completely replace the members of a user list with new members, order theoperations in AddOfflineUserDataJobOperationsRequest in this sequence:

    1. Set remove_all to true in anOfflineUserDataJobOperation.
    2. For each new member, add a create operation setting their UserData inan OfflineUserDataJobOperation.

    When you run your job, the Google Ads API will first mark all current members ofthe list for removal, and then apply the create operations.

  • Operations are validated when uploaded to anOfflineUserDataJob. We recommendenabling partial_failure in anAddOfflineUserDataJobOperationsRequestso as to detect any problematic operations before running the job.

  • Errors encountered during the execution of anOfflineUserDataJob can be fetched usingthe offline_user_data_job report using the Google Ads Query Language. Note, however, thatthis report does not contain information about any failed matches; only hashesare compared when performing matches, so we cannot provide specific reasonsfor failures.

  • For privacy purposes, the user list size will show as zero until the list hasat least 1,000 members. After that, the size will be rounded to the two mostsignificant digits.

  • Upload at least 5,000 members to the list to ensure that ads start serving.

    Video: Google Ads API Webinar from May 22, 2018

  • A crm_based_user_list can only be combined with anothercrm_based_user_list when using a logical_user_list. All the policies forcrm_based_user_list will apply to the result user list.

  • If you attempt to create multiple jobs with the sameexternal_id, the requestwill fail with anEXTERNAL_UPDATE_ID_ALREADY_EXISTSerror.

  • Avoid simultaneously running multipleOfflineUserDataJob processes that modifythe same user list (that is, multiple jobs whoseCustomerMatchUserListMetadata.user_listpoint to the same resource name). Doing so can result in aCONCURRENT_MODIFICATIONerror since multiple jobs are not permitted to operate on the same list at thesame time. This error can also occur if attempting to simultaneously modify alist through the Google Ads UI and the Google Ads API. Note that this does not apply toadding operations to anexisting job, which can be done at any time before the job is started.

  • A list may appear to be smaller than expected when viewed in the AudienceManager in the Google Ads UI. This view shows the number of active users in thelist. A user is considered active if they have recently logged into theirGoogle account. For more information on active users, see this discussion onhow totroubleshoot low trafficwith Customer Match lists.

Remove data from a Customer Match audience list

There are multiple ways to remove data from a Customer Match audience list:

Remove the list itself:

  • Use the UserListService.mutate_user_lists method to submit a remove operation using the resource name of the user list you would like to remove.

Remove all data from the list at once:

  • Set remove_all to true in an OfflineUserDataJobOperation.
  • Issue a RunOfflineUserDataJob request with the resource name associated with the above remove_all operation.
  • Note that when a remove_all operation is included, it must be the first operation in a job. If not, then running the job will return an INVALID_OPERATION_ORDER error.

Remove individual users using identifiers:

  • Set the remove attribute on an OfflineUserDataJobOperation equal to a UserData object.
  • Add one or more UserIdentifiers to the user_identifiers[] repeated field.
  • A single user identifier can be used to remove a user from a list, even if more than one identifiers were submitted that match the user.
  • Note that remove operations cannot be mixed with create operations in a single job. Running such a job will fail with a CONFLICTING_OPERATION error.

Customer Match attributes (deprecated)

This was an allowlisted feature that is now obsolete.

You can no longer uploadUserData objects with attributes using anOfflineUserDataJob with the typeset to CUSTOMER_MATCH_WITH_ATTRIBUTES.

Customer Match attributes cannot be used with Customer Match user lists. Thisfeature uploads user data to the account (not in a user list), and the uploadeddata influences targeting across the account without a user list.

The current fields available in the documentation are:

Video: AdWords API DevBytes Episode 1: Why Use the AdWords API?

lifetime_value_micros
The advertiser-defined lifetime value for the user, specified in micros.
lifetime_value_bucket
A value between 1 and 10 (inclusive) that represents the lifetime valuebucket of the user, with 10 representing the highest value bucket. To clearthis attribute, provide a value of 0.

FAQs

How do customers match on Google Ads?

Customer Match lets you target ads to your customers using the data they share with you. You create a CSV file including customer data and upload it into Google Ads to incorporate this targeting into your campaigns.

Is there an API for Google Ads?

The Google Ads API lets developers create and use applications that interact directly with their account details on the Google Ads server. The API helps advertisers efficiently manage large Google Ads accounts and campaigns.

Can you create lookalike audiences in Google Ads?

Log in to your main Google Ads page and click “Audiences” in the navigation bar. Go to the “Edit audiences” section and select an ad group with the pencil icon next to it. In the “All audiences” box, select the remarketing and similar audiences, and then click on the list or lists you want to use for similar audiences.

Can I run Google Ads for clients?

You can link new and existing Google Ads accounts, as well as other manager accounts. You can then monitor ad performance, update campaigns, and manage other account tasks for those client accounts. Your manager account can also be given ownership of a client account.

How do you establish customer match audience?

How to Use Google Ads Customer Match Like a Pro - YouTube

How does Google use customer Match data?

Google Ads Customer Match lets you use the information your customers shared with you to reach them where they are. Ads are shown to your customers based on the data you share about these customers with Google.

Is Google Ads API free?

There will be no charges for AdWords API usage for either basic or standard access.

How do I create a Google ad API?

The best way to set up new ads in the API is to use the Add Expanded Text Ads code example in the Basic Operations folder of your client library. The sample handles all the background authentication tasks for you, and walks you through creating expanded text ads. // Creates the expanded text ad info.

How do I set up Google ad API?

Set up AdWords API access
  1. Step 1: Obtain a developer token.
  2. Step 2: Create test accounts.
  3. Step 3: Choose a client library.
  4. Step 4: Set up authentication via OAuth2.
  5. Step 5: Get an OAuth2 refresh token.
  6. Step 6: Make your first API call.
Jun 24, 2019

How do you set a lookalike audience?

How to create a Facebook lookalike audience
  1. Go to your Audiences. ...
  2. Select the Create Audience dropdown and choose Lookalike Audience.
  3. Choose your source. ...
  4. Choose the country/countries where you'd like to find a similar set of people.
  5. Choose your desired audience size with the slide.
  6. Select Create Audience.

What is Rlsa in Adwords?

Remarketing lists for search ads (RLSA) is a Google Ads feature that allows advertisers to tailor their search campaigns based on whether a user has previously visited their website (or app), and the pages that user viewed.

How do I create a Google ad remarketing list?

How to Create and Segment Remarketing Audiences in Google Ads:
  1. Log into Google Ads.
  2. Click on Tools & Settings in the top right corner.
  3. Click on Audience Manager under the Shared Library section. ...
  4. Click on the blue button in the top left corner to create a new audience. ...
  5. Name your audience.
Apr 6, 2020

How do I manage a client's Google ad account?

How to Connect and Manage Your Clients Accounts With Google Ads

What is CPA advertising?

CPA in marketing stands for cost per acquisition or action and is a type of conversion rate marketing. Cost per acquisition refers to the fee a company will pay for an advertisement that results in a sale.

How can I get my Google Ads customer ID?

Instructions
  1. Sign in to your Google Ads account.
  2. Click the help icon in the top right corner.
  3. Find “Customer ID” at the bottom of the menu.

Videos

1. AdWords API DevBytes Episode 3: API Basics
(Google Developers)
2. API Use Cases - Ad Manager Developer Workshop
(Google Ads Developers)
3. Google Ads API Workshop - Spring 2019 - AdWords API vs Google Ads API
(Google Ads Developers)
4. Welcome to the Google Ads API in 60 Seconds
(Google Ads Developers)
5. Website Conversions & Audience Remarketing
(Google Ads Developers)

You might also like

Latest Posts

Article information

Author: Kerri Lueilwitz

Last Updated: 03/13/2022

Views: 6220

Rating: 4.7 / 5 (47 voted)

Reviews: 86% of readers found this page helpful

Author information

Name: Kerri Lueilwitz

Birthday: 1992-10-31

Address: Suite 878 3699 Chantelle Roads, Colebury, NC 68599

Phone: +6111989609516

Job: Chief Farming Manager

Hobby: Mycology, Stone skipping, Dowsing, Whittling, Taxidermy, Sand art, Roller skating

Introduction: My name is Kerri Lueilwitz, I am a courageous, gentle, quaint, thankful, outstanding, brave, vast person who loves writing and wants to share my knowledge and understanding with you.