Google Data Manager API Customer Match tag

The Google Data Manager API Customer Match tag allows you to send audience data to Google advertising platforms through the Data Manager API. With this tag, you can manage your Customer Match lists by adding or removing users.

• Automatically manage Customer Lists in Google Ads/Display & Video 360. With the Google Data Manager API Customer Match tag, you can automate the creation and update of Customer Match lists. So, you won't need to repeat manual uploads of CVS files with audience data.
• Improved ad audience targeting. When first-party data is provided to Google Ads/Display & Video 360, the platform analyzes the information and generates audience lists that can be used in campaigns to reach high-intent audiences.
• Build detailed audience segments. Using the Google Data Manager API Customer Match tag,  advertisers can transform first-party customer data into audience segments that can be included or excluded during campaign targeting.

To configure the tag, you will need to complete the following steps:

• Configured the server GTM container.
• Set up data transfer from the web to the server GTM container. You can set it up using server-side Google Analytics 4 or Data Tag/Data Client.

Choose and set up an authentication method:

• Use Stape's connection (recommended) - the easiest way to manage authentication. Simply enable the Data Manager API Connection in your Stape admin account.
• Use your own Google credentials - select this option if you are not using Stape's services or are on Stape's free plan.

Select your preferred authentication option and follow the instructions.

1. Add the Google Data Manager API Customer Match tag to your server GTM Workspace.

Open your Server GTM container. Navigate to Templates → next to Tag Templates, click Search Gallery. Find Google Data Manager API Customer Match and click Add to Workspace.

2. Create a new tag. Go to Tags → click New. Select Google Data Manager API Customer Match as the tag configuration.

3. Configure a tag.

3.1 Action - choose the action for the tag. For this guide, we select Add to Customer List. You can also choose to remove users from a customer list.

3.2 Authentication Type - opt for the option selected in the prerequisites section.

• Stape Google Connection - an easier way to establish the connection with the Data Manager API. It can be enabled within the Stape container settings, in the Connections section.
• Own Google Credentials - a more complicated type of auth. Use this authentication method only if you want to authenticate with your own Google Cloud credentials instead of using the Stape Google Connection. This option relies on Google Cloud Application Default Credentials (ADC), which automatically discovers and uses credentials available in the server environment.

If you haven’t configured one of the authentication types, please refer to the detailed instructions in the prerequisites section of this guide.

3.3 Product - select from the list the platform you configure Customer List for - Google Ads, or Display and Video 360.

3.4 Operating customer ID - enter the Google Ads account ID that will receive conversions. To find it: sign in to Google Ads → click your profile picture (top-right) → copy the value. Ensure this matches the account used for the Data Manager API connection.

Important: remove hyphens before using it.

3.5 Customer ID - ID of the account used for authorization.

• If you're using your customer account, use the customer account ID.
• If you access the customer account through a manager account, use the manager account ID.

Remove hyphens before using it.

3.6 Customer List Name - specify the customer list to interact with. Only lists created via Stape are supported.

The audience name format in Google products: stape_<Customer List Name> (e.g., entering “Purchasers” maps to stape_Purchasers).

If you need to update some more Customer Lists, click on the “Add Customer List” button within the section and specify values for the fields as described above.

3.7 Terms of Service Status - it must be accepted to upload to Customer Match. Requirements include good policy compliance and payment history. You should have:

• A good history of policy compliance
• A good payment history

For more details on Google's policy regarding Customer Match, please check their documentation.

3.8 Validate Only - if enabled, the request is validated but not executed. Only errors are returned.

3.9 Use Optimistic Scenario - if enabled, the tag calls gtmOnSuccess() without waiting for an API response. Speeds up sGTM response but always reports fired successfully, even if it hasn't.

3.10 Request-level consent - specify consent for Ad User Data and Ad Personalization. User-level consent (set per audience member) overrides request-level consent.

3.11 Audience member section.

• Audience Data Encoding - choose HEX or BASE64 for user identifiers.

