Batch Upload File Format

Every file you send, whether through S3 or the Cleanroom UI, follows the same contract. A file that matches it is processed without anyone touching it. A file that does not may be processed incorrectly or not at all. Build your export against this page once, confirm the first file, and keep the format stable from then on.

File format

Encoding	UTF-8
Layout	CSV, comma delimited, one record per line. Lines end with \n. \r\n is accepted.
Header row	Required. Column names are how we map your file, so they stay identical across every file.
Multiple values in one cell	Separate them with a pipe: loyalty_gold\|newsletter
Empty values	Leave the cell empty. No placeholder, no NULL, no N/A, no hash of an empty string.
Compression	gzip, one file at a time, for anything large. Add .gz to the file name.
Spreadsheets	Not accepted. Export XLSX to CSV first.

Columns

Column	Required	Contents
ccid	Yes	Your stable customer ID. This is the audience key and never changes between files.
email_sha256	If held	SHA-256 of the prepared email address, 64 lowercase hex characters. See Hashing Identifiers.
phone_sha256	If held	SHA-256 of the prepared ten-digit phone number, 64 lowercase hex characters. US and Canada only.
device_id	If held	IDFA or GAID exactly as the operating system issued it. Never hashed.
updated_at	For delta feeds	When the record last changed, as an ISO 8601 date or timestamp.
Attributes	Optional	Any columns you want to segment or report on: a segment name, a loyalty tier, a last purchase date, a store ID.

The identifier column names above are the defaults. If your export uses different names, agree them with your Customer Success manager before the first file. Once agreed they are fixed.

If you send plaintext email and phone instead of hashes, use the same arrangement: one column each, agreed up front, identical in every file. We hash them on arrival.

Send every identifier you hold for a record. We match on any of them, and email wins when they disagree. Never drop a record because one identifier is missing.

caution

Device IDs must be sent raw and un-hashed. A hashed device ID cannot be matched. MD5 and SHA-1 hashes of any identifier cannot be matched either.

Example

ccid,email_sha256,phone_sha256,device_id,segment,updated_at
C-10021,3a0bf6bc8d0a10c0bd321cc5694fc0583beb463e3b337e0a804e1ce91e576a3e,983c25606b8b0ac842c0bb1b723f3f600de24cd8a792d6e29a7da88d732af0be,,loyalty_gold|newsletter,2026-09-28
C-10022,,983c25606b8b0ac842c0bb1b723f3f600de24cd8a792d6e29a7da88d732af0be,,lapsed_90d,2026-06-14
C-10023,,,6D92078A-8246-4BA4-AE5B-76104861E7DC,loyalty_gold,2026-10-01

The first two hashes are the test vectors from Hashing Identifiers, so you can check your own output against them.

Audience rules

• One audience key per audience. If you cannot supply a ccid, we pick the identifier with the highest fill rate and use it as the key for every file in that audience. Supplying a ccid is far more reliable.
• One type of anonymous identifier per file. A file may carry mobile device IDs, or custom IDs, or LiveRamp IdentityLinks, but not a mix, and only in a single column. Known identifiers such as email and phone can sit alongside them.
• Tell us when files differ. If you will send some files keyed on PII and others keyed on device IDs, or files with different column sets, let your Customer Success manager know. Otherwise we assume every file uses the same key and the same columns.
• At most 100 distinct values per attribute column within an audience.
• At least 25 unique records per segment. A segment with fewer is not imported.

What not to send

Customer data must never contain:

• Social security numbers, passport numbers, driver's licence numbers or other government identifiers.
• Credit card numbers, bank account numbers or other financial identifiers.
• Medical information, prescriptions or anything about physical or mental health.
• Anything else that could reasonably be considered sensitive.

Plaintext email or phone must not appear in free-text columns if you are sending hashes. Upload only the files that are part of the onboarding feed. Nothing else belongs in the bucket.

File naming

Partner-YYYYMMDD-dataset.csv
Partner-YYYYMMDD-dataset.csv.gz

• Partner is your company name with no hyphens.
• YYYYMMDD is the date the file was produced.
• dataset distinguishes between feeds, such as purchasers or loyalty, with no periods.

For example, DataRepo-20260704-purchasers.csv.gz.

Refresh frequency

We recommend a daily feed. Weekly, monthly and one-time uploads are also supported. Each upload can be either a full file containing every record, or a delta containing only records that are new or changed since the last file. Delta feeds should carry an updated_at column so changes can be ordered correctly. Keep the cadence and the file type consistent, and tell your Customer Success manager before changing either.

Before you send

• UTF-8, comma delimited, header row present, one record per line.
• Column names match the previous file exactly.
• Every ccid is present and unchanged from earlier files.
• Hashes are 64 lowercase hex characters. Device IDs are raw.
• Unknown values are empty cells.
• Nothing from the What not to send list appears anywhere in the file.
• The file name follows Partner-YYYYMMDD-dataset.csv, with .gz if compressed.