Data Manager API Audience Ingestion

Core Directives

[IMPORTANT] When reading API documentation from developers.google.com, read the Markdown equivalent of the page by appending .md.txt to the URL.

Sequential Implementation Workflow

For simple informational, configuration, or setup questions, skip any irrelevant steps and answer using only the relevant guidelines or documentation provided below.

Step 1: Identify Use Case & Read Documentation

Determine Destination Account Type: [CRITICAL] If it's not explicitly stated, STOP and CLARIFY with the user where the data is being sent (e.g., Google Ads, Display & Video 360, etc.) BEFORE generating any code. Do NOT assume Google Ads by default. This maps to the account_type field of the operating_account in the Destination.
Read Documentation: [CRITICAL] You MUST follow the relevant audience upload overview for implementation steps:
- Google Ads Customer Match: Upload members to an audience
- DV360 Customer Match: Upload members to an audience

Step 2: Setup Auth

Enable API (Prerequisite): Check that the user has enabled the Data Manager API in their Google Cloud project.
Generate ADC: Authenticate the local workspace using Application Default Credentials (ADC) via gcloud auth application-default login.
- Required Scopes: Include scopes https://www.googleapis.com/auth/datamanager and https://www.googleapis.com/auth/cloud-platform.
- Multi-API Scopes: If using the same credentials for other APIs, append their scopes (e.g., https://www.googleapis.com/auth/adwords).
- Service Accounts: Ensure the Service Account has the Service Usage Consumer IAM role, and the user executing gcloud has the Token Creator role (roles/iam.serviceAccountTokenCreator) on that Service Account for impersonation.
Reference: Refer to Set up API access for a walkthrough of the gcloud CLI auth setup.

Step 3: Install Client Library and Utilities

Refer to Install a client library for detailed installation instructions.

[IMPORTANT] The utility library is NOT available on public package managers (such as PyPI or Maven). Follow the below instructions to install:

Clone the repository from GitHub using the commands from the table below.
Always use the latest available version of the library. Determine the actual version identifier (VERSION) from the cloned repository metadata.
- Python: Find the version in pyproject.toml.
- Java: Find the version in data-manager-util/build.gradle.
- Node: Find the version in util/package.json (as the version field).
Follow the language-specific instructions in the next section to build and install the utility dependency, replacing VERSION with the version identifier you found.

Install Utility Library

Python

Navigate to the data-manager-python directory and install the utility library:
```
pip install .
```
Declare a dependency in your project's requirements.txt file (replacing VERSION with the identified version):
```
google-ads-datamanager-util==VERSION
```

Java

Navigate to the data-manager-java directory.
Build and publish the utility library to your local Maven repository:

./gradlew data-manager-util:install

Declare a dependency on the utility library in your project (replacing VERSION with the identified version):

Gradle:

implementation 'com.google.api-ads:data-manager-util:VERSION'

Maven:

<dependency>
   <groupId>com.google.api-ads</groupId>
   <artifactId>data-manager-util</artifactId>
   <version>VERSION</version>
</dependency>

Node

Navigate to the data-manager-node directory and install dependencies:

npm install

Navigate to the util directory:

cd util

Pack the utility library into a .tgz archive:

npm pack

Declare a dependency in your Node.js project's package.json pointing to the path of the generated .tgz archive (replacing VERSION with the identified version):

{
   "dependencies": {
      "@google-ads/data-manager-util": "file:/path/to/google-ads-datamanager-util-VERSION.tgz"
   }
}

PHP

Navigate to the data-manager-php directory.
Resolve dependencies for the library:

composer update --prefer-dist

Update your project's composer.json to declare a dependency on the utility library using a path repository:

 {
     "repositories": [
         {
             "type": "path",
             "url": "/path/to/cloned/data-manager-php"
         }
     ],
     "require": {
         "googleads/data-manager-util": "@dev"
     }
 }

.NET

In your .NET project, declare a ProjectReference dependency pointing to the cloned library's .csproj path:

<ProjectReference Include="\path\to\cloned\Google.Ads.DataManager.Util\src\Google.Ads.DataManager.Util.csproj" />

Step 4: Retrieve Code Sample

[IMPORTANT] If writing or updating an ingestion script, ALWAYS retrieve the relevant code sample to use as a reference:

Step 5: Retrieve migration guides

[CRITICAL] If refactoring code to upgrade from another Google API, ALWAYS extract the full contents of the relevant field mapping guide.

Google Ads

Google Ads API Customer Match: Google Ads API to Customer Match Migration Field Mappings

Display & Video 360

Display & Video 360 API Customer Match: Display & Video 360 API to Customer Match Migration Field Mappings

Step 6: Implementation

Implement the ingestion logic using the following checkpoints:

[ ] Initialize Client: Instantiate the Data Manager client (IngestionServiceClient).
[ ] Define Destinations: Build the Destination object using the product_destination_id and the appropriate account configurations: operating_account (target account receiving data), login_account (if authenticating using a manager account or a data partner account), and linked_account (if you're a data partner accessing the account via a partner link to a manager account). STRONGLY RECOMMENDED: Refer to the Configure destinations and headers guide for more details on configuring destinations.
[ ] Format User Data: Use the utility library helpers to normalize and hash user identifiers correctly.
[ ] Construct Payload: Build the request payload (IngestAudienceMembersRequest) containing the destinations, formatted members, and consent permissions.
[ ] Send Request: Execute ingest_audience_members and record the returned request ID for logging/troubleshooting.

Formatting

Fetch the Format user data guide and use that as the source of truth for formatting and normalization rules.

Use the utility library to format, hash, and encrypt user data (emails, phone numbers, addresses).

Python Example:

from google.ads.datamanager_util import Formatter
from google.ads.datamanager_util.format import Encoding

formatter: Formatter = Formatter()

processed_email: str = formatter.process_email_address(
    email, Encoding.HEX
)

Critical Gotchas

Do NOT set the address field on UserIdentifier unless all required fields are present (postal_code, family_name, given_name, region_code); incomplete address fields will cause the API request to fail.
product_destination_id must be a numeric string. It is NOT a resource name.
The enum values for ConsentStatus are CONSENT_GRANTED and CONSENT_DENIED. Do not use the values GRANTED and DENIED.
Field names on UserIdentifier are email_address and phone_number. Do not use the Google Ads API field names hashed_email and hashed_phone_number.

Error Handling & Troubleshooting

Inspecting Error Payloads

[IMPORTANT] Refer to Understand API Errors for a detailed guide on how to understand the structure of errors returned by the API.

API Reference

When implementing or debugging API integrations, use the API reference to lookup field names, types, and acceptable values. DO NOT guess values.

Send audience members guide: https://developers.google.com/data-manager/api/devguides/audiences/send-audience-members
REST API Reference: https://developers.google.com/data-manager/api/reference/rest/v1/audienceMembers/ingest