Customer Match

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

OfflineUserDataJobService and UserDataService

There are two services available to upload Customer Match data. Carefully choose the service based on your use case as there can be limitations for a service.

Customer Match with email or mailing address

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 logical_user_list.

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

Per policy, you are only 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, make sure you perform the following tasks:

• Remove leading and trailing whitespaces.
• Convert text to lowercase.
• You're not required to remove all periods (.) preceding the domain name in gmail.com and googlemail.com email addresses since they'll still be accepted.

Code example

// 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
      

// 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"
            }
        }
    }
};
AddCustomerMatchUserList.cs
      

// 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'
            ])
        ])
    ]
]);
AddCustomerMatchUserList.php
      

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,
    ]
add_customer_match_user_list.py
      

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")
  end
end

# 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
  end
end
add_customer_match_user_list.rb
      

# Create a first user data based on an email address.
my $user_data_with_email_address =
  Google::Ads::GoogleAds::V12::Common::UserData->new({
    userIdentifiers => [
      Google::Ads::GoogleAds::V12::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::V12::Common::UserData->new({
    userIdentifiers => [
      Google::Ads::GoogleAds::V12::Common::UserIdentifier->new({
          addressInfo =>
            Google::Ads::GoogleAds::V12::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"
            })})]});
add_customer_match_user_list.pl
      

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 will show 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 and on Gmail (only if there are GSP creatives).

Video campaigns

A crm_based_user_list and its similar_user_list are 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 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 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.

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

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

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

  • There are no limits on the number of operations you can add to a single job. However, for optimal processing, we recommend adding up to 10,000 identifiers in a single call to the OfflineUserDataJobService.AddOfflineUserDataJobOperations method and up to 1,000,000 identifiers to a single job.

• Do not mix create and remove operations within the same OfflineUserDataJob. Doing so can result in a CONFLICTING_OPERATION error.

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

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

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

• Operations are validated when uploaded to an OfflineUserDataJob. We recommend enabling partial_failure in an AddOfflineUserDataJobOperationsRequest so as to detect any problematic operations before running the job.

• Errors encountered during the execution of an OfflineUserDataJob can be fetched using the offline_user_data_job report using the Google Ads Query Language. Note, however, that this report does not contain information about any failed matches; only hashes are compared when performing matches, so we cannot provide specific reasons for failures.

• 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.

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

• If you attempt to create multiple jobs with the same external_id, the request will fail with an EXTERNAL_UPDATE_ID_ALREADY_EXISTS error.

• Avoid simultaneously running multiple OfflineUserDataJob processes that modify the same user list (that is, multiple jobs whose CustomerMatchUserListMetadata.user_list point to the same resource name). Doing so can result in a CONCURRENT_MODIFICATION error since multiple jobs are not permitted to operate on the same list at the same time. This error can also occur if attempting to simultaneously modify a list through the Google Ads UI and the Google Ads API. Note that this does not apply to adding operations to an existing 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 Audience Manager in the Google Ads UI. This view shows the number of active users in the list. A user is considered active if they have recently logged into their Google account. For more information on active users, see this discussion on how to troubleshoot low traffic with 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 upload UserData objects with attributes using an OfflineUserDataJob with the type set to CUSTOMER_MATCH_WITH_ATTRIBUTES.

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

The current fields available in the documentation are:

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 value bucket of the user, with 10 representing the highest value bucket. To clear this attribute, provide a value of 0.