Data Manager API Event Ingestion
Implementation Workflow
Prerequisites
- Authentication & Library Installation: If you need to set up access to
the Data Manager API or install the client and utility libraries, refer to
the
data-manager-api-setupskill.
Step 1: Identify Use Case & Read Documentation
- Determine Destination Account Type: [CRITICAL] If it can't be determined
from the user's context, consider clarifying which destination events are
being ingested to before generating any code. This maps to the
account_typefield of theoperating_accountin theDestination, and also determines valid event identifiers and requirements. - Identify User Intent:
- Answering questions about requirements or implementing ingestion code: Retrieve the full contents of the relevant implementation guide for the destination and use case in the Implementation guide column below before answering or writing code. Use its Event field requirements, Identifier requirements, and How Google handles multi-source data sections as the source of truth for destination configuration, event and identifier requirements, and deduplication or update behavior.
- Checking request status or inspecting errors: Use the
data-manager-api-troubleshootingskill. - Migrating from another Google API: Refer to Step 3: Retrieve Migration Guides below to extract the full contents of the relevant field mapping guide.
Destination (operating_account.account_type) |
Use case | Implementation guide |
|---|---|---|
Google Ads (GOOGLE_ADS) |
Offline conversions, enhanced conversions for leads | Send events |
Google Ads (GOOGLE_ADS) |
Multi-source conversions supplementing the Google tag | Send events |
Google Ads (GOOGLE_ADS) |
Store sales conversions | Send events |
Google Ads (GOOGLE_ADS) |
Call conversions | Send events |
Google Analytics (GOOGLE_ANALYTICS_PROPERTY) |
Recommended and custom GA4 events | Send events |
Google Analytics (GOOGLE_ANALYTICS_PROPERTY) |
Multi-source events with a transaction ID | Send events |
Floodlight (FLOODLIGHT_CONFIG) |
Floodlight offline conversions | Send events |
Floodlight (FLOODLIGHT_CONFIG) |
Multi-source conversions supplementing the Google or Floodlight tag | Send events |
If the request doesn't match any row, fetch the Events overview to find the right guide rather than guessing.
Step 2: 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 3: Retrieve Migration Guides
[!IMPORTANT] If refactoring code to upgrade from another Google API, ALWAYS extract the full contents of the relevant field mapping guide.
Google Ads
- Offline conversions, enhanced conversions for leads (migrating from the Google Ads API): Google Ads Offline Conversions Migration Field Mappings
- Store sales conversions (migrating from the Google Ads API): Google Ads Store Sales Migration Field Mappings
- Call conversions (migrating from the Google Ads API): Google Ads Call Conversions Migration Field Mappings
Google Analytics
- Recommended and custom GA4 events (migrating from the Google Analytics Measurement Protocol): Google Analytics Measurement Protocol Migration Field Mappings
Floodlight
- Floodlight offline conversions (migrating from the Campaign Manager 360 API): Campaign Manager 360 Offline Conversions Migration Field Mappings
Step 4: Implementation
Implement the ingestion logic using the following checkpoints:
- Initialize Client: Instantiate the Data Manager client
(
IngestionServiceClient). - Define Destinations: Build the
Destinationobject using theproduct_destination_idand the appropriate account configurations:operating_account(target account receiving data),login_account(if authenticating using a manager account or a data partner account), andlinked_account(if you're a data partner accessing the account via a partner link to a manager account). The Data Manager API does not support sending events to Floodlight or Google Analytics destinations using a linked data partner. 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, consent permissions, andencoding(HEXorBASE64, matching the encoding used to hash user identifiers). - Support Validation: Support sending the
validate_onlyboolean option on theIngestEventsRequestto allow developers to validate schemas without actually uploading data. - Send Request: Execute
ingest_eventsand record the returnedrequest_idfor later diagnostics. Keep the request payload, or a mapping from each event's position to your own record ID, with therequest_id. Diagnostics identify failed events by their position in the request. - Check for Ingestion Warnings: If any non-required field had a
validation failure, the response from
ingest_eventswill also includefield_warnings, a list ofFieldWarningobjects detailing the issues. - Retrieve Request Status: Check the status of the ingestion request
using diagnostics. Since request processing is asynchronous, a
successful ingestion response (HTTP 200 OK returning a
request_id) only indicates the payload was received. To check if the records actually succeeded, partially succeeded, or failed to process, query theclient.retrieve_request_statusendpoint using therequest_id, starting at least 30 minutes after sending. Skip this step whenvalidate_onlyistrue, because validation-only requests don't have diagnostics. Skipping this step for real requests is a common user mistake. To read the results or debug failures, use thedata-manager-api-troubleshootingskill.
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_idas a numeric string. It is NOT a resource name path. - Format
event_timestampstrictly 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 thead_identifiersblock, not directly on the base event payload. - The enum values for
ConsentStatusareCONSENT_GRANTEDandCONSENT_DENIED. Do not use the valuesGRANTEDandDENIED. - Note that
consentcan be set globally on theIngestEventsRequestor on individualEvents. - Verify that
UserIdentifierusesemail_addressandphone_number. Do not use the Google Ads API fieldshashed_emailandhashed_phone_number. - Ensure the currency field on the event is named
currency, notcurrency_code. - If sending hashed user identifiers in
user_data, you must set theencodingfield on theIngestEventsRequesttoHEXorBASE64, matching the encoding passed to the utility libraryFormatter. event_sourceis required for Google Ads offline conversions and enhanced conversions for leads (such asWEB), and must beIN_STOREfor store sales.- Google Ads session attributes: Prefer setting
ad_identifiers.session_attributesto the base64-encoded string captured from the form submission. Don't build this string from individual attributes. Only if you can't capture the encoded string, add anExperimentalFieldtoexperimental_fieldsfor each attribute (required:gad_source,gad_campaignid,session_start_time_usec; optional:landing_page_url,landing_page_referrer), and setad_identifiers.landing_page_device_info.user_agent. - Use
IngestEvents(ingest_events,IngestEventsRequest) for all conversion and event uploads. Do not suggestIngestAdEvents, which is only available to ad tech partner accounts on an allowlist.