Upload identity mapping files to a Taboola-managed S3 bucket on an agreed schedule. Taboola scans, validates, and ingests the files automatically, writing the identifier pairs to the identity graph for cross-device resolution.

This is the recommended server-to-server path for sharing identity data. For the real-time alternative, see Server-to-server identity sync - online (real-time).

📘

Three ways to send identity data

	Eids push	Online sync (real-time)	Offline sync (this page)
Mechanism	_taboola.push({eids}) in the page tag	Separate HTTP pixel (/um endpoint)	S3 file upload on a schedule
Delivery	Part of the TRC request	Separate browser call per user	Bulk file transfer
Volume	Per-pageview (automatic)	Per-pageview or per-session	High volume, bulk data
Update mode	Immediate	Immediate	Incremental or full refresh
Browser required	Yes	Yes (Taboola cookie must be present)	No

Roles and responsibilities

How it works

1. Taboola provisions an S3 bucket with credentials and a designated upload folder.
2. Your server-side pipeline generates files that map your identifiers to Taboola-recognized identifiers (e.g. publisher ID to hashed email, publisher ID to device ID).
3. You upload the files to the S3 bucket on the agreed schedule (e.g. daily).
4. Taboola scans the folder, validates each file, and ingests valid records into the identity graph.
5. Processed files move to processed/. Rejected files move to error/.

Companion client-side step

If you cannot or prefer not to send PII-derived identifiers (e.g. hashed email) client-side, send a pseudonymous identifier via the eids push instead. The batch file then maps that pseudonymous identifier to PII-derived values server-to-server. Taboola joins the two, resolving identity without sensitive data touching the browser.

_taboola.push({
  eids: [{
    source: "publisher.com",
    uids: [{ id: "user-abc-123", atype: 3, ext: "ppid" }]
  }]
});

The ext field identifies the type of identifier being sent (e.g. "ppid" for a publisher-provided ID, "hemsha256" for a SHA-256 hashed email). Contact your Taboola account manager for the correct ext value for your use case.

See Passing first-party publisher data for the full client-side reference.

Supported identifier types

Each row in the upload file maps 2 or more identifiers together. Common identifier types include:

The file format is fully configurable. The columns, their order, and the identifier types are all agreed during onboarding. If you need to map an identifier type not listed above, share the format and requirements with your Taboola account manager during setup.

Onboarding setup

Taboola provisions the following parameters during onboarding:

S3 access credentials (access key and secret) are provided securely during setup.

Recommended cadence

Daily file drops are recommended. The shorter the gap between transfers, the less data is lost to cookie churn and consent changes between syncs. Daily delivery provides the freshest mapping without adding significant operational overhead.

Incremental vs full refresh

Confirm your delivery mode with your Taboola account manager during onboarding.

File format

Record structure

Files are delimiter-separated text, compressed with GZIP (.gz). The column layout is fully configurable. The most common format uses tab-delimited columns.

Example: 3-column file (publisher IDs, device IDs, hashed emails)

• Columns are separated by a delimiter character. The default is a tab (\t). Other delimiters (e.g. comma, pipe) can be agreed during onboarding.
• Multiple values within a single column are separated by commas with no spaces.
• Empty columns retain the delimiter (row 3 above has no device ID, but the delimiter is still present in the file).
• Files must not contain a header row. The column labels above are for illustration only.

Validation rules

1. Every row must contain at least 2 populated identifier columns. Rows with only 1 identifier are rejected.
2. Retain all delimiters for empty columns. Do not omit columns.
3. No whitespace around inner-column commas (a,b is valid; a, b is not).
4. Do not use sentinel values like 0 or null for empty fields. Leave empty columns blank.

File naming and delivery

Naming convention

Every filename must start with the assigned $PREFIX and end with .gz:

$PREFIX_<date>_<sequence>.<ext>.gz

Recommended structure:

<publisher-name>_<yyyyMMdd>_<hhmmss>.<ext>.gz

When splitting large files, append an ordinal number:

PublisherName_20260820_033246_0000.tsv.gz
PublisherName_20260820_033246_0001.tsv.gz

Delivery rules

• Every filename must include the assigned $PREFIX.
• Files must end in .gz and be valid GZIP.
• The extension before .gz can be .tsv, .csv, or .txt, matching the agreed format.
• Never reuse a filename, even after an error. Always use a unique name for resubmissions.
• Encoding: UTF-8 without BOM, LF line endings.
• Maximum compressed file size: 500 MB. Files larger than 500 MB should be split into multiple parts within the same daily drop.
• Do not upload empty files.

Processing status

Taboola evaluates and moves files automatically after processing:

Partial failure handling ingests valid records up to a configured threshold before rejecting the file. If a file lands in error/, fix the formatting issue, append a revision suffix to the filename, and upload as a new file.

🚧

Do not retry with the same filename

Automated retries using the same filename can cause unintended rollback of consent or deletion events. Always upload resubmissions as a new, uniquely named file.

Consent and privacy

The batch path has no browser context, so Taboola cannot read consent signals (GDPR/TCF, CCPA/GPP) from the file data. You are responsible for ensuring that user consent has been obtained before including a user's identifiers in the upload file. Do not include data for users who have opted out or for whom consent is missing.

Onboarding checklist

Review and confirm the following with your Taboola account manager before setup: