You can find more information on Customer Match requirements and eligibility in the Google Ads Help Center.
Customer Match with email address, address, or user ID
For advertisers with rich CRM databases, you can define and target audience
lists based on your CRM data. You can upload CRM data in bulk, append/remove
data, or use these user lists to create a
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 acquired yourself (first party). You are not allowed to buy email lists from third parties and upload them into the account.
For privacy concerns, email addresses, first names, and last names must be hashed using the SHA-256 algorithm before being uploaded. In order to standardize the hash results, prior to hashing one of these values you must:
Remove leading/trailing whitespaces.
Convert the text to lowercase.
This example is not yet available in Java; you can take a look at the other languages.
This example is not yet available in C#; you can take a look at the other languages.
// 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('email@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' ]) ]) ] ]);
This example is not yet available in Python; you can take a look at the other languages.
This example is not yet available in Ruby; you can take a look at the other languages.
This example is not yet available in Perl; you can take a look at the other languages.
Options for Customer Match in different campaign types
- Search network only campaigns
crm_based_user_listis available. Ads will show on the search network.
- Display network only campaigns
similar_user_listare available. Ads will show on Gmail only if there are GSP creatives.
- Search network with display select campaigns
crm_based_user_listis available. Ads will show on the search network and on Gmail (only if there are GSP creatives).
- Video campaigns
similar_user_listare available. Ads will show 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 matching with phone numbers.
For privacy concerns, the phone number needs to be hashed using the SHA-256
algorithm before being uploaded. In order to standardize results, convert each
phone number to E164 format before hashing.
This format represents a phone number as a number up to fifteen digits in length
starting with a
+ sign (e.g. +12125650000, +442070313000).
If the phone number is not correctly formatted before hashing, the API will still accept the hashed phone number, but the phone number will not be matched with a customer.
Customer Match with mobile device IDs
Similar to Customer Match with emails, you can also perform customer matching using IDFA (Identifier for Advertising) or AAID (Google Advertising ID) mobile device IDs. Note that mobile device IDs cannot be combined with any other types of customer data.
Customer Match attributes
Starting in v6 of the Google Ads API, you can have a Customer Match list that stores the following attributes of its members:
- The advertiser-defined lifetime value for the user, specified in micros.
- A value between
10(inclusive) that represents the lifetime value bucket of the user, with
10representing the highest value bucket.
- To clear this attribute, provide a value of
Customer Match considerations
When implementing Customer Match, keep the following points in mind:
It takes 6 to 12 hours for a list to be populated with members, so you'll most likely see an "In Progress" status (on the Google Ads UI) if you upload to an audience list more frequently than once every 12 hours.
operationscollection for each
AddOfflineUserDataJobOperationsRequestcan contain at most 100,000 elements. If you need to submit more than 100,000 operations for a job, send multiple requests with the same job
To completely replace the members of a user list with new members, order the operations in
AddOfflineUserDataJobOperationsRequestin this sequence:
- For each new member, add a
createoperation setting their
When you run your job, the Google Ads API will first mark all current members of the list for removal, and then apply the
For privacy purposes, the user list size will show as zero until the list has at least 1,000 members. After that, the size will be rounded to the two most significant digits.
Upload at least 5,000 members to the list to ensure that ads start serving.
crm_based_user_listcan only be combined with another
crm_based_user_listwhen using a
logical_user_list. All the policies for
crm_based_user_listwill apply to the result user list.
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_listsmethod to submit a
removeoperation using the resource name of the user list you would like to remove.
Remove all data from the list at once:
- Issue a
RunOfflineUserDataJobrequest with the resource name associated with the above
- Note that when a
remove_alloperation is included, it must be the first operation in a job. If not, then running the job will return an
Remove individual users using identifiers:
- Set the
removeattribute on an
OfflineUserDataJobOperationequal to a
- Add one or more
- 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
removeoperations cannot be mixed with
createoperations in a single job. Running such a job will fail with a