Real-time identity sync maps your user identifiers to Taboola's identity graph through browser-based HTTP calls (sync pixels). When the call fires, Taboola reads its own cookie from the browser, pairs it with your identifier from the query string, and writes the mapping immediately.

For the batch file upload alternative (recommended for high-volume integrations), see Server-to-server identity sync - offline (batch).

📘

Three ways to send identity data

	Eids push	Online sync (this page)	Offline sync (batch)
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 assigns a partner name and configures the sync endpoint during onboarding.
2. On your web pages, you fire a sync pixel (HTTP GET) that includes your user identifier as a query parameter.
3. Taboola reads its own cookie from the browser, resolving the Taboola user ID.
4. If both IDs are valid, Taboola writes the pair to the identity graph.
5. Taboola responds with a 1x1 transparent pixel or a 302 redirect (configurable).

📘

Companion client-side step

The real-time sync pixel provides a mapping path alongside the eids push. Use both when you need to map identifier types that are not included in the eids push, or when syncing from pages where the eids push is not implemented.

Supported identifier types

The following identifier types can be passed as query parameters in the sync call:

The exact parameter name(s) are agreed during onboarding. You can send multiple identifier types in a single call.

Onboarding setup

Taboola configures the following during onboarding:

Request format

Single-partner sync

GET https://trc.taboola.com/sg/$PARTNER/1/um/?$PARAM=<your_user_id>

Multi-parameter sync

Send multiple identifier types in a single call:

GET https://trc.taboola.com/sg/$PARTNER/1/um/?hem=<hashed_email>&did=<device_id>

Multi-partner sync (chained)

Chain multiple partner syncs in one call using -- as a separator:

GET https://trc.taboola.com/sg/$PARTNER_A--$PARTNER_B/1/um/?paramA=<id_a>&paramB=<id_b>

If one parameter is missing in a chained call, the missing sub-partner is skipped while the present sub-partner is processed normally.

Validation rules

• Every call must resolve at least 2 distinct IDs: the Taboola cookie ID (resolved automatically from the browser) plus at least 1 partner ID from the query string. Calls that resolve only 1 ID are discarded.
• If hashing is enabled, values must be trimmed, lowercased (for email-derived IDs), and converted to a 64-character lowercase hex SHA-256 string.
• Query parameters must be URL-encoded exactly once. Double-encoded or unencoded reserved characters cause silent drops.

🚧

One cookie touch per call

Exactly one Taboola cookie read occurs per HTTP call, regardless of how many sub-partners or ID parameters are chained in that call.

Initiation modes

Partner-initiated (default)

You fire Taboola's sync pixel on your pages. Taboola resolves the IDs and returns either a 1x1 transparent pixel or a 302 redirect containing the Taboola user ID.

Your page  -->  Taboola endpoint  -->  [identity graph write]  -->  1x1 pixel or 302 redirect

Taboola-initiated

You provide a match URL template. Taboola fires this call when encountering new or unmatched users across its publisher network, replacing <TUID> with the real Taboola user ID:

GET https://publisher.com/match?uuid=<TUID>

Bi-directional

Both modes run concurrently. Recommended only after partner-initiated match rates are verified, as this doubles sync traffic.

Response handling

By default, partner-initiated calls return a 1x1 transparent GIF. If a callback is required, Taboola supports 302 redirect responses:

Static redirect example:

Response: HTTP 302 --> https://publisher.com/match?partner_uid=<taboola_user_id>

Dynamic redirect example:

GET https://trc.taboola.com/sg/$PARTNER/1/um/?hem=<hashed_email>&redir=https%3A%2F%2Fpublisher.com%2Fcb%3Fuid%3D%3CTUID%3E

HTTP 302 --> https://publisher.com/cb?uid=<real_taboola_id>

Hashing requirements

For any PII-derived identifier (e.g. email), apply SHA-256 hashing before sending:

1. Trim leading and trailing whitespace.
2. Convert to lowercase.
3. Hash with SHA-256.
4. The result must be a 64-character lowercase hexadecimal string.

Do not strip dots or + tags from email addresses before hashing.

For code examples, see the hashing section in the client-side integration guide.

Consent and privacy

Because the sync call fires from the browser, Taboola validates consent signals (GDPR/TCF, CCPA/GPP) on every call. If consent is missing or the user has opted out, Taboola will not process the mapping. You are also responsible for ensuring that you only fire the sync pixel for users who have given consent.

Onboarding checklist

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