> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Data Manager API

> Fuel AI-powered personalization and support advanced measurement use-cases by connecting first-party audience and conversion data to Google Ads, Google Analytics, and Google Marketing Platform through a single unified API.

## Supported syncing

| Sync type | Description | Supported sync modes | API reference |
| - | - | - | - |
| [**Google Ads Audiences**](#syncing-google-ads-audience-members) | Sync records as audience members in Google Data Manager via the Data Manager API | Add | [Audience Members](https://developers.google.com/data-manager/api/get-started/quickstart/send-audience-members) |
| [**Display & Video 360 Audiences**](#syncing-display--video-360-audiences) | Create and update first and third party audiences in Google Display & Video 360 | Add | [Display & Video 360 Audiences](https://developers.google.com/display-video/api/guides/audiences/overview) |
| [**Google Ads Conversion Events**](#syncing-google-ads-events) | Send Online and Offline events to Google Data Manager via the Data Manager API | Insert | [Events](https://developers.google.com/data-manager/api/get-started/quickstart/send-events) |

For more information about sync modes, refer to the [sync modes](https://docs.hightouch.com/syncs/types-and-modes.md#sync-modes) docs.

## Connect to Google Data Manager

Go to the [**Destinations** overview page](https://app.hightouch.com/destinations?from=docs) and click the **Add destination** button.
Select **Google Data Manager** and click **Continue**. Select whether you'd like to send data to Google Ads or Display & Video 360.

For Google Ads, Hightouch supports two authentication methods:

| Method | Description |
| - | - |
| **Sync data to Google Ads** | OAuth-based authentication. Hightouch creates a partner link between Hightouch and your Google Ads account during the first sync run. Recommended for most destinations. |
| **Existing Partner Link** | A method for accounts that already have a Hightouch partner link. Use this when the OAuth method can't create the partner link for you. |

### Sync data to Google Ads

Select **Sync data to Google Ads**, click **Log in to Google Data Manager**, log in with your Google Account, and click **Allow**.
You should then see a success notification in the Hightouch UI.

Hightouch creates the partner link during the first sync run. Creating the partner link requires the authenticating user to have **Admin** access on the Google Ads account. If the user doesn't have Admin access, the sync fails with a `PERMISSION_DENIED` error. See [PERMISSION\_DENIED from Data Manager API](#permission_denied-from-data-manager-api) to verify and fix the access level.

### Existing Partner Link

Use this method if the OAuth method can't create the partner link for you and you already have a Hightouch partner link set up in your Google Ads account.

Unlike the OAuth method, this method doesn't create the partner link for you. Before connecting, create the partner link in your Google Ads account by linking **Hightouch** as a data provider. See Google's [data partner linking](https://developers.google.com/data-manager/api/devguides/concepts/destinations#ads-credentials) documentation for details.

### Enter your account ID

Enter the Google Ads or Display & Video 360 account ID you'd like to use with this destination. You can find this value in Google, at the top-right corner with your account information. This should be a 10 digit value. Remove any dashes that may be present in your account ID.

## Sync configuration

Once you've set up your Google Data Manager destination and have a [model](https://docs.hightouch.com/getting-started/concepts.md#models) to pull data from, you can set up your sync configuration to begin syncing data.
Go to the [**Syncs** overview page](https://app.hightouch.com/syncs?from=docs) and click the **Add sync** button to begin.
Then, select the relevant model and the Google Data Manager destination you want to sync to.

### Syncing Google Ads audience members

Hightouch lets you create and maintain customer match lists via the Google Data Manager API.
It can take 6 to 48 hours for a list to be populated with members once Hightouch has sent the data to Google.

#### User list type

To begin, select which type of Customer Match User List you'd like to create or sync to. The available options are:

* **CONTACT\_INFO**
* **MOBILE\_ADVERTISING\_ID**

#### Select an existing list or create a new one

You can create a new [Customer match user list](https://support.google.com/google-ads/answer/6276125) or use an existing one.
When creating a new list, you can optionally enter a name.
Otherwise, Hightouch defaults to the name of the associated model.

To use an existing list, enter the list's ID in the following format: `products/{product}/customers/{customer_id}/userLists/{user_list_id}`. Example: `products/GOOGLE_ADS/customers/12345678/userLists/12345678`

> [!WARNING]
>
> If you choose to create a new list, you can't update the
> [account](#select-account) to which you're syncing data after the initial sync
> run. If you need to change the account, configure a new sync.

#### User identifiers

Select which columns in your model you'd like to send to Google Ads as user identifiers.

For user lists with the Contact Info type, you must select *either* hashed email addresses or hashed phone numbers. If you choose to sync addresses, all fields of the address are required.

For user lists with the Mobile Advertising ID type, the mobile advertising ID is required.

> [!TIP]
>
> Increase match rates in Google Data Manager audience members by enabling [Match Booster](https://docs.hightouch.com/match-booster/overview.md).

#### Handling PII and hashing

You can enable PII hashing if you wish for Hightouch to detect whether your data requires normalization and hashing based on the chosen record mapping.
For example, if you select **Email** and the model column with the email data is unhashed, Hightouch hashes the value for you.

By default, Hightouch automatically detects if the following fields require hashing:

* **Email**
* **Phone**
* **Given name**
* **Family name**

#### EU user consent policy

If you are uploading data for users in the European Economic Area ([EEA](https://ec.europa.eu/eurostat/statistics-explained/index.php?title=Glossary:European_Economic_Area_\(EEA\))),
you need to ensure you are passing the required consent signals to [Google](https://www.google.com/about/company/user-consent-policy/?sjid=2196795394224792925-NA).

For each sync, you can specify the consent status for these types:

* `ad_user_data`: consent for sending user data to Google for advertising purposes
* `ad_personalization`: consent for ad personalization

Check out Google's support [doc](https://support.google.com/google-ads/answer/14310715?hl=en) to learn more.

### Syncing Display & Video 360 audiences

Hightouch allows you to create and update first and third party audiences in Google Display & Video 360 as customer match user lists. These lists support adding members using mobile device ID or an array of email, phone numbers, and physical addresses.

When creating the audience, make sure the source of the data is properly selected between first or third party sources.

#### User identifiers

Mobile device IDs and other user identifiers cannot be mixed. Also, if providing the user's physical address, the zip code, country code, first and last name must be provided.

Phone numbers must be in [E.164](https://en.wikipedia.org/wiki/E.164) format.

> [!TIP]
>
> Increase match rates in Google Data Manager Display & Video 360 audiences by enabling [Match Booster](https://docs.hightouch.com/match-booster/overview.md).

#### User consent

Starting in March 2024, Display & Video 360 introduced the [consent object](https://developers.google.com/display-video/api/guides/audiences/upload-customer-match?sjid=10202302840984618943-NA#set_user_consent) for uploading consent with customer match data. The consent object specifies two distinct types of consent and users must grant both types of consent to use their data for customer match lists. Reference the [DV360 docs](https://support.google.com/displayvideo/answer/14673239?hl=en) for more information.

> [!WARNING]
>
> If you don't set the consent status or if the status is denied, the sync
> results in an error.

#### PII data and hashing

Hightouch automatically hashes all the PII data before it's sent to Google. If the data is already hashed, this option can be disabled. Reference the [DV360 docs](https://developers.google.com/display-video/api/reference/rest/v1/firstAndThirdPartyAudiences#ContactInfo) for more information.

> [!WARNING]
>
> Google's Personalized Ads Policy, Customer Match Policy and Platforms program
> policies include requirements for advertisers to show sufficiently established
> Google Ads or Display & Video 360 account history before accessing certain
> features. To enable uploading data to DV360, please fill [this
> form](https://support.google.com/displayvideo/answer/9176010) before you
> create the sync.

### Syncing Google Ads events

Hightouch supports syncing:

* Online events: Send event data as an additional data source for your tag conversions, to maximize ad interaction signals and strengthen your data and overall performance.
* Offline events: Send event data for [offline conversions](https://support.google.com/google-ads/answer/2998031) or [enhanced conversions for leads](https://support.google.com/google-ads/answer/15713840).

When syncing conversion events, Hightouch treats any records added to [your source](https://docs.hightouch.com/getting-started/concepts.md) as new events and sends them to Google Data Manager when your sync runs.

> [!WARNING]
>
> To ensure syncs send each event, your event model must use a truly unique [primary key](https://docs.hightouch.com/getting-started/concepts.md#unique-primary-key-requirement). See the [events syncs](https://docs.hightouch.com/syncs/types-and-modes.md#event-syncs) documentation for more information.

#### Field mapping

Select which columns in your model you'd like to sync as attributes of conversion events.

Google Data Manager requires the following fields for each event:

* Event timestamp (event\_timestamp): The time the event occurred.
* Transaction ID (transaction\_id): The unique identifier for the event.
* Event source (event\_source): The source of the event. Required for offline events. Optional for online events. If specified for an online event, must be WEB.
* Ad identifiers (GCLID, GBRAID, or WBRAID) or user data (email, phone, or address): The event must have either an ad identifier or user data. Send both if you have both for the event.

The accepted values for `event_source` are:

* `EVENT_SOURCE_UNSPECIFIED`
* `WEB`
* `APP`
* `IN_STORE`
* `PHONE`
* `OTHER`

Additional user properties mappings include:

* Customer type
  * Accepted values: `CUSTOMER_TYPE_UNSPECIFIED`, `NEW`, `RETURNING`, `REENGAGED`
* Customer value bucket
  * Accepted values: `CUSTOMER_VALUE_BUCKET_UNSPECIFIED`, `LOW`, `MEDIUM`, `HIGH`

#### Landing page device info (recommended for online events)

For online events, we recommend collecting and sending information about the device being used (if any) when the event happened. This will improve the likelihood that conversion events can be accurately attributed back to ad interactions, resulting in more accurate reporting and better performance as Google's AI systems learn and improve from each attributed conversion.

To map device information to your conversion events, select `Landing page device info` and map the following fields:

* `userAgent` - user-agent string of the device for the given context.
* `ipAddress` - The IP address of the device for the given context.

> [!WARNING]
>
> Google Ads does **not** support IP address matching for end users in the
> European Economic Area (EEA), United Kingdom (UK), or Switzerland (CH). We
> recommend adding logic directly in your model to conditionally exclude sharing
> IP addresses from users from these regions and ensure that you provide users
> with clear and comprehensive information about the data you collect on your
> sites, apps, and other properties and get consent where required by law or any
> applicable Google policies. See Google's [**About offline conversion
> imports**](https://support.google.com/google-ads/answer/2998031) page for more
> details.

#### EU user consent policy

If you are uploading data for users in the European Economic Area ([EEA](https://ec.europa.eu/eurostat/statistics-explained/index.php?title=Glossary:European_Economic_Area_\(EEA\))),
you need to ensure you are passing the required consent signals to [Google](https://www.google.com/about/company/user-consent-policy/?sjid=2196795394224792925-NA).

For [click conversions](#syncing-click-conversions), [call conversions](#syncing-call-conversions) and [offline store conversions](#syncing-offline-store-conversions), you can specify the Google consent status for advertising purposes, by mapping these fields in the sync configuration:

* `Ad user data consent` (for the `ad_user_data` property)
* `Ad personalization consent` (for the `ad_personalization` property)

## Tips and troubleshooting

To see the exact API requests and responses from each sync run, use the [live debugger](https://docs.hightouch.com/syncs/debugger.md). To get notified by Slack, PagerDuty, SMS, or email when a sync fails, set up [sync alerts](https://docs.hightouch.com/syncs/alerting.md). If you run into an issue this page doesn't cover, [contact support](#pylon-chat).

## Common errors

### PERMISSION\_DENIED from Data Manager API

You may receive a `403 - {"error":{"code":403,"message":"The caller does not have permission","status":"PERMISSION_DENIED","domain":"datamanager.googleapis.com"}}` error when syncing to Google Ads.

This occurs when Hightouch creates the partner link during a sync run but the authenticating user doesn't have **Admin** access on the Google Ads account. Google Data Manager checks access against the login account, which in manager-account setups is the manager (MCC) account. A user with a lower access level, such as Standard, can sign in successfully but can't create the partner link.

To verify the access level:

1. Go to your Google Ads account.
2. Open **Access and security**.
3. Open the **Users** tab.
4. Turn off the **Show users in full hierarchy** toggle.
5. Confirm the authenticating user is listed directly on the manager (MCC) account.
6. Confirm the user's access level is **Admin**. For more on access levels, see Google's [access levels](https://support.google.com/google-ads/answer/9978556) documentation.

If the user isn't an Admin, upgrade the access level and rerun the sync, or re-authorize the destination with a different user who has Admin access. If you can't grant Admin access, create the partner link manually and switch to the [**Existing Partner Link**](#existing-partner-link) authentication method instead.