Data Manager API Audience 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. - Audience Creation (if needed): If the user does not have an existing
audience or needs to create a new one, use the
Create an Audience reference. This step
provides the
product_destination_idneeded for the ingestion or removal requests.
Step 1: Identify Use Case & Read Documentation
- Determine Destination Account Type: [CRITICAL] If it's not clear where
the data is being sent (e.g., Google Ads, Display & Video 360, etc.), STOP
and CLARIFY with the user BEFORE generating any code. Do not assume Google
Ads by default. This maps to the
account_typefield of theoperating_accountin theDestination. - Read the implementation guide: Read the relevant guide for your destination and use case. Do this before answering questions or writing code because each destination has unique payload structures, consent rules, and required fields.
| Destination | Audience Type | Accepted Data Types | Upload Guide | Remove All/Replace All Guide |
|---|---|---|---|---|
| Google Ads | Customer Match | composite_data.user_data (contact info), mobile_data (device IDs), user_id_data (user IDs) |
Upload Data | Remove All/Replace All |
| Display & Video 360 (DV360) | Customer Match | composite_data.user_data (contact info), mobile_data (device IDs) |
Upload Data | Remove All/Replace All |
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_audience_members.py |
| Java | IngestAudienceMembers.java |
| PHP | ingest_audience_members.php |
| Node | ingest_audience_members.ts |
| .NET | IngestAudienceMembers.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
- 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 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). STRONGLY RECOMMENDED: Refer to the Configure destinations and headers guide for more details on configuring destinations. - Format User Data: If sending an
IngestAudienceMembersRequestorRemoveAudienceMembersRequest, refer to Formatting User Data to properly normalize and hash user identifiers using the utility library. - Construct Payload: Build the appropriate request payload based on
the operation:
- Add:
IngestAudienceMembersRequest - Remove:
RemoveAudienceMembersRequest - Remove All:
RemoveAllAudienceMembersRequest
- Add:
- Support Validation: Support sending the
validate_onlyboolean option on the payload to allow developers to validate schemas without actually applying changes. - Send Request: Execute the appropriate method and record the returned
request_idfor later diagnostics. Keep the request payload, or a mapping from each member's position to your own record ID, with therequest_id. Diagnostics identify failed members by their position in the request.- Add:
ingest_audience_members - Remove:
remove_audience_members - Remove All:
remove_all_audience_members
- Add:
- Check for Ingestion Warnings: If any non-required field had a
validation failure, the response from
ingest_audience_memberswill 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
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, queryclient.retrieve_request_statususing 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.
Critical Gotchas
- If sending hashed user identifiers in
user_dataforingest_audience_membersorremove_audience_members, you must set theencodingfield on theIngestAudienceMembersRequesttoHEXorBASE64. - If uploading to a Customer Match audience, the
terms_of_servicefield is required on theIngestAudienceMembersRequestto indicate the user has accepted the policies. - Only set the
addressfield onUserIdentifierif all required fields (postal_code,family_name,given_name,region_code) are present; incompleteaddressfields will cause the API request to fail. product_destination_idmust be a numeric string. It is NOT a resource name.- The enum values for
ConsentStatusareCONSENT_GRANTEDandCONSENT_DENIED. Do not use the valuesGRANTEDandDENIED. - Field names on
UserIdentifierareemail_addressandphone_number. Do not use the Google Ads API field nameshashed_emailandhashed_phone_number.