Why is impersonation recommended over a service account key?

A key file is a long-lived secret and stays valid until revoked if it leaks; Google's own guide notes it becomes a security risk when not managed carefully. With impersonation, meaning making calls on behalf of a service account using your own identity, short-lived tokens are produced during authentication: the service account gets the Service Usage Consumer role, and your own account gets the Service Account Token Creator role on that service account. The result is that no key file is kept on disk.

How many records can be sent in a single request?

At most 10,000 members on the audience side, at most 2,000 events on the event side. Both requests can define at most 10 destinations, and a single audience member or event can carry at most 10 identifiers. When exceeded, the request fails with TOO_MANY_AUDIENCE_MEMBERS, TOO_MANY_EVENTS, TOO_MANY_DESTINATIONS or TOO_MANY_USER_IDENTIFIERS. That asymmetry requires defining two separate batch sizes on the uploader side.

Which fields are hashed and which stay in plain text?

Email, phone number, first name and last name are SHA256 hashed after normalisation. Country code and postal code are not hashed and are sent in plain text. The normalisation rules also vary by field type: whitespace trimming and lowercasing on every field, E.164 formatting on phone numbers, and removing the dots before the domain on gmail.com and googlemail.com addresses. If encryption is used, what gets encrypted is the hash itself, not the unhashed value.

How do you tell whether an upload worked?

Not from the synchronous response. A successful request only returns a request_id; how many records were processed, how many errored and the match rate range are read through a RetrieveRequestStatus call. Processing can finish in thirty minutes but can also take up to twenty-four hours, so the status query has to be a loop with backoff rather than a single call.

Is the match rate given as an exact number?

No, it comes in buckets. The buckets run under twenty, twenty to thirty, thirty-one to forty and so on up to ninety-one to one hundred, plus unknown and not eligible values. If there are not enough records, the field is not populated at all. So a match rate at percentage precision cannot be tracked through the API; following trends means recording bucket transitions.

Uploading with the Data Manager API: Setup Order from Authentication to Diagnostics

The API begins where the dashboard connector stops. Service account impersonation, the asymmetry of batch limits, the fields that are not hashed, the hidden cost of a dry run, and the only way to read the result of an upload.

TL;DR

The hard part of a Data Manager API setup is not the request body, it is the four decisions around it: building authentication on impersonation rather than a key file, batch sizes differing between the audience and event sides, deciding which field gets hashed, and reading the result through a separate call. The synchronous response only says the request was accepted; how many records were processed comes from a separate status call that can take up to twenty-four hours.

Create Free Account Sign In