Data Manager API Event 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, Floodlight, Google Analytics) 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, and also determines valid event identifiers and requirements.
Read Documentation: [CRITICAL] You MUST follow the the Send events guide to understand implementation steps, user/event identifier requirements, and how to configure the destination object.

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.

Language	Installation Instructions
Python	`pip install google-ads-datamanager`
Java	Follow the quickstart instructions to install the Maven/Gradle dependency.
Node	`npm install @google-ads/datamanager`
PHP	Install the `googleads/data-manager` component using Composer.
.NET	Install the `Google.Ads.DataManager.V1` NuGet package.

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

Language	Git Clone Command
Python	`git clone https://github.com/googleads/data-manager-python.git`
Java	`git clone https://github.com/googleads/data-manager-java.git`
Node	`git clone https://github.com/googleads/data-manager-node.git`
PHP	`git clone https://github.com/googleads/data-manager-php.git`
.NET	`git clone https://github.com/googleads/data-manager-dotnet.git`

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:

Language	Sample
Python	`ingest_events.py`
Java	`IngestEvents.java`
PHP	`ingest_events.php`
Node	`ingest_events.ts`
.NET	`IngestEvents.cs`

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.

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.
Prepare Event Data: Use the utility library helpers to format and normalize user identifiers correctly.
Construct Payload: Build the request payload (IngestEventsRequest) containing the destinations, event records, and consent permissions.
Send Request: Execute ingest_events 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

Format product_destination_id as a numeric string. It is NOT a resource name path.
Format event_timestamp strictly in RFC 3339 format. Use the SDK's typed timestamp object instead of a raw string where available.
Nest click identifiers (gclid, gbraid, wbraid) inside the ad_identifiers block, not directly on the base event payload.
The enum values for ConsentStatus are CONSENT_GRANTED and CONSENT_DENIED. Do not use the values GRANTED and DENIED.
Note that consent can be set globally on the IngestEventsRequest or on individual Events.
Verify that UserIdentifier uses email_address and phone_number. Do NOT use the Google Ads API fields hashed_email and hashed_phone_number.
Ensure the currency field on the event is named currency, not currency_code.

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.

REST API Reference: https://developers.google.com/data-manager/api/reference/rest/v1/events/ingest