Format user data

  • The Data Manager API supports uploading UserData, PairData, and MobileData, each with specific formatting, hashing, and encoding requirements.

  • UserData includes user-provided information like email address, phone number, and address, and requires specific formatting, whitespace trimming, and SHA-256 hashing for email and phone number, while AddressInfo has its own formatting rules for components like name and address details.

  • PairData requires hashing cleanroom-provided PII data with SHA-256, encrypting the hash using an EC commutative cipher with a publisher key, and encoding the result using hex or Base64.

  • MobileData involves populating the mobile_ids field with mobile IDs, which should not be hashed.

  • Timestamps for fields like timestamp and last_updated_timestamp should follow the RFC 3339 format for JSON or use seconds and optional nanos when using the protocol buffer format.

  • Encoding should be done using hex or Base64, keeping in mind that case sensitivity matters for Base64 but not for hex.

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 requirements

A UserData object is a collection of UserIdentifier objects. Each UserIdentifier has exactly one of the attributes in the following table.

UserIdentifier
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 format

Use the following formatting guidelines to construct the address attribute of a UserIdentifier.

AddressInfo
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
A two-character ISO-3166-1 alpha-2 code.
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:

  1. Hash the cleanroom-provided PII data using the SHA-256 algorithm.
  2. Encrypt the hash bytes with an EC commutative cipher using the publisher key for the PAIR user list.
  3. 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:

Next
Encrypt user data