This field is required for UserData (User Email Address, User Phone Number, and User Given/Family Name) uploads. For other types (User Address Region and User Address Postal Code) uploads, this field is ignored.

• Audience Data Encryption - encrypts User Email, Phone, Given/Family Name. Assumes data is hashed but not encrypted if left blank.

• User Mode - choose to send data for a single user or multiple users.

3.12 User Data Identifiers - specify up to 10 identifiers. At least one of User Email, User Phone, or User Address must be provided.

4. Add a trigger for the tag. Configure when the tag should fire according to your workflow.

5. Test the configuration. Open Preview mode in both your web and server GTM containers and verify your setup. 

• Check whether the tag fired in the server GTM container.

• Navigate to the Google Ads or Display and Video 360 account and check if the Customer Match list was added/updated. To check the creation of the Customer Match list in Google Ads, open Tools → Audience Manager → Your data segments → confirm the Customer Match list appears.

For more detailed debugging instructions, refer to our server-side tracking debugging guide.

To populate the Customer Match list, you need to accept a few terms of use:

• Customer Match terms.

It's a legal agreement within Google Ads where you confirm that any data you upload has been collected in compliance with Google's policies (first-party only, clear opt-in). You can read more about the Customer Match policy on Google's end.

How to fix: the Customer Match terms usually pop up when you create the Customer Match list for the first time. Later, it must reappear; be sure to confirm that you comply with the policy.

• Enhanced conversion terms.

Enhanced Conversions sends hashed first-party data (emails, phone numbers) from your website to Google to "fill in the gaps" when cookies are blocked. That's a list of terms that allows Google to use this hashed data to match conversions to signed-in Google accounts.

How to fix: go to the Goals section → Settings → Enhanced Conversions. Check the box next to Turn on enhanced conversions. A window with terms must pop up; be sure to accept the terms.

Note: if your conversions are managed via the Manager Account (MCC), the customer data terms must be accepted from the manager's account.

Enhanced Conversions for Leads (ECfL) is the specific feature that allows Google to attribute conversions using first-party data (like hashed emails) rather than just Google Click ID (GCLID). ECfL provides the framework to match CRM data using hashed first-party identifiers (like emails) instead of cookies or click IDs.

How to fix: go to the Goals section → Settings → Enhanced conversions for leads. Check the box next to Turn on enhanced conversions for leads. A window with terms must pop up; be sure to accept the terms.

To link a third-party tool (like Stape) to your Google Ads account via the API, the user account needs specific permissions. Lower access levels (like Read-only or Billing) cannot grant the necessary scopes for the Data Manager API to "write" or "upload" data to the account.

How to fix: Obtain Standard or Admin access to authorize the OAuth flow.

If you encounter the error says REQUIRED_FIELD_MISSINGThe reason is often that you selected a conversion type that requires a Transaction ID, but didn't provide one in the tag.

The requirement is determined by the Conversion Action Type:

• Website (any online conversions) - a transaction_id is mandatory.
• Offline (import from clicks) or enhanced conversions for leads - a transaction_id is optional.

For more info on when transaction_id is required, refer to Google's documentation.

If you are reporting an online "Website" conversion, you must provide a transaction_id regardless of whether the event is a purchase, a lead, or any other type.

How to fix: You need to provide the transaction_id.

Be sure to have a variable that will grab transaction_id in your Google Data Manager API Conversion Events tag.

The variable configurations:

• Variable Type - Event Data
• Key Path - transaction_id

The error INVALID_ARGUMENT for ad_personalization or ad_user_data points to consent. It means that the consent signal was either missing or sent in a format the API didn't recognize.

Google can process only three values:

• CONSENT_GRANTED
• CONSENT_DENIED
• CONSENT_STATUS_UNSPECIFIED

As provided in the tags:

How to fix: check whether you specified the consent status in the Request-level Consent section of the tag.

If you are dynamically viewing the consent status and using a variable in the Request-level Consent section, you need to transform the values into the appropriate ones that will be understandable for Google. For this purpose, use the LookUp variable.