The Data Manager API supports uploading multiple types of user data. Follow the formatting, hashing, and encoding requirements for each data element so that your data is received and processed successfully.
-
UserData: User-provided data such as an email address or phone number. -
PairData: Publisher Advertiser Identity Reconciliation (PAIR) IDs. -
MobileData: Data identifying a mobile device.
UserData
requirements
A UserData
object is a collection of UserIdentifier
objects. Each UserIdentifier
has exactly one of the attributes in the following table.
email_address
| Format | string
Convert to lowercase.
If the email address has the
gmail.com
or googlemail.com
domain, remove all dots ( .
)
before the @
symbol. |
| Whitespace | Trim leading, trailing and intermediate whitespace. |
| Hashing | Hash using the SHA-256 algorithm . Encode the hash bytes using hex or Base64 encoding. |
phone_number
| Format | string
Include the plus sign (
+
) and the country
code. All characters after the plus sign must be digits.For example, the US phone number
(800)555-0100
should be formatted and normalized to +18005550100
. |
| Whitespace | Trim leading and trailing whitespace. |
| Hashing | Hash using the SHA-256 algorithm . Encode the hash bytes using hex or Base64 encoding. |
address
AddressInfo
object AddressInfo
format
Use the following formatting guidelines to construct the address
attribute of a UserIdentifier
.
given_name
| Format | string
Convert to lowercase.
Don't include prefixes such as
Mrs.
|
| Whitespace | Trim leading and trailing whitespace. |
| Hashing | Hash using the SHA-256 algorithm . Encode the hash bytes using hex or Base64 encoding. |
family_name
| Format | string
Convert to lowercase.
Don't include suffixes such as
Jr.
|
| Whitespace | Trim leading and trailing whitespace. |
| Hashing | Hash using the SHA-256 algorithm . Encode the hash bytes using hex or Base64 encoding. |
region_code
| Format | string
|
| Whitespace | Trim leading and trailing whitespace. |
| Hashing | Don't hash region_code
. |
postal_code
| Format | string
Both US and international zip and postal codes are
allowed.
For US addresses, use either 5 digits or 5 digits followed by a
4-digit extension. Using a 4-digit extension may improve your match
rate.
For all other countries, don't use postal code
extensions.
|
| Whitespace | Trim leading and trailing whitespace. |
| Hashing | Don't hash postal_code
. |
PairData
requirements
Populate the pair_ids
field of a PairData
object with a list of IDs.
Format each element in the list using the following steps:
- Hash the cleanroom-provided PII data using the SHA-256 algorithm .
- Encrypt the hash bytes with an EC commutative cipher using the publisher key for the PAIR user list.
- Encode the encrypted data using hex or Base64 encoding.
MobileData
requirements
Populate the mobile_ids
field of a MobileData
object with a list of mobile IDs
. Don't hash mobile
IDs.
Timestamp format
If using the JSON format for Timestamp
fields, like timestamp
and last_updated_timestamp
of Event
, use the RFC
3339
format. Here are some examples of the UTC time
of August 8, 2025 at 5:18:44.291 PM in the RFC 3339 format and different time
zones:
- UTC time zone:
2025-08-08T17:18:44.291Z - EDT time zone, which was 4 hours before UTC at that time:
2025-08-08T13:18:44.291-04:00 - PDT time zone, which was 7 hours before UTC at that time:
2025-08-08T10:18:44.291-07:00 - Time zone for Tokyo, Japan, which was 9 hours ahead of UTC and doesn't observe
daylight saving time:
2025-08-08T22:18:44.291+09:00
If using the protocol buffer format, set the seconds
and, optionally, the nanos
when constructing the Timestamp
. Here are the seconds
and nanos
values for the UTC time of August 8, 2025 at 5:18:44.291 PM:
-
seconds:1754683124 -
nanos:291000000
Encoding
Keep the following in mind when encoding data:
- The case of the encoding output doesn't matter when using hexadecimal encoding (hex).
- The case of the encoding output matters when using Base64 encoding .
Next steps
- Learn how to encrypt user data .
